Statement of Work — PS Construction CRM Project Name: PS Construction — Construction Project Management CRM
Client: PS Construction (construction company)
Developer: Hybrid Interactive
Date: 9 April 2026
PS Construction CRM is a full-stack web application for managing the end-to-end lifecycle of construction projects — from lead capture and quotation through project execution, labour/vendor management, procurement, billing, accounting, and payroll. The system serves five user roles (Super Admin, Admin, Site Supervisor, Estimator, Client) with role-based dashboards and granular permission controls across 93 backend permissions.
Layer
Technology
Frontend Next.js 16, React 19, TypeScript 5, Tailwind CSS v4, Zustand, TanStack React Query, Framer Motion 12, Zod 4
Backend Python 3.11+, FastAPI, SQLAlchemy 2.0 (async), Pydantic v2, Alembic
Database PostgreSQL 16
Cache / Queue Redis 7 (caching + Celery broker)
Background Jobs Celery + Flower monitoring
File Storage S3-compatible object storage (DigitalOcean Spaces)
Auth JWT (access + refresh tokens), httpOnly cookies, RBAC
Monitoring Prometheus metrics, rotating file logs
Infrastructure Docker Compose (multi-container), multi-stage Dockerfile
Backend: Modular monolith following Domain-Driven Design (DDD). Each business domain is a self-contained module with its own models, schemas, CRUD, services, routes, permissions, and enums. Strict 3-layer architecture: Routes → Services (transaction owner) → CRUD (DB queries only).
Frontend: Next.js App Router with module-driven architecture. Each domain has a collocated lib/<domain>/ directory (api, types, hooks, store, transformers). UI state via Zustand, server state via React Query. Permission-gated pages and navigation.
4. Modules & Scope of Work 4.1 Lead Management (CRM Pipeline) Full lead-to-project conversion pipeline.
Feature
Description
Lead Capture Create/edit leads (individual or business type) with contact info, location, service type, estimation cost, source tracking
Follow-Ups Log follow-up calls, meetings, and emails against leads
Status Pipeline Lead lifecycle: New → Contacted → Qualified → Quotation/Design Quote → Converted → Deal Won/Lost
Quotations BOQ-based quotations linked to leads, with line items, measurements, site images, approval workflow, client status tracking
Design Quotations Area-based design quotations with stages (concept, 3D, working drawings) and payment milestones
Deals Won deals tracked with stage management (active, on_hold, completed, cancelled)
Lead → Project Automatic project creation from won deals
4.2 Project Management (Core Module) Central module managing the full lifecycle of construction projects.
Feature
Description
Project CRUD Create/edit projects with name, client, location, type (residential/commercial/infrastructure/industrial), build-up area, dates, budget fields
Dashboard Views Grid, table, and Kanban board views with status filters and search
Project Detail 8-tab detail view: Labour, Vendors, Purchases, Documents, Billing, Subcontracts, Finance, Meetings
Project Members Assign system users (Admin/Supervisor/Estimator) to projects with role-scoped data access
Auto-Generated Code Unique project code auto-generated from project name
Progress Tracking Computed progress percentage based on start/end dates (not stored, calculated on read)
Project Status Lifecycle: Not Started → In Progress → Completed / On Hold / Cancelled
Two-layer system: master registry (independent) + project-scoped operations.
Feature
Description
Labour Types Dynamic trade categories (Mason, Electrician, Plumber, etc.) with 3-tier skill-level rates (skilled, semi-skilled, unskilled) — each with daily rate and overtime rate
Labour Registry Worker master data: name, phone, address, bank details, linked labour type & skill category, active/inactive status
Project Assignments Assign workers to projects with date ranges; rates snapshotted at assignment creation (immutable historical record)
Batch Assignment Assign up to 50 workers to a project in a single operation
Contract Head Designate one contract head per labour type per project
Daily Attendance Mark daily attendance: present, absent, half-day with overtime hours. Bulk attendance for multiple workers per date (muster roll)
Wage Calculation Formula: earned = (present_days × daily_rate) + (half_days × 0.5 × daily_rate) + (total_OT_hours × OT_rate)
Wage Disbursement Record payments (cash, bank transfer, UPI, cheque) with period snapshots. Track earned vs paid vs balance
Feature
Description
Vendor Registry Master vendor directory: name, company, type (Material Supplier/Service Provider/Subcontractor/Equipment Supplier), GST, PAN, bank details
Project Assignment Link vendors to specific projects
Vendor Payments Payment tracking and history per vendor
Status Management Active/inactive vendor lifecycle
Feature
Description
Material Master Registry of materials with name, category, unit, base quantity
Project Materials Project-specific material tracking with quantity management
Stock Transactions Record stock movements: purchase_in, site_consumption, transfer_in/out, adjustment, wastage
Material Transfers Transfer materials between projects/sites with audit trail
Full procurement workflow: PR → PO → Goods Receipt → Payment.
Feature
Description
Purchase Requests (PR) Internal material/service requests with line items, linked to project/vendor. Approval/rejection workflow
Purchase Orders (PO) Auto-generated from approved PRs. Line items with unit price, quantity, tax
Purchase Records Goods receipt tracking against POs with line-item matching
Purchase Payments Payment recording against purchase records with method tracking
Delivery Challans Post-delivery documentation with transport details
4.7 Bill of Quantities (BOQ Library)
Feature
Description
BOQ Item Library Reusable work item templates with description, unit, rate, category
Category Management Group BOQ items by work category
Quotation Integration BOQ items used as line items in project quotations
Feature
Description
Work Logs Time/labour tracking tied to project assignments. Line-item detail
Invoices Generated from work logs with payment status tracking (draft/sent/paid/overdue)
Expenses Project expense recording with categories, attachments, and purchaser tracking
Expense Settlements Settlement records for expense reimbursements
Finance Summary Consolidated financial overview per project
Finance Analytics Dashboard analytics for financial KPIs
4.9 Accounting (Double-Entry Bookkeeping)
Feature
Description
Chart of Accounts Hierarchical CoA with groups (Assets, Liabilities, Equity, Revenue, Expenses) and sub-types. Parent-child relationships. Soft delete
Voucher Types Payment (PV), Receipt (RV), Contra (CV), Journal (JV), Purchase (PURV), Sales (SLV) with auto-generated sequential numbering
Voucher Lifecycle Draft → Posted → Cancelled. Double-entry enforcement (debit total = credit total, tolerance ±0.005)
Trial Balance Cumulative balance report for all accounts
Profit & Loss Period-bounded income statement with gross profit and net profit
Balance Sheet Point-in-time statement: Assets = Liabilities + Equity + Net Profit
General Ledger Per-account transaction detail with running balance
Cash Flow Statement Operating / Investing / Financing activities (direct method)
4.10 Human Resource Management (HRM) Manages company employees (distinct from daily-wage site labour).
Feature
Description
Departments & Designations Organizational structure setup
Employee Management Employee records with personal info, employment type (full_time/part_time/contract/intern), salary (monthly/daily/hourly), department, designation, optional platform user link
Shift Management Fixed and flexible shift patterns with grace periods, auto-clock-out, break time
Daily Attendance Clock-in/out with status auto-derivation (present/absent/late/half_day/on_leave/holiday/incomplete). Geolocation + IP logging
Weekly/Monthly Summaries Aggregated attendance data via scheduled Celery jobs
Leave Types Configurable leave categories with balance intervals (monthly/yearly/no_interval)
Leave Applications Request-approval workflow: Pending → Approved / Rejected / Withdrawn. Holiday exclusion from leave balance
Holiday Calendar System and optional company holidays
Salary / Payroll Salary computation with formula: payable_days × per_day_rate. Draft → Finalized records
4.11 Subcontract Management
Feature
Description
Subcontracts Work package definition with scope, amount, dates linked to projects
Subcontract Payments Payment milestones: advance, RA bill, retention, final settlement
4.12 Additional Project Features
Feature
Description
Project Documents File upload/download with S3 storage, cross-project document management
Project Meetings Meeting scheduling and recording per project
Project Insurance Insurance policy tracking per project
Daily Logs Daily site activity log entries
4.13 Partner Company Management
Feature
Description
Partner Companies Master registry of partner/subcontractor firms with contact and bank details
Feature
Description
Bank Account Master Manage bank accounts (savings, current, overdraft) linked to projects or org
4.15 User & Access Control
Feature
Description
Authentication JWT-based login with access + refresh tokens, httpOnly cookies, password hashing
User Management CRUD for system users with profile, status (active/inactive/suspended/pending), department
5 Default Roles Super Admin, Admin, Site Supervisor, Estimator, Client — with scope-based data filtering
93 Permissions Granular resource:action format. Roles are composable (users can hold multiple roles)
Dynamic Roles Admins can create custom roles via API
Permission-Gated UI Navigation, pages, and actions filtered by current user's permissions
Feature
Description
Activity Logs Append-only audit trail: all CRUD operations logged with actor, resource, project, timestamp, IP address
Release Notes "What's New" system for publishing feature announcements and changelogs
Dark/Light Theme User-togglable theme with CSS custom properties
Responsive Design Mobile dock navigation with overflow drawer, iOS safe-area support
PDF Generation Report export to PDF (jsPDF + ReportLab)
Prometheus Metrics Backend observability via /metrics endpoint
5. User Roles & Permissions Summary
Role
Scope
Access
Super Admin Global
Full system access including role/permission management
Admin Global
All operational features, user management; no role management
Site Supervisor Assigned Projects
View all data; manage labour, attendance, documents for assigned projects
Estimator Assigned Projects
View projects; manage costing, BOQ, labour estimates
Client Own Projects
Read-only access to own project data and documents
6. Current Implementation Status
Module
Backend
Frontend
Notes
Authentication & RBAC
✅ Complete
✅ Complete
JWT + 93 permissions + 5 roles
Lead Management
✅ Complete
✅ Complete
Full pipeline: leads → quotations → deals
Project Management
✅ Complete
✅ Complete
Dashboard + 8-tab detail view
Labour Types & Registry
✅ Complete
✅ Complete
Master data CRUD
Project Labour (Assignments)
✅ Complete
✅ Complete
Batch assign, contract heads
Labour Attendance
✅ Complete
✅ Complete
Daily + bulk muster roll
Wage Disbursement
✅ Complete
✅ Complete
Period-based processing
Vendor Management
✅ Complete
✅ Complete
Registry + payments
Material Management
✅ Complete
✅ Complete
Inventory + transfers + transactions
Purchase Management
✅ Complete
✅ Complete
PR → PO → Receipt → Payment
BOQ Library
✅ Complete
✅ Complete
Item library + categories
Billing & Finance
✅ Complete
✅ Complete
Work logs, invoices, expenses
Accounting
✅ Complete
✅ Complete
CoA, vouchers, 5 reports
HRM
✅ Complete
✅ Complete
Employees, attendance, leaves, payroll
Subcontracts
✅ Complete
✅ Complete
Work packages + payments
Partner Companies
✅ Complete
✅ Complete
Master data CRUD
Bank Accounts
✅ Complete
✅ Complete
Account management
User Management
✅ Complete
✅ Complete
CRUD + profiles
Access Control
✅ Complete
✅ Complete
Role/permission matrix UI
Activity Logs
✅ Complete
✅ Complete
Audit trail viewer
Documents / Meetings / Insurance
✅ Complete
✅ Complete
Project sub-features
Daily Logs
✅ Complete
✅ Complete
Site activity logging
Release Notes
✅ Complete
—
Backend only, no frontend UI
HRM Biometric Integration
📋 Planned
—
Phase 4: third-party device API
Labour Head System
⚠️ Needs Fixes⚠️ Needs Fixes1 critical + 4 high-priority issues identified
7. Infrastructure & Deployment
Component
Configuration
Application FastAPI served via Uvicorn/Gunicorn behind Docker
Database PostgreSQL 16 (Alpine) with persistent volume
Cache Redis 7 (Alpine) with AOF persistence
Background Workers Celery worker + Flower monitoring UI
File Storage DigitalOcean Spaces (S3-compatible)
Frontend Hosting Next.js (to be deployed; Vercel or self-hosted)
Migrations Alembic (async) — run at startup or manually
Seeding Idempotent role/permission seeder runs at app startup
Logging Rotating file logs (5 files) + colored console output
Health Check /health endpoint for container orchestration
Rate Snapshotting — Labour wage rates are copied from the LabourType at assignment creation and never change, preserving historical accuracyDouble-Entry Enforcement — Every accounting voucher must balance (debit total = credit total)Unique Attendance — Only one attendance record per worker per project per dateScope-Based Filtering — Site Supervisors and Estimators see only their assigned projects; Clients see only their own projectsApproval Workflows — Purchase Requests, Quotations, and Leave Applications require explicit approval before progressingCascading Deletes — Deleting a project cascades to assignments, attendance, and wage recordsOne Contract Head — Only one active contract head per labour type per project at any time
Backend API — FastAPI application with all modules listed in Section 4, deployed via Docker ComposeFrontend Application — Next.js web application with responsive dashboard, all module UIs, and RBACDatabase — PostgreSQL schema with Alembic migrations, seeded roles/permissionsDocumentation — Developer guides, module specs, API documentation (Swagger/ReDoc auto-generated)Docker Configuration — Production-ready docker-compose with all services (API, DB, Redis, Celery, Flower)Deployment Scripts — Setup scripts, environment configuration templates
10. Out of Scope (Future Considerations)
Fiscal year closing entries & year-end processing
Foreign currency support in accounting
Multi-tenancy (currently single-tenant)
Mobile native app (currently responsive web only)
SMS/email notification system
Third-party biometric device integration (planned as HRM Phase 4)
Advanced analytics / BI dashboards
Equipment management module
Client portal (dedicated client-facing app)
