Skip to content

repository-architecture.md

Latest commit

 

History

History
95 lines (84 loc) · 4.47 KB

repository-architecture.md

File metadata and controls

95 lines (84 loc) · 4.47 KB
Raw

Repository Architecture

Monorepo Structure

openbuildapp/
  apps/
    control-center/         mission-control frontend
  packages/
    contracts/              shared domain contracts and enumerations
    runtime-core/           filesystem, JSON, hashing, confidence, event storage
    run-engine/             deterministic run creation and lifecycle state writes
    agent-runtime/          contract loading and structured agent execution
    cognitive-graph/        graph storage, merge rules, invalidation
    hypothesis-engine/      hypothesis lifecycle and validation records
    replay-engine/          replay steps and divergence detection
    verification-engine/    scoring, hard gates, perceptual checks
    repair-engine/          defect clustering and repair planning
    safety-kernel/          policy gates, approvals, redaction
  services/
    orchestrator/           control core and phase scheduler
    observer-web/           MVP web-lane observation runtime
    dashboard-backend/      read models, event streaming, evidence access
  workspace/
    agents/                 markdown contracts for each agent
    templates/              task, policy, evidence templates
    schemas/                runtime schema artifacts
    runs/                   deterministic run folders
    targets/                user-supplied targets
    snapshots/              shared snapshot artifacts
    logs/                   workspace-level logs
    artifacts/              shared non-run artifacts
    generated/              generated code outputs
    replays/                exported replay bundles
    reports/                exported reports
  docs/                     design and implementation docs
  schemas/                  schema registry metadata
  scripts/                  validation and bootstrap automation
  examples/                 example run requests
  tests/                    unit and integration tests

Ownership Boundaries

  • apps/*: owned by product UI and frontend platform engineers.
  • packages/contracts: owned by architecture; breaking changes require coordinated rollout.
  • packages/runtime-core: owned by platform runtime; no product-specific logic.
  • packages/run-engine: owned by control-plane engineers; writes canonical run state.
  • packages/agent-runtime: owned by agent platform; must remain lane-agnostic.
  • packages/cognitive-graph and packages/hypothesis-engine: owned by cognition platform.
  • packages/replay-engine, packages/verification-engine, packages/repair-engine: owned by fidelity and repair engineering.
  • packages/safety-kernel: owned by platform safety and runtime security.
  • services/orchestrator: owned by control-plane; coordinates all other packages.
  • services/observer-web: owned by observation lane team; MVP-only implementation lane.
  • services/dashboard-backend: owned by platform API team; serves run read models.
  • workspace/*: runtime-owned durable data; no package may assume in-memory-only state.

Dependency Rules

  • packages/contracts has no internal dependencies.
  • packages/runtime-core may depend only on packages/contracts and Node built-ins.
  • packages/run-engine depends on contracts, runtime-core, and safety-kernel.
  • packages/agent-runtime depends on contracts and runtime-core.
  • packages/cognitive-graph, hypothesis-engine, replay-engine, verification-engine, and repair-engine depend on contracts and runtime-core.
  • services/orchestrator may depend on all packages but no app.
  • services/dashboard-backend may depend on contracts, runtime-core, replay-engine, and verification-engine.
  • apps/control-center depends on backend DTOs only; no direct workspace mutation.

Runtime Data Flow

workspace target
  -> run engine creates run folder
  -> orchestrator initializes phase state
  -> observation runtime emits artifacts + events
  -> cognitive graph ingests evidence
  -> hypothesis engine proposes and validates claims
  -> reconstruction agents write generated outputs
  -> verification engine scores target vs twin
  -> repair engine plans patches
  -> safety kernel gates mutations and approvals
  -> replay engine archives step-by-step timeline
  -> dashboard backend serves read models

Filesystem-First Rule

No critical state may exist only in memory. If the orchestrator or any worker crashes, the run must be reconstructable from:

  • run-state.json
  • events.jsonl
  • actions.jsonl
  • replay artifacts
  • model files under models/
  • verification outputs