Architecture

This section is for contributors. It explains how the code fits together and why. AGENTS.md at the repository root is the fuller, denser version, written for agents and maintainers; this section is the readable map, and the glossary says what each domain word means.

The shape

flowchart TB
    subgraph portal["Praxis — one Python process"]
        API["api/ — tier 4<br/>HTTP, SSE, MCP"]
        FL["flows/ — tier 3<br/>Flow folders, Phases, Runs"]
        AG["agent/ — tier 2<br/>prompts, toolsets, one turn"]
        MS["modelstore/ — tier 1<br/>client, catalog, gate, model gen + editing"]
        SB["sandbox/ — tier 1<br/>client"]
        CO["core/ — tier 0<br/>settings, sqlite + accessors, events, LLM builder, jobs, deployenv"]
        API --> FL --> AG --> MS & SB --> CO
    end
    WEB["src/web — React app"] -- "HTTP + one event stream" --> API
    MS -- "/refs/{ref}/query · sql · meta" --> STORE["model store → Cube → warehouse"]
    SB -- "/run · /uploads · /files" --> SBX["sandbox service"]

Five ideas carry most of the design:

1. The agent never writes SQL. It writes Cube JSON queries that pass a four-tier gate. → The query gate
2. The LLM returns decisions, never YAML, and Cube is the validator. → The data model
3. One flat event stream is the contract between agent and browser, and the event log is the transcript. → Events and the transcript
4. A Flow is a folder. Definition, runs and state are files, not rows. → The Flow engine
5. The portal runs nothing. It renders compose files and is told addresses. → The two deployments

And one rule enforced by a test: a package may import only its own tier or below. → Layering