renox23/order-supervisor

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