How shxrox/buildsure-ai works
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: FloorPlanPage.tsx Planning workspace views · AppRoutes.tsx App routes · index.ts Route registry · project.controller.ts Project controller
Components 22
React client
- Vite entry
frontend/src/main.tsx - App shell
frontend/src/App.tsx - App routes · Defines authenticated and role-aware access paths.
frontend/src/routes/AppRoutes.tsx - Session and route gates
frontend/src/context/AuthContext.tsx - Project workspace · Hosts project-scoped planning tools and views.
frontend/src/components/project/ProjectLayout.tsx - Planning workspace views · Floor plan, blueprint, BOQ, cost, timeline, and AI render stages.
frontend/src/pages/project/FloorPlanPage.tsx - Blueprint canvas
frontend/src/components/blueprint/BlueprintCanvas.tsx - Pricing and volumetrics
frontend/src/utils/pricingEngine.ts - Project API service
frontend/src/services/project.service.ts - Axios client
frontend/src/api/axios.ts
Express API
- API bootstrap
backend/src/server.ts - Express application
backend/src/app.ts - Route registry
backend/src/routes/index.ts - Auth and entitlement · Establishes Clerk identity, role, and subscription access.
backend/src/middleware/auth.middleware.ts - Project controller
backend/src/controllers/project.controller.ts - Project model
backend/src/models/project.model.ts - User model
backend/src/models/user.model.ts - Upload middleware · Accepts project uploads before association with project data.
backend/src/middleware/upload.middleware.ts
AI service
- AI service entry
ai-service/app/main.py - AI pipeline
ai-service/app/pipeline.py
Other components
- Database
backend/src/config/database.ts - Cloudinary
backend/src/config/cloudinary.ts
Connections 22
- 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