From 63592c2c65ce63197a07a7926234b1809e339e3d Mon Sep 17 00:00:00 2001 From: Adeolu Ogunnoiki Date: Sun, 8 Nov 2026 17:22:26 -0600 Subject: [PATCH] docs: render every architecture diagram in the house style --- docs/ARCHITECTURE.md | 69 ++++++------------------------ docs/architecture/job-recovery.mmd | 20 +++++++++ docs/architecture/job-recovery.svg | 1 + docs/architecture/job-states.mmd | 18 ++++++++ docs/architecture/job-states.svg | 1 + docs/architecture/request-path.mmd | 33 ++++++++++++++ docs/architecture/request-path.svg | 1 + 7 files changed, 88 insertions(+), 55 deletions(-) create mode 100644 docs/architecture/job-recovery.mmd create mode 100644 docs/architecture/job-recovery.svg create mode 100644 docs/architecture/job-states.mmd create mode 100644 docs/architecture/job-states.svg create mode 100644 docs/architecture/request-path.mmd create mode 100644 docs/architecture/request-path.svg diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index f1596e5..f074213 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -26,26 +26,11 @@ worker processes open it independently. ## Request path -```mermaid -flowchart LR - C[Client] -->|Bearer key| A[api.py
ThreadingHTTPServer] - A --> K{auth.py
HMAC lookup} - K -->|missing, invalid, revoked| E401[401] - K -->|tenant from key row| R{per-tenant
token bucket} - R -->|empty| E429[429] - R --> T[Tracer span
http.request] - T --> AG[AgentRuntime.ask
react_agent.ReActAgent] - AG -->|every model call| GW[llm_gateway.Gateway
for this tenant] - GW -->|injection check, PII redaction,
cache, output policy| P[GroundedPolicyProvider] - GW -->|blocked| E422[422] - AG -->|tool: search_knowledge_base| KB[KnowledgeBase
tenant index only] - KB --> HR[hybrid_rag.HybridRetriever
BM25 + TF-IDF + HNSW] - HR --> HN[ann_vector_search_library.HNSW] - AG -->|tool: calculator| CALC[react_agent CalculatorTool] - AG -->|optional schema| CG[constrained_generation_library] - T --> TS[(spans table)] - AG --> RESP[answer, citations,
grounded, sources, trace_id] -``` +

+ Request path diagram +

+ +Legend: amber = entry points and external systems, indigo = core logic, green = data and state, blue = validation and control, grey = observability and outputs. 1. `api.py` reads the `Authorization: Bearer` (or `X-API-Key`) header and calls `KeyStore.verify`. The tenant comes from the stored key row. Request bodies never carry @@ -66,41 +51,15 @@ flowchart LR ## Durable job lifecycle -```mermaid -stateDiagram-v2 - [*] --> queued: POST /v1/jobs - queued --> running: claim (BEGIN IMMEDIATE)
lease_owner, lease_expires, lease_token+1 - running --> running: heartbeat renews lease - running --> running: step done: ledger row + board snapshot
(one transaction, fenced by lease_token) - running --> running: lease expired, worker dead:
another worker claims, token+1, resumes from board - running --> succeeded: report step checkpointed - running --> failed: critic rejection, step error,
or attempts > max_attempts - succeeded --> [*] - failed --> [*] -``` - -```mermaid -sequenceDiagram - participant API - participant DB as SQLite - participant WA as Worker A - participant WB as Worker B - API->>DB: INSERT job (queued) - WA->>DB: claim: token=1, expires=now+L - WA->>DB: save plan (blackboard snapshot) - loop each step - WA->>DB: record attempt (q1) - WA->>WA: Orchestrator.attempt_subtask - WA->>DB: save spans - WA->>DB: ledger row q1 + board (only if owner and token=1) - end - Note over WA: SIGKILL. Heartbeats stop. - WB->>DB: claim fails until expires < now - WB->>DB: claim: token=2 - WB->>WB: Blackboard.restore(board) - WB->>DB: record attempt (next incomplete step) - WB->>DB: ledger rows, then status=succeeded -``` +

+ Durable job lifecycle diagram +

+ +Legend: amber = entry points and external systems, indigo = core logic, green = data and state, blue = validation and control, grey = observability and outputs. + +

+ Durable job recovery sequence diagram +

### Tables diff --git a/docs/architecture/job-recovery.mmd b/docs/architecture/job-recovery.mmd new file mode 100644 index 0000000..ee2e1db --- /dev/null +++ b/docs/architecture/job-recovery.mmd @@ -0,0 +1,20 @@ +sequenceDiagram + participant API + participant DB as SQLite + participant WA as Worker A + participant WB as Worker B + API->>DB: INSERT job (queued) + WA->>DB: claim: token=1, expires=now+L + WA->>DB: save plan (blackboard snapshot) + loop each step + WA->>DB: record attempt (q1) + WA->>WA: Orchestrator.attempt_subtask + WA->>DB: save spans + WA->>DB: ledger row q1 + board (only if owner and token=1) + end + Note over WA: SIGKILL. Heartbeats stop. + WB->>DB: claim fails until expires < now + WB->>DB: claim: token=2 + WB->>WB: Blackboard.restore(board) + WB->>DB: record attempt (next incomplete step) + WB->>DB: ledger rows, then status=succeeded diff --git a/docs/architecture/job-recovery.svg b/docs/architecture/job-recovery.svg new file mode 100644 index 0000000..732dd74 --- /dev/null +++ b/docs/architecture/job-recovery.svg @@ -0,0 +1 @@ +Worker BWorker ASQLiteAPIloop[each step]SIGKILL.Heartbeats stop.INSERT job (queued)claim: token=1,expires=now+Lsave plan (blackboardsnapshot)record attempt (q1)Orchestrator.attempt_su-btasksave spansledger row q1 + board (onlyif owner and token=1)claim fails until expires < nowclaim: token=2Blackboard.restore(boa-rd)record attempt (next incomplete step)ledger rows, then status=succeeded \ No newline at end of file diff --git a/docs/architecture/job-states.mmd b/docs/architecture/job-states.mmd new file mode 100644 index 0000000..f793c26 --- /dev/null +++ b/docs/architecture/job-states.mmd @@ -0,0 +1,18 @@ +stateDiagram-v2 + direction TB + classDef edge fill:#F59E0B,stroke:#1E293B,color:#1E293B,stroke-width:1px; + classDef core fill:#6366F1,stroke:#1E293B,color:#ffffff,stroke-width:1px; + classDef data fill:#10B981,stroke:#1E293B,color:#ffffff,stroke-width:1px; + classDef control fill:#0EA5E9,stroke:#1E293B,color:#ffffff,stroke-width:1px; + classDef obs fill:#CBD5E1,stroke:#1E293B,color:#1E293B,stroke-width:1px; + [*] --> queued: POST /v1/jobs + queued --> running: claim, lease_token + 1 + running --> running: heartbeat, fenced step commit,
reclaim after lease expiry + running --> succeeded: report checkpointed + running --> failed: rejected or out of attempts + succeeded --> [*] + failed --> [*] + class queued data + class running core + class succeeded obs + class failed edge diff --git a/docs/architecture/job-states.svg b/docs/architecture/job-states.svg new file mode 100644 index 0000000..3dcde91 --- /dev/null +++ b/docs/architecture/job-states.svg @@ -0,0 +1 @@ +

POST /v1/jobs

claim, lease_token + 1

heartbeat, fenced step commit,
reclaim after lease expiry

report checkpointed

rejected or out of attempts

queued

running

succeeded

failed

\ No newline at end of file diff --git a/docs/architecture/request-path.mmd b/docs/architecture/request-path.mmd new file mode 100644 index 0000000..d280999 --- /dev/null +++ b/docs/architecture/request-path.mmd @@ -0,0 +1,33 @@ +flowchart LR + classDef edge fill:#F59E0B,stroke:#1E293B,color:#1E293B,stroke-width:1px; + classDef core fill:#6366F1,stroke:#1E293B,color:#ffffff,stroke-width:1px; + classDef data fill:#10B981,stroke:#1E293B,color:#ffffff,stroke-width:1px; + classDef control fill:#0EA5E9,stroke:#1E293B,color:#ffffff,stroke-width:1px; + classDef obs fill:#CBD5E1,stroke:#1E293B,color:#1E293B,stroke-width:1px; + subgraph Edge["HTTP edge (api.py)"] + direction TB + C["Client"]:::edge -->|Bearer key| A["api.py
ThreadingHTTPServer"]:::edge + A --> K["auth.py: HMAC key lookup
401 if missing or revoked"]:::control + K -->|tenant from key row| R["per-tenant token bucket
429 when empty"]:::control + end + subgraph Agent["Agent runtime"] + direction TB + T["Tracer span
http.request"]:::obs --> AG["AgentRuntime.ask
ReActAgent loop"]:::core + AG --> RESP["answer, citations,
grounded, trace_id"]:::obs + end + subgraph Calls["Model, tools and retrieval"] + direction TB + GW["llm_gateway.Gateway
422 when blocked"]:::control --> P["GroundedPolicyProvider"]:::edge + CALC["CalculatorTool"]:::core ~~~ CG["constrained_generation
optional schema"]:::control + KB["KnowledgeBase
tenant index only"]:::data --> HR["HybridRetriever
BM25 + TF-IDF + HNSW"]:::core + HR --> HN["ann_vector_search
HNSW"]:::data + P ~~~ CALC + CG ~~~ KB + end + subgraph State["State"] + direction TB + TS[("spans table")]:::data + end + Edge -->|allowed request| Agent + Agent -->|model calls, tools, search| Calls + Agent -.->|spans| State diff --git a/docs/architecture/request-path.svg b/docs/architecture/request-path.svg new file mode 100644 index 0000000..549f475 --- /dev/null +++ b/docs/architecture/request-path.svg @@ -0,0 +1 @@ +

State

Model, tools and retrieval

Agent runtime

HTTP edge (api.py)

Bearer key

tenant from key row

allowed request

model calls, tools, search

spans

Client

api.py
ThreadingHTTPServer

auth.py: HMAC key lookup
401 if missing or revoked

per-tenant token bucket
429 when empty

Tracer span
http.request

AgentRuntime.ask
ReActAgent loop

answer, citations,
grounded, trace_id

llm_gateway.Gateway
422 when blocked

GroundedPolicyProvider

CalculatorTool

constrained_generation
optional schema

KnowledgeBase
tenant index only

HybridRetriever
BM25 + TF-IDF + HNSW

ann_vector_search
HNSW

spans table

\ No newline at end of file