# jeetukashyap1/buildscale architecture

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

- Interactive diagram: https://gitdiagram.com/jeetukashyap1/buildscale
- Repository: https://github.com/jeetukashyap1/buildscale

## Overview

BuildScale Company OS is a multi-tenant business operations platform with a web control plane, agent/workflow execution, and CRM, project-delivery, pricing, and finance capabilities. Users access operational views through the web app and API; governed runtime actions dispatch to domain handlers, where policy, permission, risk, approval, and audit controls constrain consequential changes. The source index documents these broad relationships, but many route and domain implementations were not excerpted; those links are shown only where the index supports them. Web-to-API transport is unverified.

Main entry points: [`api/routes.py`](https://github.com/jeetukashyap1/buildscale/blob/main/api/routes.py) (API routes), [`runtime/handlers.py`](https://github.com/jeetukashyap1/buildscale/blob/main/runtime/handlers.py) (Operation handlers), [`core/governance.py`](https://github.com/jeetukashyap1/buildscale/blob/main/core/governance.py) (Action governance), [`runtime/service.py`](https://github.com/jeetukashyap1/buildscale/blob/main/runtime/service.py) (Runtime service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_webclient["API client<br/>[client.ts]"]
  node_webpages["Operational pages"]
end

subgraph group_control["API control plane"]
  node_api["API routes<br/>[routes.py]"]
  node_agentroutes["Agent routes<br/>[routes_agents.py]"]
  node_crmroute["CRM routes<br/>[routes_crm.py]"]
  node_finroute["Finance routes<br/>[routes_finance.py]"]
  node_pricingroute["Pricing routes<br/>[routes_pricing.py]"]
  node_runtimeapi["Runtime routes<br/>[routes_runtime.py]"]
end

subgraph group_execution["Agent execution"]
  node_runtime["Runtime service<br/>[service.py]"]
  node_handlers["Operation handlers<br/>[handlers.py]"]
  node_automation["Workflow runner<br/>[runner.py]"]
  node_agentcore["Agent runtime<br/>[runtime.py]"]
end

subgraph group_operations["Business operations"]
  node_crm["CRM lifecycle<br/>[leads.py]"]
  node_projects["Project delivery<br/>[tasks.py]"]
  node_finance["Invoices and payments<br/>[payments.py]"]
  node_pricing["Pricing decisions<br/>[pricing.py]"]
end

subgraph group_foundation["Governance and state"]
  node_governance["Action governance<br/>[governance.py]"]
  node_permissions["Permission controls<br/>[permissions.py]"]
  node_policies["Policy registry<br/>[policies.py]"]
  node_audit["Audit trail<br/>[audit.py]"]
  node_memory["Scoped memory<br/>[store.py]"]
  node_models[("Persistent records<br/>[models.py]")]
  node_db["Database sessions<br/>[db.py]"]
end

node_user(("Operator"))

node_user -->|"uses"| node_webapp
node_webapp -->|"renders"| node_webpages
node_webclient -.->|"sends requests"| node_api
node_api -->|"routes to"| node_agentroutes
node_api -->|"routes to"| node_crmroute
node_api -->|"routes to"| node_finroute
node_api -->|"routes to"| node_pricingroute
node_api -->|"routes to"| node_runtimeapi
node_api -->|"uses"| node_runtime
node_runtimeapi -.->|"invokes"| node_runtime
node_runtime -->|"dispatches"| node_handlers
node_runtime -->|"invokes"| node_automation
node_runtime -->|"invokes"| node_agentcore
node_handlers -->|"delegates"| node_crm
node_handlers -->|"delegates"| node_projects
node_handlers -->|"delegates"| node_finance
node_handlers -->|"delegates"| node_pricing
node_handlers -->|"delegates"| node_memory
node_crmroute -->|"calls"| node_crm
node_finroute -->|"calls"| node_finance
node_pricingroute -->|"calls"| node_pricing
node_governance -->|"checks"| node_permissions
node_governance -->|"records"| node_audit
node_governance -->|"consults"| node_policies
node_crm -.->|"governs actions"| node_governance
node_finance -.->|"governs actions"| node_governance
node_projects -.->|"governs actions"| node_governance
node_audit -->|"writes records"| node_models
node_db -->|"creates schema"| node_models
node_memory -->|"persists records"| node_models

click node_webapp "https://github.com/jeetukashyap1/buildscale/blob/main/web/src/App.tsx"
click node_webclient "https://github.com/jeetukashyap1/buildscale/blob/main/web/src/api/client.ts"
click node_webpages "https://github.com/jeetukashyap1/buildscale/tree/main/web/src/pages"
click node_api "https://github.com/jeetukashyap1/buildscale/blob/main/api/routes.py"
click node_agentroutes "https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_agents.py"
click node_crmroute "https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_crm.py"
click node_finroute "https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_finance.py"
click node_pricingroute "https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_pricing.py"
click node_runtimeapi "https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_runtime.py"
click node_runtime "https://github.com/jeetukashyap1/buildscale/blob/main/runtime/service.py"
click node_handlers "https://github.com/jeetukashyap1/buildscale/blob/main/runtime/handlers.py"
click node_automation "https://github.com/jeetukashyap1/buildscale/blob/main/automation/runner.py"
click node_agentcore "https://github.com/jeetukashyap1/buildscale/blob/main/agents/runtime.py"
click node_crm "https://github.com/jeetukashyap1/buildscale/blob/main/crm/leads.py"
click node_projects "https://github.com/jeetukashyap1/buildscale/blob/main/projects/tasks.py"
click node_finance "https://github.com/jeetukashyap1/buildscale/blob/main/finance/payments.py"
click node_pricing "https://github.com/jeetukashyap1/buildscale/blob/main/core/pricing.py"
click node_governance "https://github.com/jeetukashyap1/buildscale/blob/main/core/governance.py"
click node_permissions "https://github.com/jeetukashyap1/buildscale/blob/main/core/permissions.py"
click node_policies "https://github.com/jeetukashyap1/buildscale/blob/main/core/policies.py"
click node_audit "https://github.com/jeetukashyap1/buildscale/blob/main/core/audit.py"
click node_memory "https://github.com/jeetukashyap1/buildscale/blob/main/memory/store.py"
click node_models "https://github.com/jeetukashyap1/buildscale/blob/main/core/models.py"
click node_db "https://github.com/jeetukashyap1/buildscale/blob/main/core/db.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_webapp,node_webclient,node_webpages toneBlue
class node_api,node_agentroutes,node_crmroute,node_finroute,node_pricingroute,node_runtimeapi toneAmber
class node_runtime,node_handlers,node_automation,node_agentcore toneMint
class node_crm,node_projects,node_finance,node_pricing toneRose
class node_governance,node_permissions,node_policies,node_audit,node_memory,node_models,node_db,node_user toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/jeetukashyap1/buildscale/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [API client](https://github.com/jeetukashyap1/buildscale/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Operational pages](https://github.com/jeetukashyap1/buildscale/tree/main/web/src/pages): `web/src/pages`

### API control plane

- [API routes](https://github.com/jeetukashyap1/buildscale/blob/main/api/routes.py): `api/routes.py`
- [Agent routes](https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_agents.py): `api/routes_agents.py`
- [CRM routes](https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_crm.py): `api/routes_crm.py`
- [Finance routes](https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_finance.py): `api/routes_finance.py`
- [Pricing routes](https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_pricing.py): `api/routes_pricing.py`
- [Runtime routes](https://github.com/jeetukashyap1/buildscale/blob/main/api/routes_runtime.py): `api/routes_runtime.py`

### Agent execution

- [Runtime service](https://github.com/jeetukashyap1/buildscale/blob/main/runtime/service.py): `runtime/service.py`
- [Operation handlers](https://github.com/jeetukashyap1/buildscale/blob/main/runtime/handlers.py): `runtime/handlers.py`
- [Workflow runner](https://github.com/jeetukashyap1/buildscale/blob/main/automation/runner.py): `automation/runner.py`
- [Agent runtime](https://github.com/jeetukashyap1/buildscale/blob/main/agents/runtime.py): `agents/runtime.py`

### Business operations

- [CRM lifecycle](https://github.com/jeetukashyap1/buildscale/blob/main/crm/leads.py): `crm/leads.py`
- [Project delivery](https://github.com/jeetukashyap1/buildscale/blob/main/projects/tasks.py): `projects/tasks.py`
- [Invoices and payments](https://github.com/jeetukashyap1/buildscale/blob/main/finance/payments.py): `finance/payments.py`
- [Pricing decisions](https://github.com/jeetukashyap1/buildscale/blob/main/core/pricing.py): `core/pricing.py`

### Governance and state

- [Action governance](https://github.com/jeetukashyap1/buildscale/blob/main/core/governance.py): `core/governance.py`
- [Permission controls](https://github.com/jeetukashyap1/buildscale/blob/main/core/permissions.py): `core/permissions.py`
- [Policy registry](https://github.com/jeetukashyap1/buildscale/blob/main/core/policies.py): `core/policies.py`
- [Audit trail](https://github.com/jeetukashyap1/buildscale/blob/main/core/audit.py): `core/audit.py`
- [Scoped memory](https://github.com/jeetukashyap1/buildscale/blob/main/memory/store.py): `memory/store.py`
- [Persistent records](https://github.com/jeetukashyap1/buildscale/blob/main/core/models.py): `core/models.py`
- [Database sessions](https://github.com/jeetukashyap1/buildscale/blob/main/core/db.py): `core/db.py`

### Other components

- **Operator**

## Connections

- Operator → Web application: uses (evidence: `web/src/App.tsx`)
- Web application → Operational pages: renders (evidence: `web/src/App.tsx`)
- API client → API routes: sends requests
- API routes → Agent routes: routes to (evidence: `api/routes.py`)
- API routes → CRM routes: routes to (evidence: `api/routes.py`)
- API routes → Finance routes: routes to (evidence: `api/routes.py`)
- API routes → Pricing routes: routes to (evidence: `api/routes.py`)
- API routes → Runtime routes: routes to (evidence: `api/routes.py`)
- API routes → Runtime service: uses (evidence: `api/routes.py`)
- Runtime routes → Runtime service: invokes
- Runtime service → Operation handlers: dispatches (evidence: `runtime/service.py`)
- Runtime service → Workflow runner: invokes (evidence: `runtime/service.py`)
- Runtime service → Agent runtime: invokes (evidence: `runtime/service.py`)
- Operation handlers → CRM lifecycle: delegates (evidence: `runtime/handlers.py`)
- Operation handlers → Project delivery: delegates (evidence: `runtime/handlers.py`)
- Operation handlers → Invoices and payments: delegates (evidence: `runtime/handlers.py`)
- Operation handlers → Pricing decisions: delegates (evidence: `runtime/handlers.py`)
- Operation handlers → Scoped memory: delegates (evidence: `runtime/handlers.py`)
- CRM routes → CRM lifecycle: calls (evidence: `api/routes_crm.py`)
- Finance routes → Invoices and payments: calls (evidence: `api/routes_finance.py`)
- Pricing routes → Pricing decisions: calls (evidence: `api/routes_pricing.py`)
- Action governance → Permission controls: checks (evidence: `core/governance.py`)
- Action governance → Audit trail: records (evidence: `core/governance.py`)
- Action governance → Policy registry: consults (evidence: `core/governance.py`)
- CRM lifecycle → Action governance: governs actions (evidence: `crm/leads.py`)
- Invoices and payments → Action governance: governs actions (evidence: `finance/payments.py`)
- Project delivery → Action governance: governs actions (evidence: `projects/tasks.py`)
- Audit trail → Persistent records: writes records (evidence: `core/audit.py`)
- Database sessions → Persistent records: creates schema (evidence: `core/db.py`)
- Scoped memory → Persistent records: persists records (evidence: `memory/store.py`)
