Architecture

Agency is split so product runtime, reference deployment, and engineering umbrella stay distinct. Do not treat Compose choices as permanent package requirements.

Product / runtime

agency-django (import agency)

Domain models, ThreadRunner, REST, Channels publishers, corpus, miner, UI schema producers, Celery task entrypoints. Installable without agency-server.

agency-ui

Vue schema renderer for the Agency desktop. Owns how schema nodes look and behave. Built assets are published into agency-django static (not a standalone production deploy). Mission Control is one desktop app (Agents / Missions / Executions), not the whole UI.

Together they are the reusable product surface: agents, missions, realtime projections, and the desktop UI.

Reference host / deployment

agency-server is a reference Django host + Docker Compose stack:

  • Django WSGI — HTTP, REST, admin, SPA shell

  • Django ASGI — WebSockets (/channel/)

  • Celery worker / beat / Flower — transport for background work

  • PostgreSQL — primary Agency DB

  • Redis — broker + Channels layer

  • Nginx — reverse proxy and /static/

  • ChromaDB — vector store used by corpus in this stack

  • Ollama — local LLM provider used in this stack

  • ComfyUI — local GPU image generation used in this stack

Nginx, Ollama, and Chroma are reference deployment choices, not conceptual requirements of agency-django. Another host may swap providers, brokers, or front proxies while keeping the same package APIs.

Example domain apps (boe, bopv, chat) live in the host, not in the package.

Engineering umbrella

agency-workspace coordinates the three product repos:

  • ./dev helpers

  • todo/ backlog

  • Cursor rules

  • submodule commit pins

It is not part of the runtime. There is no product Compose file at the umbrella root.

How they connect

agency-ui  ──build──►  agency-django static
                          │
                          ▼
agency-server  (Compose: WSGI + ASGI + Celery + DB + …)
                          │
                     nginx :80

See also: Concepts, Deployment, Workspace.

Strategic vision (not technical spec): workspace CONTEXT.md. Documentation surface map: workspace README.md (Documentation architecture).