epic-12: after epic audit and init commit
This commit is contained in:
@@ -0,0 +1,361 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user