# urbanspacebuilderstech-usb/my-home-usb architecture

> Architecture diagram of the GitHub repository urbanspacebuilderstech-usb/my-home-usb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urbanspacebuilderstech-usb/my-home-usb
- Repository: https://github.com/urbanspacebuilderstech-usb/my-home-usb

## Overview

#### 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.

Main entry points: [`backend/main.py`](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/main.py) (FastAPI API), [`frontend/src/App.js`](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/App.js) (Router & auth gate), [`backend/routes/procurement.py`](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/procurement.py) (Procurement & vendors), [`backend/routes/pre_construction.py`](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/pre_construction.py) (Planning & operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa_entry["SPA entry<br/>React bootstrap<br/>[index.js]"]
  node_app_gate["Router &amp; auth gate<br/>React app shell<br/>[App.js]"]
  node_auth_pages["Login &amp; OAuth callback<br/>auth pages<br/>[Login.jsx]"]
  node_crm_ui["CRM &amp; project UI<br/>workspace pages<br/>[CRMPreSales.jsx]"]
  node_planning_ui["Planning &amp; field UI<br/>workspace pages<br/>[PlanningBoard.jsx]"]
  node_procurement_ui["Procurement &amp; vendor UI<br/>workspace pages"]
  node_finance_ui["Accounting &amp; finance UI<br/>workspace pages<br/>[FinanceBoard.jsx]"]
end

subgraph group_backend["FastAPI backend"]
  node_api_server["FastAPI API<br/>server boundary<br/>[main.py]"]
  node_security["Auth &amp; role dependencies<br/>security layer<br/>[security.py]"]
  node_visibility["Contact visibility<br/>access scoping"]
  node_crm_projects["CRM, prospects &amp; projects<br/>domain routes<br/>[projects.py]"]
  node_planning_ops["Planning &amp; operations<br/>domain routes"]
  node_site_ops["Site execution<br/>domain routes<br/>[site_ops.py]"]
  node_procurement["Procurement &amp; vendors<br/>domain routes<br/>[procurement.py]"]
  node_finance["Financial control<br/>domain routes<br/>[financial.py]"]
  node_shared_services["Notifications &amp; counters<br/>shared services<br/>[notifications.py]"]
  node_uploads["Files &amp; uploads<br/>storage routes<br/>[uploads.py]"]
end

subgraph group_data["Data &amp; integrations"]
  node_mongo[("MongoDB<br/>primary database<br/>[database.py]")]
  node_gridfs[("GridFS file storage<br/>object storage<br/>[storage.py]")]
  node_email_oauth{{"Email &amp; Google OAuth<br/>external services"}}
end

node_spa_entry -->|"boots"| node_app_gate
node_app_gate -->|"unauthenticated routes"| node_auth_pages
node_app_gate -->|"role-gated workspace"| node_crm_ui
node_app_gate -->|"role-gated workspace"| node_planning_ui
node_app_gate -->|"role-gated workspace"| node_procurement_ui
node_app_gate -->|"role-gated workspace"| node_finance_ui
node_app_gate -->|"API requests"| node_api_server
node_api_server -->|"authenticates routes"| node_security
node_security -->|"scopes contacts"| node_visibility
node_security -.->|"OAuth / email"| node_email_oauth
node_api_server -->|"routes"| node_crm_projects
node_api_server -->|"routes"| node_planning_ops
node_api_server -->|"routes"| node_site_ops
node_api_server -->|"routes"| node_procurement
node_api_server -->|"routes"| node_finance
node_api_server -->|"shared events"| node_shared_services
node_api_server -->|"file APIs"| node_uploads
node_crm_projects -->|"leads &amp; projects"| node_mongo
node_planning_ops -->|"uses project scope"| node_crm_projects
node_site_ops -->|"executes work orders"| node_planning_ops
node_procurement -->|"approved needs"| node_planning_ops
node_procurement -->|"dispatch &amp; receipt"| node_site_ops
node_procurement -->|"commitments &amp; receipts"| node_finance
node_finance -->|"financial records"| node_mongo
node_procurement -->|"POs, vendors &amp; receipts"| node_mongo
node_uploads -->|"stores evidence"| node_gridfs

click node_spa_entry "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/index.js"
click node_app_gate "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/App.js"
click node_auth_pages "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/Login.jsx"
click node_crm_ui "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/CRMPreSales.jsx"
click node_planning_ui "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/PlanningBoard.jsx"
click node_procurement_ui "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/ProcurementBoardV2.jsx"
click node_finance_ui "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/FinanceBoard.jsx"
click node_api_server "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/main.py"
click node_security "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/security.py"
click node_visibility "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/core/contact_visibility.py"
click node_crm_projects "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/projects.py"
click node_planning_ops "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/pre_construction.py"
click node_site_ops "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/site_ops.py"
click node_procurement "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/procurement.py"
click node_finance "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/financial.py"
click node_shared_services "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/core/notifications.py"
click node_uploads "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/uploads.py"
click node_mongo "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/core/database.py"
click node_gridfs "https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/core/storage.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa_entry,node_app_gate,node_auth_pages,node_crm_ui,node_planning_ui,node_procurement_ui,node_finance_ui toneBlue
class node_api_server,node_security,node_visibility,node_crm_projects,node_planning_ops,node_site_ops,node_procurement,node_finance,node_shared_services,node_uploads toneAmber
class node_mongo,node_gridfs,node_email_oauth toneMint
```

## Components

### React SPA

- [SPA entry](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/index.js): React bootstrap · `frontend/src/index.js`
- [Router & auth gate](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/App.js): React app shell · Composes authenticated and role-specific views. · `frontend/src/App.js`
- [Login & OAuth callback](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/Login.jsx): auth pages · `frontend/src/pages/Login.jsx`
- [CRM & project UI](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/CRMPreSales.jsx): workspace pages · `frontend/src/pages/CRMPreSales.jsx`
- [Planning & field UI](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/PlanningBoard.jsx): workspace pages · `frontend/src/pages/PlanningBoard.jsx`
- [Procurement & vendor UI](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/ProcurementBoardV2.jsx): workspace pages · `frontend/src/pages/ProcurementBoardV2.jsx`
- [Accounting & finance UI](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/frontend/src/pages/FinanceBoard.jsx): workspace pages · `frontend/src/pages/FinanceBoard.jsx`

### FastAPI backend

- [FastAPI API](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/main.py): server boundary · Exposes domain APIs consumed by the SPA. · `backend/main.py`
- [Auth & role dependencies](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/security.py): security layer · Central authentication, authorization, and route dependencies. · `backend/security.py`
- [Contact visibility](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/core/contact_visibility.py): access scoping · `backend/core/contact_visibility.py`
- [CRM, prospects & projects](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/projects.py): domain routes · Converts leads into the shared project lifecycle boundary. · `backend/routes/projects.py`
- [Planning & operations](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/pre_construction.py): domain routes · Creates staged needs, work orders, and approval-controlled operational requests. · `backend/routes/pre_construction.py`
- [Site execution](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/site_ops.py): domain routes · `backend/routes/site_ops.py`
- [Procurement & vendors](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/procurement.py): domain routes · Turns approved needs into vendor selection, POs, dispatch, and receipts. · `backend/routes/procurement.py`
- [Financial control](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/financial.py): domain routes · Records commitments and receipts through approvals and corrections. · `backend/routes/financial.py`
- [Notifications & counters](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/core/notifications.py): shared services · `backend/core/notifications.py`
- [Files & uploads](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/routes/uploads.py): storage routes · Supports receipt evidence such as GPS, images, and files. · `backend/routes/uploads.py`

### Data & integrations

- [MongoDB](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/core/database.py): primary database · Primary persistence for users, projects, operational, procurement, and finance records. · `backend/core/database.py`
- [GridFS file storage](https://github.com/urbanspacebuilderstech-usb/my-home-usb/blob/main/backend/core/storage.py): object storage · `backend/core/storage.py`
- **Email & Google OAuth**: external services · Resend delivers email; Emergent provides Google OAuth.

## Connections

- SPA entry → Router & auth gate: boots
- Router & auth gate → Login & OAuth callback: unauthenticated routes
- Router & auth gate → CRM & project UI: role-gated workspace
- Router & auth gate → Planning & field UI: role-gated workspace
- Router & auth gate → Procurement & vendor UI: role-gated workspace
- Router & auth gate → Accounting & finance UI: role-gated workspace
- Router & auth gate → FastAPI API: API requests
- FastAPI API → Auth & role dependencies: authenticates routes
- Auth & role dependencies → Contact visibility: scopes contacts
- Auth & role dependencies → Email & Google OAuth: OAuth / email
- FastAPI API → CRM, prospects & projects: routes
- FastAPI API → Planning & operations: routes
- FastAPI API → Site execution: routes
- FastAPI API → Procurement & vendors: routes
- FastAPI API → Financial control: routes
- FastAPI API → Notifications & counters: shared events
- FastAPI API → Files & uploads: file APIs
- CRM, prospects & projects → MongoDB: leads & projects
- Planning & operations → CRM, prospects & projects: uses project scope
- Site execution → Planning & operations: executes work orders
- Procurement & vendors → Planning & operations: approved needs
- Procurement & vendors → Site execution: dispatch & receipt
- Procurement & vendors → Financial control: commitments & receipts
- Financial control → MongoDB: financial records
- Procurement & vendors → MongoDB: POs, vendors & receipts
- Files & uploads → GridFS file storage: stores evidence