362 lines
8.9 KiB
Markdown
362 lines
8.9 KiB
Markdown
---
|
||
name: "Structure"
|
||
description: "Repository and module directory structure"
|
||
depth: 1
|
||
links: ["../index.md", "../modules/modules-and-spec.md"]
|
||
---
|
||
|
||
```text
|
||
correx/
|
||
│
|
||
├── apps/ # runnable entrypoints
|
||
│ ├── cli/ # clikt-based cli
|
||
│ ├── server/ # ktor api + websocket server
|
||
│ ├── worker/ # future distributed executor
|
||
│ └── desktop/ # optional later
|
||
│
|
||
├── core/ # PURE DOMAIN + ORCHESTRATION
|
||
│ │
|
||
│ ├── kernel/ # orchestration brain
|
||
│ │ ├── SessionOrchestrator.kt
|
||
│ │ ├── WorkflowCoordinator.kt
|
||
│ │ ├── ExecutionScheduler.kt
|
||
│ │ └── RuntimeSupervisor.kt
|
||
│ │
|
||
│ ├── events/ # event sourcing primitives
|
||
│ │ ├── model/
|
||
│ │ ├── store/
|
||
│ │ ├── append/
|
||
│ │ ├── replay/
|
||
│ │ ├── snapshot/
|
||
│ │ └── projection/
|
||
│ │
|
||
│ ├── transitions/ # workflow graph engine
|
||
│ │ ├── engine/
|
||
│ │ ├── dsl/
|
||
│ │ ├── parser/
|
||
│ │ ├── validator/
|
||
│ │ ├── graph/
|
||
│ │ └── conditions/
|
||
│ │
|
||
│ ├── context/ # context synthesis
|
||
│ │ ├── layers/
|
||
│ │ ├── ranking/
|
||
│ │ ├── compression/
|
||
│ │ ├── budgeting/
|
||
│ │ ├── summarization/
|
||
│ │ ├── dedup/
|
||
│ │ └── builders/
|
||
│ │
|
||
│ ├── inference/ # model abstraction
|
||
│ │ ├── contracts/
|
||
│ │ ├── routing/
|
||
│ │ ├── scheduling/
|
||
│ │ ├── lifecycle/
|
||
│ │ ├── capabilities/
|
||
│ │ └── isolation/
|
||
│ │
|
||
│ ├── stages/ # stage runtime
|
||
│ │ ├── runtime/
|
||
│ │ ├── execution/
|
||
│ │ ├── registry/
|
||
│ │ └── resolution/
|
||
│ │
|
||
│ ├── agents/ # ephemeral execution wrappers
|
||
│ │ ├── runtime/
|
||
│ │ ├── spawning/
|
||
│ │ ├── contracts/
|
||
│ │ └── teardown/
|
||
│ │
|
||
│ ├── artifacts/ # structured outputs
|
||
│ │ ├── model/
|
||
│ │ ├── schemas/
|
||
│ │ ├── lineage/
|
||
│ │ ├── validation/
|
||
│ │ └── serialization/
|
||
│ │
|
||
│ ├── validation/ # layered validation
|
||
│ │ ├── routing/
|
||
│ │ ├── schema/
|
||
│ │ ├── semantic/
|
||
│ │ ├── policy/
|
||
│ │ ├── approvals/
|
||
│ │ └── pipeline/
|
||
│ │
|
||
│ ├── approvals/ # approval engine
|
||
│ │ ├── tiers/
|
||
│ │ ├── policies/
|
||
│ │ ├── escalation/
|
||
│ │ ├── steering/
|
||
│ │ └── decisions/
|
||
│ │
|
||
│ ├── tools/ # tool orchestration
|
||
│ │ ├── contracts/
|
||
│ │ ├── runtime/
|
||
│ │ ├── receipts/
|
||
│ │ ├── sandbox/
|
||
│ │ └── registry/
|
||
│ │
|
||
│ ├── router/ # conversational facade
|
||
│ │ ├── memory/
|
||
│ │ ├── interpretation/
|
||
│ │ ├── summarization/
|
||
│ │ └── steering/
|
||
│ │
|
||
│ ├── sessions/ # lifecycle + fsm
|
||
│ │ ├── lifecycle/
|
||
│ │ ├── state/
|
||
│ │ ├── projections/
|
||
│ │ └── recovery/
|
||
│ │
|
||
│ ├── policies/ # separate policy engine
|
||
│ │ ├── evaluation/
|
||
│ │ ├── enforcement/
|
||
│ │ ├── filesystem/
|
||
│ │ ├── network/
|
||
│ │ └── execution/
|
||
│ │
|
||
│ ├── observability/
|
||
│ │ ├── tracing/
|
||
│ │ ├── metrics/
|
||
│ │ ├── diagnostics/
|
||
│ │ ├── event_inspection/
|
||
│ │ └── replay_debugging/
|
||
│ │
|
||
│ └── config/
|
||
│ ├── loading/
|
||
│ ├── validation/
|
||
│ ├── migrations/
|
||
│ ├── defaults/
|
||
│ └── schemas/
|
||
│
|
||
├── infrastructure/ # IO + implementations
|
||
│ │
|
||
│ ├── persistence/
|
||
│ │ ├── sqlite/
|
||
│ │ ├── postgres/
|
||
│ │ ├── snapshots/
|
||
│ │ └── migrations/
|
||
│ │
|
||
│ ├── inference/
|
||
│ │ ├── llama_cpp/
|
||
│ │ ├── ollama/
|
||
│ │ ├── vllm/
|
||
│ │ ├── openai_compatible/
|
||
│ │ └── mock/
|
||
│ │
|
||
│ ├── tools/
|
||
│ │ ├── shell/
|
||
│ │ ├── git/
|
||
│ │ ├── filesystem/
|
||
│ │ ├── docker/
|
||
│ │ ├── network/
|
||
│ │ └── sandboxing/
|
||
│ │
|
||
│ ├── security/
|
||
│ │ ├── secrets/
|
||
│ │ ├── isolation/
|
||
│ │ ├── allowlists/
|
||
│ │ └── permissions/
|
||
│ │
|
||
│ ├── scheduler/
|
||
│ │ ├── queues/
|
||
│ │ ├── concurrency/
|
||
│ │ ├── throttling/
|
||
│ │ └── backpressure/
|
||
│ │
|
||
│ └── telemetry/
|
||
│ ├── logging/
|
||
│ ├── tracing/
|
||
│ └── exporters/
|
||
│
|
||
├── interfaces/ # transport + api contracts
|
||
│ │
|
||
│ ├── api/
|
||
│ │ ├── rest/
|
||
│ │ ├── websocket/
|
||
│ │ ├── dto/
|
||
│ │ ├── mapping/
|
||
│ │ └── auth/
|
||
│ │
|
||
│ ├── cli/
|
||
│ │ ├── commands/
|
||
│ │ ├── formatting/
|
||
│ │ ├── interactive/
|
||
│ │ └── progress/
|
||
│ │
|
||
│ └── sdk/
|
||
│ ├── client/
|
||
│ └── protocol/
|
||
│
|
||
├── plugins/ # extension ecosystem
|
||
│ │
|
||
│ ├── tools/
|
||
│ ├── validators/
|
||
│ ├── compressors/
|
||
│ ├── providers/
|
||
│ ├── transitions/
|
||
│ ├── stages/
|
||
│ └── policies/
|
||
│
|
||
├── frontend/ # sveltekit ui
|
||
│ │
|
||
│ ├── src/
|
||
│ │ ├── routes/
|
||
│ │ ├── lib/
|
||
│ │ ├── components/
|
||
│ │ ├── stores/
|
||
│ │ ├── websocket/
|
||
│ │ └── visualizations/
|
||
│ │
|
||
│ └── static/
|
||
│
|
||
├── testing/
|
||
│ ├── replay/
|
||
│ ├── integration/
|
||
│ ├── fixtures/
|
||
│ ├── projections/
|
||
│ ├── transitions/
|
||
│ ├── approvals/
|
||
│ └── deterministic/
|
||
│
|
||
├── docs/
|
||
│ ├── architecture/
|
||
│ ├── events/
|
||
│ ├── transitions/
|
||
│ ├── plugins/
|
||
│ ├── configs/
|
||
│ └── threat_model/
|
||
│
|
||
└── examples/
|
||
├── workflows/
|
||
├── configs/
|
||
├── plugins/
|
||
└── stages/
|
||
```
|
||
|
||
architecturally:
|
||
|
||
```text
|
||
ui/cli/api
|
||
↓
|
||
interfaces layer
|
||
↓
|
||
application/orchestration layer
|
||
↓
|
||
domain/core layer
|
||
↓
|
||
ports/contracts
|
||
↓
|
||
infrastructure layer
|
||
```
|
||
|
||
rules:
|
||
|
||
* core NEVER imports infrastructure
|
||
* infrastructure implements ports/interfaces from core
|
||
* plugins only talk through contracts
|
||
* ui never touches persistence directly
|
||
* projections are rebuildable only from events
|
||
* tools never mutate state directly
|
||
* models never own memory/state
|
||
* router never owns execution state
|
||
|
||
important internal split
|
||
|
||
1. domain/core (pure deterministic logic)
|
||
|
||
contains:
|
||
|
||
* events
|
||
* transitions
|
||
* projections
|
||
* approvals
|
||
* policies
|
||
* artifact definitions
|
||
* session fsm
|
||
|
||
must be:
|
||
|
||
* testable without IO
|
||
* replayable
|
||
* deterministic
|
||
|
||
2. application layer
|
||
|
||
contains:
|
||
|
||
* orchestration
|
||
* workflow execution
|
||
* context building
|
||
* retries
|
||
* scheduling
|
||
* coordination
|
||
|
||
this is the “brain”.
|
||
|
||
3. infrastructure layer
|
||
|
||
contains:
|
||
|
||
* sqlite
|
||
* llama.cpp
|
||
* shell
|
||
* websocket
|
||
* filesystem
|
||
* network
|
||
|
||
replaceable adapters only.
|
||
|
||
4. interface layer
|
||
|
||
contains:
|
||
|
||
* cli
|
||
* web api
|
||
* websocket protocol
|
||
* sdk
|
||
|
||
thin wrappers only.
|
||
|
||
most important subsystem boundaries
|
||
|
||
event system
|
||
source of truth.
|
||
|
||
projection system
|
||
derived/read models only.
|
||
|
||
transition engine
|
||
pure deterministic graph executor.
|
||
|
||
context processor
|
||
stateless synthesizer.
|
||
|
||
validation pipeline
|
||
hard gatekeeper.
|
||
|
||
approval engine
|
||
risk boundary.
|
||
|
||
tool runtime
|
||
isolated side effects.
|
||
|
||
model manager
|
||
resource scheduler.
|
||
|
||
router
|
||
human-facing facade only.
|
||
|
||
if implemented correctly, you should eventually be able to:
|
||
|
||
* replay entire sessions deterministically
|
||
* swap model providers without touching orchestration
|
||
* rebuild every projection from events
|
||
* run headless without UI
|
||
* replace frontend entirely
|
||
* distribute workers later
|
||
* test most logic without inference
|
||
* fuzz transitions/approvals safely
|
||
|
||
that’s usually the sign the boundaries are correct.
|