# renox23/order-supervisor architecture

> Architecture diagram of the GitHub repository renox23/order-supervisor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/renox23/order-supervisor
- Repository: https://github.com/renox23/order-supervisor

## Overview

#### Purpose and entry points
Order Supervisor is a POC for durable, per-order AI supervision. A Temporal workflow receives order events and operator controls, decides simulated business actions through an LLM, persists an auditable timeline, and produces a final summary at termination.

Primary processes are the FastAPI server (`backend/app/main.py`), Temporal worker (`backend/app/temporal/worker.py`), Next.js UI (`frontend/app/page.tsx`), and terminal driver (`backend/scripts/supervisor_cli.py`).

#### API command/read boundary
FastAPI exposes supervisor configuration and run-control endpoints. All mutations—run start, order event, instruction, interrupt/resume, and termination—are sent to Temporal; reads of status, timeline, and memory query PostgreSQL rather than workflow state directly.

- Routers: `backend/app/api/runs.py`, `backend/app/api/supervisors.py`
- Signal-with-start client boundary: `backend/app/temporal/client.py`
- API schemas/dependencies: `backend/app/schemas.py`, `backend/app/api/deps.py`

#### Durable order orchestration
`OrderSupervisorWorkflow` is the core state machine: one workflow execution per order/run. It remains deterministic, accepts signals, manages interrupt/resume/terminal state, waits for either incoming signals or timers, and drives sleep/wake cycles. It never performs network or database I/O itself.

- Workflow and shared contracts: `backend/app/temporal/workflows.py`, `backend/app/temporal/shared.py`
- Wake policy: `backend/app/temporal/policy.py`
- Worker registration/runtime: `backend/app/temporal/worker.py`

#### Activity and agent execution
The workflow delegates all impure work to Temporal activities. `agent_decide` invokes the OpenAI-compatible LLM client using structured tool/function output; resulting simulated actions and memory updates are fed back into durable workflow progression. A separate activity creates the terminal summary.

- Activities: `backend/app/temporal/activities.py`
- LLM agent: `backend/app/agent/agent.py`
- Activity/workflow DTO boundary: `backend/app/temporal/shared.py`

The default external LLM is Groq, but configuration supports any OpenAI-compatible endpoint, including OpenAI or local Ollama.

#### Persistence and projection model
PostgreSQL is the read model and audit store, updated only through workflow-invoked persistence activities. It contains supervisor definitions, run state, compact memory, final summaries, and simulated-action/event timeline records. This separates durable Temporal command processing from API/UI query serving.

- DB connection lifecycle: `backend/app/db.py`
- SQL persistence/query layer: `backend/app/persistence.py`
- Initial schema and migration runner: `backend/db/migrations/0001_init.sql`, `backend/db/migrate.py`

#### User-facing clients
The Next.js App Router frontend creates supervisors and runs, injects lifecycle events and controls, and displays persisted run details. Its API client targets FastAPI; it does not communicate with Temporal or PostgreSQL directly.

- Run list/create/detail pages: `frontend/app/runs/new/page.tsx`, `frontend/app/runs/[id]/page.tsx`
- Supervisor creation: `frontend/app/supervisors/new/page.tsx`
- API integration: `frontend/lib/api.ts`

#### Runtime infrastructure
Docker Compose provides PostgreSQL and the Temporal development server; the worker, API, and frontend are separate long-running processes. Python 3.11 hosts FastAPI, asyncpg, Temporal Python SDK, and LLM activities; Node 18+ hosts Next.js. Temporal is the system of record for orchestration history, while PostgreSQL serves application read projections.

- Infrastructure: `docker-compose.yml`
- Backend settings: `backend/app/config.py`
- Environment contract: `.env.example`

Main entry points: [`backend/app/temporal/workflows.py`](https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/workflows.py) (OrderSupervisorWorkflow), [`backend/app/persistence.py`](https://github.com/renox23/order-supervisor/blob/main/backend/app/persistence.py) (Persistence/query layer), [`backend/app/api/runs.py`](https://github.com/renox23/order-supervisor/blob/main/backend/app/api/runs.py) (Run & supervisor routers), [`backend/app/temporal/activities.py`](https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/activities.py) (Workflow activities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Clients"]
  node_frontend["Next.js frontend<br/>web client<br/>[page.tsx]"]
  node_cli["Supervisor CLI<br/>terminal client<br/>[supervisor_cli.py]"]
  node_frontend_api["Frontend API client<br/>HTTP integration<br/>[api.ts]"]
  node_runs_ui["Run pages<br/>UI routes<br/>[page.tsx]"]
end

subgraph group_api["API Service"]
  node_fastapi["FastAPI server<br/>command/query API<br/>[main.py]"]
  node_routers["Run &amp; supervisor routers<br/>API routes<br/>[runs.py]"]
  node_temporal_client["Signal-with-start client<br/>Temporal client<br/>[client.py]"]
end

subgraph group_temporal["Temporal Orchestration"]
  node_workflow{{"OrderSupervisorWorkflow<br/>durable state machine<br/>[workflows.py]"}}
  node_policy["Wake policy<br/>workflow policy<br/>[policy.py]"]
  node_worker["Temporal worker<br/>worker runtime<br/>[worker.py]"]
  node_activities["Workflow activities<br/>impure activity layer<br/>[activities.py]"]
  node_contracts["Workflow DTOs<br/>shared contracts<br/>[shared.py]"]
  node_agent["LLM decision agent<br/>structured tool agent<br/>[agent.py]"]
end

subgraph group_data["Read Model &amp; Audit"]
  node_postgres[("PostgreSQL<br/>[docker-compose.yml]")]
  node_persistence["Persistence/query layer<br/>SQL repository<br/>[persistence.py]"]
  node_db["Database lifecycle<br/>asyncpg connection layer<br/>[db.py]"]
end

subgraph group_infra["Runtime Infrastructure"]
  node_temporal_server[("Temporal server<br/>orchestration history<br/>[docker-compose.yml]")]
  node_llm["OpenAI-compatible LLM<br/>external inference service"]
end

node_frontend -->|"uses"| node_frontend_api
node_runs_ui -->|"calls"| node_frontend_api
node_frontend_api -->|"HTTP"| node_fastapi
node_cli -->|"controls runs"| node_fastapi
node_fastapi -->|"routes requests"| node_routers
node_routers -->|"mutations"| node_temporal_client
node_routers -->|"read queries"| node_persistence
node_temporal_client -->|"signal with start"| node_temporal_server
node_temporal_server -->|"dispatches tasks"| node_worker
node_worker -->|"runs"| node_workflow
node_workflow -->|"calculates wake cycles"| node_policy
node_workflow -->|"invokes"| node_activities
node_workflow -->|"uses"| node_contracts
node_activities -->|"decision work"| node_agent
node_agent -->|"structured inference"| node_llm
node_activities -->|"updates projections"| node_persistence
node_persistence -->|"uses connections"| node_db
node_db -->|"connects"| node_postgres
node_persistence -->|"reads and writes"| node_postgres

click node_frontend "https://github.com/renox23/order-supervisor/blob/main/frontend/app/page.tsx"
click node_cli "https://github.com/renox23/order-supervisor/blob/main/backend/scripts/supervisor_cli.py"
click node_frontend_api "https://github.com/renox23/order-supervisor/blob/main/frontend/lib/api.ts"
click node_runs_ui "https://github.com/renox23/order-supervisor/blob/main/frontend/app/runs/%5Bid%5D/page.tsx"
click node_fastapi "https://github.com/renox23/order-supervisor/blob/main/backend/app/main.py"
click node_routers "https://github.com/renox23/order-supervisor/blob/main/backend/app/api/runs.py"
click node_temporal_client "https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/client.py"
click node_workflow "https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/workflows.py"
click node_policy "https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/policy.py"
click node_worker "https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/worker.py"
click node_activities "https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/activities.py"
click node_contracts "https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/shared.py"
click node_agent "https://github.com/renox23/order-supervisor/blob/main/backend/app/agent/agent.py"
click node_temporal_server "https://github.com/renox23/order-supervisor/blob/main/docker-compose.yml"
click node_postgres "https://github.com/renox23/order-supervisor/blob/main/docker-compose.yml"
click node_persistence "https://github.com/renox23/order-supervisor/blob/main/backend/app/persistence.py"
click node_db "https://github.com/renox23/order-supervisor/blob/main/backend/app/db.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_cli,node_frontend_api,node_runs_ui toneBlue
class node_fastapi,node_routers,node_temporal_client toneAmber
class node_workflow,node_policy,node_worker,node_activities,node_contracts,node_agent toneMint
class node_postgres,node_persistence,node_db toneRose
class node_temporal_server,node_llm toneIndigo
```

## Components

### User Clients

- [Next.js frontend](https://github.com/renox23/order-supervisor/blob/main/frontend/app/page.tsx): web client · Creates and controls runs and displays persisted details. · `frontend/app/page.tsx`
- [Supervisor CLI](https://github.com/renox23/order-supervisor/blob/main/backend/scripts/supervisor_cli.py): terminal client · `backend/scripts/supervisor_cli.py`
- [Frontend API client](https://github.com/renox23/order-supervisor/blob/main/frontend/lib/api.ts): HTTP integration · `frontend/lib/api.ts`
- [Run pages](https://github.com/renox23/order-supervisor/blob/main/frontend/app/runs/%5Bid%5D/page.tsx): UI routes · `frontend/app/runs/[id]/page.tsx`

### API Service

- [FastAPI server](https://github.com/renox23/order-supervisor/blob/main/backend/app/main.py): command/query API · Sends mutations to Temporal and serves reads from PostgreSQL. · `backend/app/main.py`
- [Run & supervisor routers](https://github.com/renox23/order-supervisor/blob/main/backend/app/api/runs.py): API routes · `backend/app/api/runs.py`
- [Signal-with-start client](https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/client.py): Temporal client · `backend/app/temporal/client.py`

### Temporal Orchestration

- [OrderSupervisorWorkflow](https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/workflows.py): durable state machine · Deterministically processes per-order signals, timers, and lifecycle state. · `backend/app/temporal/workflows.py`
- [Wake policy](https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/policy.py): workflow policy · `backend/app/temporal/policy.py`
- [Temporal worker](https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/worker.py): worker runtime · Registers workflow and activity execution. · `backend/app/temporal/worker.py`
- [Workflow activities](https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/activities.py): impure activity layer · Performs agent, persistence, and terminal-summary work. · `backend/app/temporal/activities.py`
- [Workflow DTOs](https://github.com/renox23/order-supervisor/blob/main/backend/app/temporal/shared.py): shared contracts · `backend/app/temporal/shared.py`
- [LLM decision agent](https://github.com/renox23/order-supervisor/blob/main/backend/app/agent/agent.py): structured tool agent · Turns order context into simulated actions and memory updates. · `backend/app/agent/agent.py`

### Read Model & Audit

- [PostgreSQL](https://github.com/renox23/order-supervisor/blob/main/docker-compose.yml): read model and audit store · Stores supervisor definitions, run projections, memory, summaries, and timelines. · `docker-compose.yml`
- [Persistence/query layer](https://github.com/renox23/order-supervisor/blob/main/backend/app/persistence.py): SQL repository · `backend/app/persistence.py`
- [Database lifecycle](https://github.com/renox23/order-supervisor/blob/main/backend/app/db.py): asyncpg connection layer · `backend/app/db.py`

### Runtime Infrastructure

- [Temporal server](https://github.com/renox23/order-supervisor/blob/main/docker-compose.yml): orchestration history · System of record for workflow execution history. · `docker-compose.yml`
- **OpenAI-compatible LLM**: external inference service · Defaults to Groq; can target OpenAI or Ollama.

## Connections

- Next.js frontend → Frontend API client: uses
- Run pages → Frontend API client: calls
- Frontend API client → FastAPI server: HTTP
- Supervisor CLI → FastAPI server: controls runs
- FastAPI server → Run & supervisor routers: routes requests
- Run & supervisor routers → Signal-with-start client: mutations
- Run & supervisor routers → Persistence/query layer: read queries
- Signal-with-start client → Temporal server: signal with start
- Temporal server → Temporal worker: dispatches tasks
- Temporal worker → OrderSupervisorWorkflow: runs
- OrderSupervisorWorkflow → Wake policy: calculates wake cycles
- OrderSupervisorWorkflow → Workflow activities: invokes
- OrderSupervisorWorkflow → Workflow DTOs: uses
- Workflow activities → LLM decision agent: decision work
- LLM decision agent → OpenAI-compatible LLM: structured inference
- Workflow activities → Persistence/query layer: updates projections
- Persistence/query layer → Database lifecycle: uses connections
- Database lifecycle → PostgreSQL: connects
- Persistence/query layer → PostgreSQL: reads and writes