# shxrox/buildsure-ai architecture

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

- Interactive diagram: https://gitdiagram.com/shxrox/buildsure-ai
- Repository: https://github.com/shxrox/buildsure-ai

## Overview

#### Purpose and System Shape
BuildSure-AI is a construction/project-planning platform with a React client, TypeScript/Express API, and Python AI service. The frontend exposes homeowner, contractor, admin, and shared project workspaces, including floor plans, blueprints, costs, BOQ, timeline, reports, pricing, collaboration, and AI rendering.

#### Runtime Entry Points
- React/Vite client starts at `frontend/src/main.tsx`, composes the application in `frontend/src/App.tsx`, and defines navigation/access routing in `frontend/src/routes/AppRoutes.tsx`.
- Express backend is bootstrapped by `backend/src/server.ts`; application and route mounting are in `backend/src/app.ts` and `backend/src/routes/index.ts`.
- Python AI service enters through `ai-service/app/main.py`; its processing orchestration is in `ai-service/app/pipeline.py`.

#### Identity, Roles, and Access Boundary
Clerk is the identity provider on both client and server, configured in `frontend/src/config/clerk.ts` and `backend/src/config/clerk.ts`. Backend authentication establishes the request identity before role and subscription checks in `backend/src/middleware/auth.middleware.ts`, `backend/src/middleware/role.middleware.ts`, and `backend/src/middleware/subscription.middleware.ts`. The UI mirrors this with authenticated and role-specific route gates in `frontend/src/components/admin/AdminRoute.tsx` and `frontend/src/routes/RoleRoute.tsx`.

#### Project Domain and Persistence
Projects and users are the core persisted domain objects, represented by `backend/src/models/project.model.ts` and `backend/src/models/user.model.ts`. HTTP controllers own project/user request handling in `backend/src/controllers/project.controller.ts` and `backend/src/controllers/user.controller.ts`; routes expose those capabilities through `backend/src/routes/project.routes.ts` and `backend/src/routes/user.routes.ts`. Database connection infrastructure is isolated in `backend/src/config/database.ts`.

#### Frontend Project Workspace
The project workspace is a nested UI shell built around `frontend/src/components/project/ProjectLayout.tsx`, `frontend/src/components/project/ProjectHeader.tsx`, and `frontend/src/components/project/ProjectSidebar.tsx`. Feature pages are independently routed workspace stages, notably `frontend/src/pages/project/FloorPlanPage.tsx`, `frontend/src/pages/project/BlueprintPage.tsx`, and `frontend/src/pages/project/AiRenderStudio.tsx`. Project API access is centralized through `frontend/src/services/project.service.ts` over the Axios client in `frontend/src/api/axios.ts`.

#### Planning, Estimation, and Visualization
The browser contains planning/estimation logic for pricing and volumetric calculations in `frontend/src/utils/pricingEngine.ts` and `frontend/src/utils/volumetricEngine.ts`. Visual blueprint interaction is concentrated in `frontend/src/components/blueprint/BlueprintCanvas.tsx`; corresponding project views include `frontend/src/pages/project/BOQPage.tsx`, `frontend/src/pages/project/CostPage.tsx`, and `frontend/src/pages/project/TimelinePage.tsx`. These appear to consume or derive project-scoped data rather than representing separate backend services.

#### External Storage and AI Processing
Cloudinary is the media/upload boundary, configured in `backend/src/config/cloudinary.ts` and reached through `backend/src/middleware/upload.middleware.ts`; project uploads likely enter the backend before being associated with project data. AI-specific work is separated from the Node API in `ai-service/app/pipeline.py`, with utilities in `ai-service/app/utils.py`. The repository does not show an explicit backend-to-AI client or route, so that integration contract is a key boundary to verify before extending AI-render flows.

#### Cross-Cutting API Behavior
The backend standardizes response and failure paths through `backend/src/utils/apiResponse.ts`, `backend/src/middleware/error.middleware.ts`, and `backend/src/middleware/notFound.middleware.ts`. Client session state is maintained in `frontend/src/context/AuthContext.tsx`. Primary control flow is: Clerk-authenticated UI → Axios/service layer → Express auth/authorization → controllers/models/database or Cloudinary; AI rendering additionally crosses into the standalone Python service.

Main entry points: [`frontend/src/pages/project/FloorPlanPage.tsx`](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/pages/project/FloorPlanPage.tsx) (Planning workspace views), [`frontend/src/routes/AppRoutes.tsx`](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/routes/AppRoutes.tsx) (App routes), [`backend/src/routes/index.ts`](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/routes/index.ts) (Route registry), [`backend/src/controllers/project.controller.ts`](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/controllers/project.controller.ts) (Project controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_client_entry["Vite entry<br/>React bootstrap<br/>[main.tsx]"]
  node_client_app["App shell<br/>React composition<br/>[App.tsx]"]
  node_client_routes["App routes<br/>navigation<br/>[AppRoutes.tsx]"]
  node_client_auth["Session and route gates<br/>access control<br/>[AuthContext.tsx]"]
  node_workspace["Project workspace<br/>nested UI shell<br/>[ProjectLayout.tsx]"]
  node_project_views["Planning workspace views<br/>project features<br/>[FloorPlanPage.tsx]"]
  node_blueprint_canvas["Blueprint canvas<br/>visual editor"]
  node_estimation["Pricing and volumetrics<br/>browser calculation<br/>[pricingEngine.ts]"]
  node_project_api["Project API service<br/>client data access<br/>[project.service.ts]"]
  node_axios["Axios client<br/>HTTP client<br/>[axios.ts]"]
end

subgraph group_backend["Express API"]
  node_server["API bootstrap<br/>Express entry point<br/>[server.ts]"]
  node_api_app["Express application<br/>middleware host<br/>[app.ts]"]
  node_api_routes["Route registry<br/>route mounting<br/>[index.ts]"]
  node_authorization["Auth and entitlement<br/>request boundary<br/>[auth.middleware.ts]"]
  node_project_controller["Project controller<br/>HTTP controller"]
  node_project_model["Project model<br/>domain model<br/>[project.model.ts]"]
  node_user_model["User model<br/>domain model<br/>[user.model.ts]"]
  node_uploads["Upload middleware<br/>media ingress"]
end

subgraph group_ai["AI service"]
  node_ai_main["AI service entry<br/>Python entry point<br/>[main.py]"]
  node_ai_pipeline["AI pipeline<br/>processing orchestration<br/>[pipeline.py]"]
end

node_database[("Database<br/>persistence<br/>[database.ts]")]
node_cloudinary[("Cloudinary<br/>media storage<br/>[cloudinary.ts]")]

node_client_entry -->|"starts"| node_client_app
node_client_app -->|"renders"| node_client_routes
node_client_routes -->|"enforces access"| node_client_auth
node_client_routes -->|"opens project routes"| node_workspace
node_workspace -->|"hosts"| node_project_views
node_project_views -->|"uses"| node_blueprint_canvas
node_project_views -->|"derives estimates"| node_estimation
node_project_views -->|"loads and saves"| node_project_api
node_project_api -->|"uses"| node_axios
node_axios -->|"HTTPS requests"| node_server
node_server -->|"boots"| node_api_app
node_api_app -->|"mounts"| node_api_routes
node_api_routes -->|"passes through"| node_authorization
node_authorization -->|"authorizes"| node_project_controller
node_project_controller -->|"reads and writes"| node_project_model
node_project_controller -->|"uses ownership data"| node_user_model
node_project_model -->|"persists to"| node_database
node_user_model -->|"persists to"| node_database
node_api_routes -->|"handles upload routes"| node_uploads
node_uploads -->|"stores media"| node_cloudinary
node_project_views -.->|"AI render boundary to verify"| node_ai_main
node_ai_main -->|"runs"| node_ai_pipeline

click node_client_entry "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/main.tsx"
click node_client_app "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/App.tsx"
click node_client_routes "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/routes/AppRoutes.tsx"
click node_client_auth "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/context/AuthContext.tsx"
click node_workspace "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/components/project/ProjectLayout.tsx"
click node_project_views "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/pages/project/FloorPlanPage.tsx"
click node_blueprint_canvas "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/components/blueprint/BlueprintCanvas.tsx"
click node_estimation "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/utils/pricingEngine.ts"
click node_project_api "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/services/project.service.ts"
click node_axios "https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/api/axios.ts"
click node_server "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/server.ts"
click node_api_app "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/app.ts"
click node_api_routes "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/routes/index.ts"
click node_authorization "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/middleware/auth.middleware.ts"
click node_project_controller "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/controllers/project.controller.ts"
click node_project_model "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/models/project.model.ts"
click node_user_model "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/models/user.model.ts"
click node_database "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/config/database.ts"
click node_uploads "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/middleware/upload.middleware.ts"
click node_cloudinary "https://github.com/shxrox/buildsure-ai/blob/main/backend/src/config/cloudinary.ts"
click node_ai_main "https://github.com/shxrox/buildsure-ai/blob/main/ai-service/app/main.py"
click node_ai_pipeline "https://github.com/shxrox/buildsure-ai/blob/main/ai-service/app/pipeline.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_client_entry,node_client_app,node_client_routes,node_client_auth,node_workspace,node_project_views,node_blueprint_canvas,node_estimation,node_project_api,node_axios toneBlue
class node_server,node_api_app,node_api_routes,node_authorization,node_project_controller,node_project_model,node_user_model,node_uploads toneAmber
class node_ai_main,node_ai_pipeline toneMint
class node_database,node_cloudinary toneNeutral
```

## Components

### React client

- [Vite entry](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/main.tsx): React bootstrap · `frontend/src/main.tsx`
- [App shell](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/App.tsx): React composition · `frontend/src/App.tsx`
- [App routes](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/routes/AppRoutes.tsx): navigation · Defines authenticated and role-aware access paths. · `frontend/src/routes/AppRoutes.tsx`
- [Session and route gates](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/context/AuthContext.tsx): access control · `frontend/src/context/AuthContext.tsx`
- [Project workspace](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/components/project/ProjectLayout.tsx): nested UI shell · Hosts project-scoped planning tools and views. · `frontend/src/components/project/ProjectLayout.tsx`
- [Planning workspace views](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/pages/project/FloorPlanPage.tsx): project features · Floor plan, blueprint, BOQ, cost, timeline, and AI render stages. · `frontend/src/pages/project/FloorPlanPage.tsx`
- [Blueprint canvas](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/components/blueprint/BlueprintCanvas.tsx): visual editor · `frontend/src/components/blueprint/BlueprintCanvas.tsx`
- [Pricing and volumetrics](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/utils/pricingEngine.ts): browser calculation · `frontend/src/utils/pricingEngine.ts`
- [Project API service](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/services/project.service.ts): client data access · `frontend/src/services/project.service.ts`
- [Axios client](https://github.com/shxrox/buildsure-ai/blob/main/frontend/src/api/axios.ts): HTTP client · `frontend/src/api/axios.ts`

### Express API

- [API bootstrap](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/server.ts): Express entry point · `backend/src/server.ts`
- [Express application](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/app.ts): middleware host · `backend/src/app.ts`
- [Route registry](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/routes/index.ts): route mounting · `backend/src/routes/index.ts`
- [Auth and entitlement](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/middleware/auth.middleware.ts): request boundary · Establishes Clerk identity, role, and subscription access. · `backend/src/middleware/auth.middleware.ts`
- [Project controller](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/controllers/project.controller.ts): HTTP controller · `backend/src/controllers/project.controller.ts`
- [Project model](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/models/project.model.ts): domain model · `backend/src/models/project.model.ts`
- [User model](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/models/user.model.ts): domain model · `backend/src/models/user.model.ts`
- [Upload middleware](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/middleware/upload.middleware.ts): media ingress · Accepts project uploads before association with project data. · `backend/src/middleware/upload.middleware.ts`

### AI service

- [AI service entry](https://github.com/shxrox/buildsure-ai/blob/main/ai-service/app/main.py): Python entry point · `ai-service/app/main.py`
- [AI pipeline](https://github.com/shxrox/buildsure-ai/blob/main/ai-service/app/pipeline.py): processing orchestration · `ai-service/app/pipeline.py`

### Other components

- [Database](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/config/database.ts): persistence · `backend/src/config/database.ts`
- [Cloudinary](https://github.com/shxrox/buildsure-ai/blob/main/backend/src/config/cloudinary.ts): media storage · `backend/src/config/cloudinary.ts`

## Connections

- Vite entry → App shell: starts
- App shell → App routes: renders
- App routes → Session and route gates: enforces access
- App routes → Project workspace: opens project routes
- Project workspace → Planning workspace views: hosts
- Planning workspace views → Blueprint canvas: uses
- Planning workspace views → Pricing and volumetrics: derives estimates
- Planning workspace views → Project API service: loads and saves
- Project API service → Axios client: uses
- Axios client → API bootstrap: HTTPS requests
- API bootstrap → Express application: boots
- Express application → Route registry: mounts
- Route registry → Auth and entitlement: passes through
- Auth and entitlement → Project controller: authorizes
- Project controller → Project model: reads and writes
- Project controller → User model: uses ownership data
- Project model → Database: persists to
- User model → Database: persists to
- Route registry → Upload middleware: handles upload routes
- Upload middleware → Cloudinary: stores media
- Planning workspace views → AI service entry: AI render boundary to verify · No explicit Node API-to-AI integration is shown.
- AI service entry → AI pipeline: runs