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 codegen-product-kit, a spec-first framework, so the pipeline reasons about a declared contract instead of guessing at free-form code.

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]
    PRCI[PR/CI loop] --> |"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 has the lifecycle states draft, active, paused, and archived. Pipeline activity is represented by its Stories, Tasks, and Runs; queues carry typed contracts between pipeline stages.

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	PO Redis consumer + ReactAgent runtime. The shared image also supplies the separate worker/architect entrypoints below.
architect	Splits a story into tasks. Its own container, not part of the scheduler.
scheduler-pipeline	Task/story lifecycle plus independent PR/CI, supervision, notification, QA and access loops.
scheduler-infrastructure	Server sync, health checks, provisioning triggers and result recovery.
scheduler-maintenance	GitHub sync, analytics aggregation and queue cleanup.
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.
worker-broker	Authenticated bridge between isolated coding workers and control-plane streams, status/session APIs, and Compose proxy operations.
infra-service	Ansible runner: provisions and configures the servers projects land on.
admin-frontend	React SPA on 3001 behind nginx basic auth: attention feed, request journeys, the runtime atlas, plus projects, tasks, workers, queues.
caddy	Public reverse proxy/TLS edge for production endpoints and the self-hosted registry.
registry	Self-hosted Docker Registry used by CI/deploy image flow.
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. Development compose bind-mounts it, images COPY it (production runs only the image), tests import it from the tree. Editing it needs no rebuild for bind-mounted development services — see docs/REBUILD.md, which is also where the two separate build loops are explained.
• Required settings take no default. A missing identity, credential, connection or production-policy value raises rather than falling back, on purpose; only safe presentation, logging and local-ergonomics settings have documented defaults. The rule is in AGENTS.md.

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

Repository map

Area	Start here
Product services	services/ — one directory per deployable service; ARCHITECTURE.md explains their relationships.
Shared contracts and utilities	shared/ — typed DTOs, queues, clients, and common runtime helpers.
Tests	tests/ — cross-service, live, and E2E coverage; service-local tests live beside each service.
Compose test harnesses	tests/compose/ — test-owned Dockerfiles and Compose stacks, with a local README.
Operations	infra/ — Ansible, production configuration, and operational scripts.
Developer and CI scripts	scripts/ — repository checks and repeatable maintenance commands.
Documentation	docs/ — contracts, pipeline, operations, testing, and historical change notes.
Assistant instructions	AGENTS.md — canonical guidance; CLAUDE.md only redirects Claude Code to it.

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.