Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
31 lines (27 loc) · 2.37 KB

ARCHITECTURE.md

File metadata and controls

31 lines (27 loc) · 2.37 KB
Raw

Architecture (bin/)

Layers

  • Dispatcher: bin/chat routes verbs to command handlers; no logic beyond arg parsing/usage.
  • Commands: bin/commands/{chat,project,mcp}.sh parse flags/args, then call report/format functions. No business logic.
  • Report: composition layer; orchestrates HTTP/state operations, send/wait, and high-level behaviors (latest/show goal, inflight guards, scoped nested item store).
  • Format: presentation layer; deterministic sorting and text extraction for outputs.
  • State: locking, validation (via rules_state_md), atomic apply/reset/write, defaults.
  • HTTP: thin /browser wrappers (GET/POST), paste-mode sends.
  • Rules: schema validation for state plus inflight guard helper.
  • Utilities: logging, paths, verbiage normalization, jq helpers, url encoding.
  • Loader/Bootstrap: sets env (paths, locale, dry-run), loads libs in order with guards.

Contracts

  • Paste-only sends (sendMode:"fill"); CHAT_DRY_RUN toggles delivery (default live).
  • Locking on STATE_LOCK_PATH; no network under lock; atomic writes with validation.
  • Deterministic reads: sorted meta/thread outputs.
  • Verbiage store: all state object keys must be verbiage keys (^[A-Z]+(-[A-Z]+)*$); inputs are normalized (lowercase→uppercase, spaces→dashes).
  • Sharded state: any string value of the form ref file://... is treated as an external JSON subtree mounted at that node; reads/mutations resolve refs as if inlined; writes update referenced files while keeping the ref string in the root document.
  • Items + ids: project/chat ids are stored as values inside arrays (not object keys) to keep the state verbiage-pure.
  • Item storage: slash-delimited verbiage paths under scope roots; values are stored directly at the leaf under META or CONTENT (allowing deep mutation via deeper paths). JSON object/array values are recursively key-normalized to verbiage keys.
  • /browser/state-snapshot: stored as a JSON string at ITEMS/GLOBAL/META/MCP/STATE-SNAPSHOT (the raw snapshot shape is not verbiage-key compatible).
  • Exit codes: usage 2, state/domain 3, inflight 4, lock 5, HTTP 6, jq 7.

Files

  • bin/chat, bin/commands/*
  • bin/lib/*
  • bin/STATE-SCHEMA.md, bin/CLI-REFERENCE.md, bin/EXIT-CODES.md, bin/FEATURES.md, bin/TESTS.md

Flow

chat (dispatcher) → commands → report → (state/http) → format → stdout/stderr with exit codes enforced.