---
name: "System Overview"
description: "System overview and core metaphor of Correx"
depth: 2
links:
  - "../index.md"
  - "./event-model.md"
  - "./replay-model.md"
  - "./context-layers.md"
  - "./security-boundaries.md"
---

# system overview

**version:** 0.1-draft  
**status:** architectural narrative

---

## 1. what is correx?

Correx is a **local‑first orchestration runtime** for structured LLM workflows. It provides a deterministic shell around probabilistic cognition, treating language models as interchangeable execution engines while owning memory, state, validation, and permissions.

The system is not a chatbot framework. It is a config‑driven workflow orchestrator that treats every model output as an untrusted proposal and only advances state after multiple layers of validation and approval.

---

## 2. core metaphor

**Harness is the brain, models are the muscles, Router is the face.**

* **Harness (core kernel):** orchestrates workflow, owns lifecycle, validates everything, maintains event‑sourced state.
* **Router:** conversational façade that chit‑chats with the user, provides summaries, and interprets steering; always available but never persists in execution context.
* **Agents:** ephemeral, stateless workers that consume synthesized context and emit structured artifacts.
* **Models:** stateless inference engines; they receive only a tightly compressed context pack and produce a single response.

---

## 3. key architectural properties

| property | implementation |
|----------|----------------|
| event‑sourced | all state is derivable from immutable events |
| deterministic‑enough | orchestration logic is deterministic; inference randomness is contained |
| replayable | full session replay without original models or live tools |
| provider‑agnostic | local GGUF and remote OpenAI‑compatible models are interchangeable |
| context‑efficient | aggressive compression, budgeting, and layering prevents context bloat |
| bounded autonomy | explicit tiers, approval gates, and cancellation boundaries |
| validation‑first | every artifact passes routing → schema → semantic → approval validation |

---

## 4. system layers

```
┌─────────────────┐
│     user        │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│   interfaces    │  cli, api, websocket, frontend
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│   orchestration │  session life, stage scheduling, retry, coordination
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│    core domain  │  events, transitions, validation, approvals, context, artifacts
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│  infrastructure │  persistence, inference providers, tool runtime, sandboxing
└─────────────────┘
```

Core never depends on infrastructure. Infrastructure implements contracts defined by core.

---

## 5. execution flow (simplified)

1. User input arrives via Router.
2. Session is created or resumed; projection rebuilt from events.
3. Orchestrator determines next stage (from transition graph).
4. Context Processor synthesises a ContextPack from L0–L2 layers.
5. Inference module selects and calls the appropriate model.
6. Model output is parsed into an artifact.
7. Validation pipeline checks artifact (routing, schema, semantic, approval).
8. If approved, transition engine evaluates conditions and moves to next stage.
9. All steps are recorded as events.

---

## 6. design philosophy

Correx is an **orchestration kernel** that enforces strict separation of concerns, immutability, and replayability. Reliability comes from explicit constraints, not from trusting model intelligence.