Codegen Orchestrator

A person describes a project in Telegram. Twenty to thirty minutes later that project is running in production, with a repository, CI, a domain and a certificate. Between those two moments no human touches anything.

The system is a set of agents built on LangGraph. A Product Owner agent runs the dialogue and decides what to build; an architect splits the result into tasks; coding agents in isolated containers write the code; the pipeline puts it through CI, deploy and post-release QA. The user comes back and says "now make it send pictures of cats", and the same machinery extends the running project rather than generating a new one.

Generated projects are built from service-template, a spec-first framework, so the pipeline reasons about a declared contract instead of guessing at free-form code.

Status: Telegram bots in Python are the working project type, verified end to end. What is done and what is next is in docs/ROADMAP.md; what the product is meant to be is in docs/VISION.md.

How a request flows

graph TD
    User((User)) <--> |Telegram| Bot[Telegram Bot]
    Bot <--> |Redis Stream| PO[Product Owner Agent]

    PO --> |tools| API[API Service]
    PO --> |create story| ArchQueue[architect:queue]

    subgraph Scheduler
        Dispatcher[Task Dispatcher]
    end

    ArchQueue --> Architect[Architect]
    Architect --> |tasks| API
    Dispatcher --> |scaffold:queue| Scaffolder[Scaffolder]
    Dispatcher --> |engineering:queue| Eng[Engineering Worker]
    Dispatcher --> |deploy:queue| Dep[Deploy Worker]
    Dep --> |qa:queue| QA[QA Worker]

    Eng --> |manages| Workers[Coding Agent Containers]

    API --> |data| DB[(PostgreSQL)]
    Eng --> |result| PO
    Dep --> |result| PO
    QA --> |result| PO

Loading

A project moves through DRAFT → scaffold → ACTIVE → architect → tasks → PR_REVIEW → DEPLOYING → TESTING → COMPLETED. Each arrow is a queue with a typed contract, not a function call, so a stage can fail and be retried without the rest of the system knowing.

Stage by stage: docs/PIPELINE_V2.md. Agent nodes and their tools: docs/NODES.md. The queues and DTOs themselves: docs/CONTRACTS.md.

Services

Service	What it does
api	FastAPI, the single source of truth over PostgreSQL. Every other service reads and writes through it.
telegram_bot	The user interface; owns PO sessions.
langgraph	The PO agent and the Engineering/DevOps subgraphs.
architect	Splits a story into tasks. Its own container, not part of the scheduler.
scheduler	Task dispatcher, scaffold trigger, github/server sync, health checker.
scaffolder	Prepares the repository: copier, make setup, first push. Runs before the architect.
engineering-worker, deploy-worker, qa-worker	Redis-stream consumers. Separate entrypoints on the shared langgraph image.
worker-manager	Starts and reaps the coding-agent containers, isolated on the codegen_worker network.
infra-service	Ansible runner: provisions and configures the servers projects land on.
admin-frontend	React SPA on 3001 behind nginx basic auth: projects, tasks, workers, queues.
user-dashboard	The end user's own view of their projects.
loki, promtail, grafana	Structured logs and dashboards.

Coding agents run inside the worker containers rather than being written here: Claude Code, Factory.ai Droid and OpenAI Codex are interchangeable behind one interface (docs/coding-agents.md).

Running it locally

Needs Docker with Compose, Python 3.12+ and uv.

cp .env.example .env      # then fill in the credentials
make setup-hooks
make up
make migrate
make seed

The stack is up when curl -sf http://localhost:8000/health answers. From there, make test-unit is the fast gate and make test-integration needs the stack running.

Two details that cost the most time when they are unknown:

• shared/ is never installed as a package. Compose bind-mounts it, images COPY it, tests import it from the tree. Editing it needs no rebuild for bind-mounted services — see docs/REBUILD.md, which is also where the two separate build loops are explained.
• Nothing takes a default value. A missing key raises rather than falling back, on purpose. The reasoning is in CLAUDE.md.

Test layers, what each one costs and when to run it: docs/TESTING.md.

Documentation

ARCHITECTURE.md	Services, data flows, the system as a whole
docs/CONTRACTS.md	Queue registry, DTOs, correlation IDs
docs/GLOSSARY.md	What an entity is called and what it means
docs/DEPLOY.md	Production deploy, GitHub Actions, server setup
docs/SECRETS.md	The three secret levels: platform, project, user
docs/ERROR_HANDLING.md	Error categories, retry and timeout policy
docs/LOGGING.md	structlog patterns, the Loki/Grafana stack
AGENTS.md	How AI assistants should work in this repository
docs/CHANGELOG.md	What has been done

Work on the orchestrator itself is scoped and tracked outside this repository, on a Pipeline board. Brainstorms, plans and the history of past sprints live in the knowledge store of the installation that drives that work, under state/knowledge/projects/codegen-orchestrator/.

License

MIT — see LICENSE.