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: :doc:`concepts`, :doc:`framework/deployment`,
:doc:`development/workspace`.

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