# tehkst/ai-app-builder-dev architecture

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

- Interactive diagram: https://gitdiagram.com/tehkst/ai-app-builder-dev
- Repository: https://github.com/tehkst/ai-app-builder-dev

## Overview

#### Purpose and Entry Points
This is an AI Software Factory: a Python platform that turns product/company intent into scoped, governed, generated, validated, and deployable applications. The primary HTTP application is `app/main.py`; the platform server surface is `app/platform/server.py`. Operational validation enters through `app/platform/validate_all.py`, with local startup scripts in `scripts/start.sh` and `scripts/bootstrap-local.sh`.

#### API, Identity, and Tenant Boundary
The conventional application API exposes auth, projects, and secrets through `app/api/routes/auth.py`, `app/api/routes/projects.py`, and `app/api/routes/secrets.py`. Platform-specific APIs are separately organized under `app/platform/api/routes.py` and `app/platform/api_gateway/api_router.py`. Authentication, authorization, tenant/organization handling, API keys, JWTs, and audit concerns are centralized in `app/platform/auth/authentication.py`, `app/platform/auth/authorization.py`, and `app/platform/auth/tenant_service.py`; this is the boundary before platform actions or customer data access.

#### Intent, Planning, and Executive Orchestration
Founder/executive requests are interpreted by board-room and decision services, notably `app/platform/board_room/service.py`, `app/platform/board_room/executive_intelligence_orchestrator.py`, and `app/platform/founder_decision/service.py`. Engineering planning decomposes scoped work into graphs and task steps via `app/platform/engineering/task_decomposer.py`, `app/platform/engineering/task_graph_runner.py`, and `app/platform/pmo/planning_engine.py`. The architecture knowledge graph projects repository, symbol, control-flow, infrastructure, and authority information from `app/platform/architecture_knowledge_graph/service.py` and `app/platform/architecture_knowledge_graph/projection.py`.

#### Agent Workforce and Governed Execution
Agent definitions, manifests, registries, and orchestration live in `app/platform/agents/registry.py`, `app/platform/agents/manifest_registry.py`, and `app/platform/agents/orchestrator.py`. Delegation selects and schedules capable agents with approval/escalation controls in `app/platform/delegation/delegation_engine.py` and `app/platform/delegation/approval_gate.py`. Runtime execution uses jobs, queues, workers, provider routing, retries, recovery, and rollback through `app/platform/runtime/execution_engine.py`, `app/platform/runtime/job_queue.py`, and `app/platform/runtime/worker.py`.

#### App Build and Materialization Pipeline
The app-build API supports product scoping, module/workflow generation, generated-file access, preview/runtime execution, repair, and restoration under `app/platform/api/app_build/`. Generation and file output originate from `app/platform/services/app_generation_service.py` and `app/ai/nodes/file_writer.py`; reusable generated SaaS reference assets are in `app/platform/saas_builder/reference_app/`. Materialization is deliberately approval-gated and sandbox-oriented, with services such as `app/platform/services/materialization_execution_gate_service.py`, `app/platform/services/materialization_sandbox_writer_service.py`, and persisted generated-file versions under `app/platform/persistence/model_definitions/generated_files.py`.

#### Persistence, Evidence, and Governance
The core application has SQLAlchemy-style models and Alembic migrations in `app/models/`, `app/core/database.py`, and `migrations/`. Platform persistence defines operational entities—including workflows, approvals, execution, materialization, scoping, and evidence—in `app/platform/persistence/model_definitions/`. Event publication and durable history are handled by `app/platform/events/event_bus.py`, `app/platform/events/durable_store.py`, and lifecycle publishers. Governance policies and evidence/approval authority are implemented in `app/platform/constitution/policy_engine.py` and `app/platform/governance_authorization/service.py`.

#### External Systems and Deployment
The platform integrates LLM providers through `app/core/llm.py` and `app/platform/runtime/provider_router.py`, GitHub through `app/platform/github/client.py` and `app/platform/github_execution/adapter.py`, and Telegram approvals through `app/platform/telegram/client.py`. Secrets/KMS/email boundaries are represented by `app/core/secret_vault.py`, `app/core/kms.py`, and `app/core/email.py`. Deployment targets Docker and GCP Cloud Run, with runtime/deployment logic in `app/platform/deployment/deployment_engine.py`, container configuration in `Dockerfile`, and Cloud Run configuration in `infra/gcp/cloud-run-service.yaml`. PostgreSQL and Redis are material infrastructure assumptions reflected in `docker-compose.yml` and deployment readiness checks.

#### Quality and Operational Feedback
Validation is a first-class release gate: `app/platform/validation/engine.py` and `app/platform/validate_all.py` run deterministic platform checks, while `app/platform/security_report.py` reports generated-app posture. Runtime health, metrics, incidents, and self-healing feed operational recovery through `app/platform/runtime/runtime_monitor.py`, `app/platform/operations/incident_registry.py`, and `app/platform/self_healing/execution_supervisor.py`.

Main entry points: [`app/platform/runtime/execution_engine.py`](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/execution_engine.py) (Execution Runtime), [`app/platform/delegation/delegation_engine.py`](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/delegation/delegation_engine.py) (Delegation & Approvals), [`app/ai/nodes/file_writer.py`](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/ai/nodes/file_writer.py) (Generated File Writer), [`app/platform/services/materialization_execution_gate_service.py`](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/services/materialization_execution_gate_service.py) (Materialization Gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API & Identity"]
  node_http_app["HTTP Application<br/>FastAPI app<br/>[main.py]"]
  node_platform_server["Platform Server<br/>platform API<br/>[server.py]"]
  node_api_routes["Application APIs<br/>route handlers<br/>[auth.py]"]
  node_platform_routes["Platform APIs<br/>route gateway<br/>[routes.py]"]
  node_identity_tenant{{"Identity &amp; Tenant Boundary<br/>auth service<br/>[authentication.py]"}}
end

subgraph group_intelligence["Intent &amp; Planning"]
  node_executive_intelligence["Executive Intelligence<br/>intent orchestration"]
  node_planning_engine["Engineering Planning<br/>work planner<br/>[planning_engine.py]"]
  node_architecture_graph[("Architecture Knowledge Graph<br/>repository intelligence<br/>[projection.py]")]
end

subgraph group_execution["Agent Execution"]
  node_agent_registry["Agent Registry<br/>agent catalog<br/>[registry.py]"]
  node_delegation{{"Delegation &amp; Approvals<br/>governed scheduling"}}
  node_agent_orchestrator["Agent Orchestrator<br/>workforce coordinator<br/>[orchestrator.py]"]
  node_runtime_engine["Execution Runtime<br/>job execution"]
  node_job_queue["Job Queue &amp; Workers<br/>async workers<br/>[job_queue.py]"]
end

subgraph group_build["Build &amp; Governance"]
  node_app_generation["App Generation<br/>generation service"]
  node_file_writer["Generated File Writer<br/>materializer<br/>[file_writer.py]"]
  node_materialization_gate{{"Materialization Gate<br/>approval gate"}}
  node_policy_governance{{"Policy &amp; Governance<br/>policy authority<br/>[policy_engine.py]"}}
end

subgraph group_operations["Persistence &amp; Operations"]
  node_platform_persistence[("Platform Persistence<br/>operational models")]
  node_core_database[("Application Database<br/>SQLAlchemy persistence<br/>[database.py]")]
  node_event_history[("Events &amp; Durable History<br/>event store<br/>[durable_store.py]")]
  node_validation{{"Validation &amp; Security Gate<br/>release validation<br/>[engine.py]"}}
  node_runtime_monitoring["Runtime Monitoring &amp; Healing<br/>operations control<br/>[runtime_monitor.py]"]
end

subgraph group_external["External Delivery"]
  node_provider_router["LLM Provider Routing<br/>AI integration<br/>[provider_router.py]"]
  node_github_adapter["GitHub Execution<br/>source-control integration<br/>[adapter.py]"]
  node_deployment["Deployment Engine<br/>Docker / Cloud Run"]
end

node_http_app -->|"serves"| node_api_routes
node_platform_server -->|"serves"| node_platform_routes
node_api_routes -->|"authenticates through"| node_identity_tenant
node_platform_routes -->|"authorizes through"| node_identity_tenant
node_identity_tenant -->|"scopes requests"| node_executive_intelligence
node_executive_intelligence -->|"creates intent"| node_planning_engine
node_architecture_graph -->|"informs plans"| node_planning_engine
node_planning_engine -->|"submits work"| node_delegation
node_agent_registry -->|"supplies capabilities"| node_delegation
node_delegation -->|"requests approval"| node_policy_governance
node_delegation -->|"assigns approved work"| node_agent_orchestrator
node_agent_orchestrator -->|"dispatches execution"| node_runtime_engine
node_runtime_engine -->|"queues jobs"| node_job_queue
node_runtime_engine -->|"routes AI calls"| node_provider_router
node_runtime_engine -->|"runs generation"| node_app_generation
node_app_generation -->|"emits files"| node_file_writer
node_file_writer -->|"requests materialization"| node_materialization_gate
node_materialization_gate -->|"enforces policy"| node_policy_governance
node_materialization_gate -->|"versions output"| node_platform_persistence
node_runtime_engine -->|"records lifecycle"| node_event_history
node_platform_persistence -->|"provides evidence"| node_event_history
node_file_writer -->|"submits generated app"| node_validation
node_validation -->|"releases validated builds"| node_deployment
node_runtime_engine -->|"reports health"| node_runtime_monitoring
node_runtime_monitoring -.->|"triggers recovery"| node_runtime_engine
node_runtime_engine -->|"executes repository actions"| node_github_adapter
node_core_database -.->|"persists application data"| node_http_app

click node_http_app "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/main.py"
click node_platform_server "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/server.py"
click node_api_routes "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/api/routes/auth.py"
click node_platform_routes "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/api/routes.py"
click node_identity_tenant "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/auth/authentication.py"
click node_executive_intelligence "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/board_room/executive_intelligence_orchestrator.py"
click node_planning_engine "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/pmo/planning_engine.py"
click node_architecture_graph "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/architecture_knowledge_graph/projection.py"
click node_agent_registry "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/agents/registry.py"
click node_delegation "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/delegation/delegation_engine.py"
click node_agent_orchestrator "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/agents/orchestrator.py"
click node_runtime_engine "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/execution_engine.py"
click node_job_queue "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/job_queue.py"
click node_app_generation "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/services/app_generation_service.py"
click node_file_writer "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/ai/nodes/file_writer.py"
click node_materialization_gate "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/services/materialization_execution_gate_service.py"
click node_policy_governance "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/constitution/policy_engine.py"
click node_core_database "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/core/database.py"
click node_event_history "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/events/durable_store.py"
click node_validation "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/validation/engine.py"
click node_runtime_monitoring "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/runtime_monitor.py"
click node_provider_router "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/provider_router.py"
click node_github_adapter "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/github_execution/adapter.py"
click node_deployment "https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/deployment/deployment_engine.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_http_app,node_platform_server,node_api_routes,node_platform_routes,node_identity_tenant toneBlue
class node_executive_intelligence,node_planning_engine,node_architecture_graph toneAmber
class node_agent_registry,node_delegation,node_agent_orchestrator,node_runtime_engine,node_job_queue toneMint
class node_app_generation,node_file_writer,node_materialization_gate,node_policy_governance toneRose
class node_platform_persistence,node_core_database,node_event_history,node_validation,node_runtime_monitoring toneIndigo
class node_provider_router,node_github_adapter,node_deployment toneTeal
```

## Components

### API & Identity

- [HTTP Application](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/main.py): FastAPI app · Conventional customer-facing API entry point. · `app/main.py`
- [Platform Server](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/server.py): platform API · Platform-specific server surface. · `app/platform/server.py`
- [Application APIs](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/api/routes/auth.py): route handlers · Auth, projects, and secrets endpoints. · `app/api/routes/auth.py`
- [Platform APIs](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/api/routes.py): route gateway · Routes app-build and platform actions. · `app/platform/api/routes.py`
- [Identity & Tenant Boundary](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/auth/authentication.py): auth service · Authenticates, authorizes, and scopes tenant access. · `app/platform/auth/authentication.py`

### Intent & Planning

- [Executive Intelligence](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/board_room/executive_intelligence_orchestrator.py): intent orchestration · Interprets founder requests and decisions. · `app/platform/board_room/executive_intelligence_orchestrator.py`
- [Engineering Planning](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/pmo/planning_engine.py): work planner · Scopes work into plans, graphs, and tasks. · `app/platform/pmo/planning_engine.py`
- [Architecture Knowledge Graph](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/architecture_knowledge_graph/projection.py): repository intelligence · Projects code, infrastructure, and authority knowledge. · `app/platform/architecture_knowledge_graph/projection.py`

### Agent Execution

- [Agent Registry](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/agents/registry.py): agent catalog · Agent definitions and manifests. · `app/platform/agents/registry.py`
- [Delegation & Approvals](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/delegation/delegation_engine.py): governed scheduling · Selects agents and enforces escalation controls. · `app/platform/delegation/delegation_engine.py`
- [Agent Orchestrator](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/agents/orchestrator.py): workforce coordinator · Coordinates multi-agent work. · `app/platform/agents/orchestrator.py`
- [Execution Runtime](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/execution_engine.py): job execution · Runs jobs with retries, recovery, and rollback. · `app/platform/runtime/execution_engine.py`
- [Job Queue & Workers](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/job_queue.py): async workers · Durable queued work execution. · `app/platform/runtime/job_queue.py`

### Build & Governance

- [App Generation](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/services/app_generation_service.py): generation service · Generates scoped product modules and workflows. · `app/platform/services/app_generation_service.py`
- [Generated File Writer](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/ai/nodes/file_writer.py): materializer · Writes generated application files. · `app/ai/nodes/file_writer.py`
- [Materialization Gate](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/services/materialization_execution_gate_service.py): approval gate · Approves sandboxed generated-file materialization. · `app/platform/services/materialization_execution_gate_service.py`
- [Policy & Governance](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/constitution/policy_engine.py): policy authority · Evaluates policy, evidence, and approval authority. · `app/platform/constitution/policy_engine.py`

### Persistence & Operations

- **Platform Persistence**: operational models · Stores workflows, approvals, execution, evidence, and generated versions.
- [Application Database](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/core/database.py): SQLAlchemy persistence · Core models and PostgreSQL access. · `app/core/database.py`
- [Events & Durable History](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/events/durable_store.py): event store · Publishes events and retains lifecycle history. · `app/platform/events/durable_store.py`
- [Validation & Security Gate](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/validation/engine.py): release validation · Runs platform checks and generated-app posture reporting. · `app/platform/validation/engine.py`
- [Runtime Monitoring & Healing](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/runtime_monitor.py): operations control · Feeds incidents and self-healing recovery. · `app/platform/runtime/runtime_monitor.py`

### External Delivery

- [LLM Provider Routing](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/runtime/provider_router.py): AI integration · Routes runtime work to LLM providers. · `app/platform/runtime/provider_router.py`
- [GitHub Execution](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/github_execution/adapter.py): source-control integration · Executes governed GitHub operations. · `app/platform/github_execution/adapter.py`
- [Deployment Engine](https://github.com/tehkst/ai-app-builder-dev/blob/main/app/platform/deployment/deployment_engine.py): Docker / Cloud Run · Deploys validated applications. · `app/platform/deployment/deployment_engine.py`

## Connections

- HTTP Application → Application APIs: serves
- Platform Server → Platform APIs: serves
- Application APIs → Identity & Tenant Boundary: authenticates through
- Platform APIs → Identity & Tenant Boundary: authorizes through
- Identity & Tenant Boundary → Executive Intelligence: scopes requests
- Executive Intelligence → Engineering Planning: creates intent
- Architecture Knowledge Graph → Engineering Planning: informs plans
- Engineering Planning → Delegation & Approvals: submits work
- Agent Registry → Delegation & Approvals: supplies capabilities
- Delegation & Approvals → Policy & Governance: requests approval
- Delegation & Approvals → Agent Orchestrator: assigns approved work
- Agent Orchestrator → Execution Runtime: dispatches execution
- Execution Runtime → Job Queue & Workers: queues jobs
- Execution Runtime → LLM Provider Routing: routes AI calls
- Execution Runtime → App Generation: runs generation
- App Generation → Generated File Writer: emits files
- Generated File Writer → Materialization Gate: requests materialization
- Materialization Gate → Policy & Governance: enforces policy
- Materialization Gate → Platform Persistence: versions output
- Execution Runtime → Events & Durable History: records lifecycle
- Platform Persistence → Events & Durable History: provides evidence
- Generated File Writer → Validation & Security Gate: submits generated app
- Validation & Security Gate → Deployment Engine: releases validated builds
- Execution Runtime → Runtime Monitoring & Healing: reports health
- Runtime Monitoring & Healing → Execution Runtime: triggers recovery
- Execution Runtime → GitHub Execution: executes repository actions
- Application Database → HTTP Application: persists application data