101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
---
|
||
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. |