urbanspacebuilderstech-usb/my-home-usb

Purpose and Entry Points

ConstructionOS is a role-based construction CRM, project-operations, procurement, and accounting system. The browser SPA starts at frontend/src/index.js and composes routing/authenticated views in frontend/src/App.js. The FastAPI backend is entered through backend/main.py/backend/server.py, which expose API routes consumed by the React application.

Application Boundary and Runtime

The frontend is React 19, styled with Tailwind and Shadcn/UI, packaged from frontend/package.json. It presents role-specific dashboards, boards, forms, and client/vendor portals. FastAPI is the server boundary; route modules under backend/routes/ implement domain APIs. MongoDB is the primary persistence store, accessed through backend/core/database.py; GridFS-backed file handling is represented by backend/core/storage.py and upload routes.

Identity, Authorization, and Visibility

Authentication and security controls are centralized around backend/security.py and dependency injection in backend/core/deps.py. User and role records are modeled in backend/models/user.py. Routes enforce role-dependent access across super-admin, accounting, planning, procurement, PM, site engineering, vendor, and client contexts; contact-scoping is isolated in backend/core/contact_visibility.py. The frontend’s route/auth gate is frontend/src/App.js, with login/OAuth callback pages such as frontend/src/pages/Login.jsx and frontend/src/pages/AuthCallback.jsx.

Project Lifecycle and CRM

Lead/prospect conversion and construction project onboarding form the upstream lifecycle. CRM, prospect, and project APIs are separated in backend/routes/crm.py, backend/routes/prospect.py, and backend/routes/projects.py; persistent entities include backend/models/lead.py and backend/models/project.py. Corresponding UI surfaces include frontend/src/pages/CRMPreSales.jsx, frontend/src/pages/CRMSales.jsx, and frontend/src/pages/ProjectDetail.jsx. Project records become the shared foreign-key-like boundary for costing, schedules, site work, procurement, and finance.

Planning, Delivery, and Workflows

Planning converts project scope/BOQ and package requirements into stages, material/labour needs, work orders, and approvals. The core operational APIs are backend/routes/pre_construction.py, backend/routes/operations.py, and backend/routes/site_ops.py; work-order assignment logic also exists in backend/work_order_assignment.py. The UI exposes planning and field execution through frontend/src/pages/PlanningBoard.jsx, frontend/src/pages/WorkOrderManagement.jsx, and frontend/src/pages/SiteEngineerProject.jsx. Approval/status transitions are an important control boundary: downstream procurement or payment should follow approved requests/orders rather than raw planning drafts.

Procurement, Vendors, and Material Receipts

Procurement translates approved needs into vendor selection, purchase orders, dispatch, and site receipt. Its backend boundary is backend/routes/procurement.py, with contractor/vendor management in backend/routes/contractors.py; Mongo dump collections indicate purchase orders, vendor master, price history, material requests, and receipts. Interfaces include frontend/src/pages/ProcurementBoardV2.jsx, frontend/src/pages/VendorPortal.jsx, and frontend/src/pages/MaterialReceipt.jsx. Site receipts can attach GPS/images/files, crossing from business records into storage/upload APIs (backend/routes/uploads.py, backend/routes/files.py).

Financial Control and Accounting

Financial routes cover cash flow, income, expenses, payment schedules/stages, approvals, corrections, and accounting views: backend/routes/financial.py, backend/routes/cashflow.py, and backend/routes/correction_engine.py. UI entry points are frontend/src/pages/AccountantModule.jsx, frontend/src/pages/FinanceBoard.jsx, and frontend/src/pages/PaymentSchedulePage.jsx. The main flow is operational commitments/receipts → financial entries and approval queues → cashbook/dashboard reporting, with correction workflows preserving controlled changes rather than direct ad hoc edits.

Cross-Cutting Services and Operations

Notifications and counters are shared backend services in backend/core/notifications.py and backend/core/counters.py. PDF generation is provided by backend/services/package_pdf.py and backend/generate_api_pdf.py. Resend is the declared email service; Google OAuth is provided by Emergent. Production deployment is automated via .github/workflows/deploy-production.yml, while Mongo migration/repair and seed scripts under backend/ support operational data evolution.