How tehkst/ai-app-builder-dev works
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: execution_engine.py Execution Runtime · delegation_engine.py Delegation & Approvals · file_writer.py Generated File Writer · materialization_execution_gate_service.py Materialization Gate
Components 25
API & Identity
- HTTP Application · Conventional customer-facing API entry point.
app/main.py - Platform Server · Platform-specific server surface.
app/platform/server.py - Application APIs · Auth, projects, and secrets endpoints.
app/api/routes/auth.py - Platform APIs · Routes app-build and platform actions.
app/platform/api/routes.py - Identity & Tenant Boundary · Authenticates, authorizes, and scopes tenant access.
app/platform/auth/authentication.py
Intent & Planning
- Executive Intelligence · Interprets founder requests and decisions.
app/platform/board_room/executive_intelligence_orchestrator.py - Engineering Planning · Scopes work into plans, graphs, and tasks.
app/platform/pmo/planning_engine.py - Architecture Knowledge Graph · Projects code, infrastructure, and authority knowledge.
app/platform/architecture_knowledge_graph/projection.py
Agent Execution
- Agent Registry · Agent definitions and manifests.
app/platform/agents/registry.py - Delegation & Approvals · Selects agents and enforces escalation controls.
app/platform/delegation/delegation_engine.py - Agent Orchestrator · Coordinates multi-agent work.
app/platform/agents/orchestrator.py - Execution Runtime · Runs jobs with retries, recovery, and rollback.
app/platform/runtime/execution_engine.py - Job Queue & Workers · Durable queued work execution.
app/platform/runtime/job_queue.py
Build & Governance
- App Generation · Generates scoped product modules and workflows.
app/platform/services/app_generation_service.py - Generated File Writer · Writes generated application files.
app/ai/nodes/file_writer.py - Materialization Gate · Approves sandboxed generated-file materialization.
app/platform/services/materialization_execution_gate_service.py - Policy & Governance · Evaluates policy, evidence, and approval authority.
app/platform/constitution/policy_engine.py
Persistence & Operations
- Platform Persistence · Stores workflows, approvals, execution, evidence, and generated versions.
- Application Database · Core models and PostgreSQL access.
app/core/database.py - Events & Durable History · Publishes events and retains lifecycle history.
app/platform/events/durable_store.py - Validation & Security Gate · Runs platform checks and generated-app posture reporting.
app/platform/validation/engine.py - Runtime Monitoring & Healing · Feeds incidents and self-healing recovery.
app/platform/runtime/runtime_monitor.py
External Delivery
- LLM Provider Routing · Routes runtime work to LLM providers.
app/platform/runtime/provider_router.py - GitHub Execution · Executes governed GitHub operations.
app/platform/github_execution/adapter.py - Deployment Engine · Deploys validated applications.
app/platform/deployment/deployment_engine.py
Connections 27
- 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