# johan8124/civictrail architecture

> Architecture diagram of the GitHub repository johan8124/civictrail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johan8124/civictrail
- Repository: https://github.com/johan8124/civictrail

## Overview

CivicTrail is a web-based, evidence-first civic workflow assistant. A person enters a problem and evidence in the case intake; the triage API validates the request and delegates to an orchestrator that uses an agent to suggest a supported workflow and official route. Deterministic rules—not the agent—evaluate evidence and determine readiness. Results include an inspectable evidence ledger and a source-referenced action packet for human review; the product does not submit actions automatically. The graph reflects documented responsibilities and sampled calls; internal agent-tool wiring is summarized where its implementation was not sampled.

Main entry points: [`lib/agent/triage-orchestrator.ts`](https://github.com/johan8124/civictrail/blob/main/lib/agent/triage-orchestrator.ts) (Triage orchestrator), [`app/components/CaseIntake.tsx`](https://github.com/johan8124/civictrail/blob/main/app/components/CaseIntake.tsx) (Case intake), [`app/api/triage/route.ts`](https://github.com/johan8124/civictrail/blob/main/app/api/triage/route.ts) (Triage API), [`lib/readiness/engine.ts`](https://github.com/johan8124/civictrail/blob/main/lib/readiness/engine.ts) (Readiness computation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_intake["Case intake<br/>[CaseIntake.tsx]"]
  node_result_views["Result views"]
end

subgraph group_triage["Triage orchestration"]
  node_triage_api["Triage API<br/>[route.ts]"]
  node_orchestrator["Triage orchestrator"]
  node_agent["Strands agent<br/>[triage-agent.ts]"]
  node_agent_tools["Typed agent tools<br/>[agent-tools.ts]"]
  node_classification["Classification guard<br/>[classification.ts]"]
end

subgraph group_verification["Verification and evidence"]
  node_rules["Deterministic rule engine<br/>[engine.ts]"]
  node_readiness["Readiness computation<br/>[engine.ts]"]
  node_ledger["Evidence ledger<br/>[ledger.ts]"]
  node_packet["Action packet<br/>[packet.ts]"]
end

subgraph group_routes["Official routing"]
  node_routes["Official route catalog<br/>[index.ts]"]
  node_registry["Verified source registry<br/>[registry.ts]"]
end

node_person(("Person"))
node_human(("Human reviewer"))

node_person -->|"enters case"| node_intake
node_intake -->|"posts case"| node_triage_api
node_triage_api -->|"runs triage"| node_orchestrator
node_orchestrator -->|"requests analysis"| node_agent
node_agent -->|"calls tools"| node_agent_tools
node_orchestrator -->|"guards workflow"| node_classification
node_orchestrator -->|"computes readiness"| node_readiness
node_readiness -->|"evaluates evidence"| node_rules
node_readiness -->|"records findings"| node_ledger
node_orchestrator -->|"resolves route"| node_routes
node_routes -->|"reads verified sources"| node_registry
node_orchestrator -->|"records classification and route"| node_ledger
node_orchestrator -->|"builds packet"| node_packet
node_triage_api -->|"returns result"| node_intake
node_intake -->|"renders result"| node_result_views
node_result_views -->|"presents for review"| node_human

click node_intake "https://github.com/johan8124/civictrail/blob/main/app/components/CaseIntake.tsx"
click node_result_views "https://github.com/johan8124/civictrail/blob/main/app/components/ReadinessBanner.tsx"
click node_triage_api "https://github.com/johan8124/civictrail/blob/main/app/api/triage/route.ts"
click node_orchestrator "https://github.com/johan8124/civictrail/blob/main/lib/agent/triage-orchestrator.ts"
click node_agent "https://github.com/johan8124/civictrail/blob/main/lib/agent/triage-agent.ts"
click node_agent_tools "https://github.com/johan8124/civictrail/blob/main/lib/agent/agent-tools.ts"
click node_classification "https://github.com/johan8124/civictrail/blob/main/lib/agent/classification.ts"
click node_routes "https://github.com/johan8124/civictrail/blob/main/lib/routes/index.ts"
click node_registry "https://github.com/johan8124/civictrail/blob/main/lib/source-registry/registry.ts"
click node_rules "https://github.com/johan8124/civictrail/blob/main/lib/rules/engine.ts"
click node_readiness "https://github.com/johan8124/civictrail/blob/main/lib/readiness/engine.ts"
click node_ledger "https://github.com/johan8124/civictrail/blob/main/lib/evidence/ledger.ts"
click node_packet "https://github.com/johan8124/civictrail/blob/main/lib/action-packet/packet.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_intake,node_result_views,node_human toneBlue
class node_triage_api,node_orchestrator,node_agent,node_agent_tools,node_classification toneAmber
class node_rules,node_readiness,node_ledger,node_packet toneMint
class node_routes,node_registry toneRose
class node_person toneIndigo
```

## Components

### User experience

- [Case intake](https://github.com/johan8124/civictrail/blob/main/app/components/CaseIntake.tsx): `app/components/CaseIntake.tsx`
- [Result views](https://github.com/johan8124/civictrail/blob/main/app/components/ReadinessBanner.tsx): `app/components/ReadinessBanner.tsx`

### Triage orchestration

- [Triage API](https://github.com/johan8124/civictrail/blob/main/app/api/triage/route.ts): `app/api/triage/route.ts`
- [Triage orchestrator](https://github.com/johan8124/civictrail/blob/main/lib/agent/triage-orchestrator.ts): `lib/agent/triage-orchestrator.ts`
- [Strands agent](https://github.com/johan8124/civictrail/blob/main/lib/agent/triage-agent.ts): `lib/agent/triage-agent.ts`
- [Typed agent tools](https://github.com/johan8124/civictrail/blob/main/lib/agent/agent-tools.ts): `lib/agent/agent-tools.ts`
- [Classification guard](https://github.com/johan8124/civictrail/blob/main/lib/agent/classification.ts): `lib/agent/classification.ts`

### Verification and evidence

- [Deterministic rule engine](https://github.com/johan8124/civictrail/blob/main/lib/rules/engine.ts): `lib/rules/engine.ts`
- [Readiness computation](https://github.com/johan8124/civictrail/blob/main/lib/readiness/engine.ts): `lib/readiness/engine.ts`
- [Evidence ledger](https://github.com/johan8124/civictrail/blob/main/lib/evidence/ledger.ts): `lib/evidence/ledger.ts`
- [Action packet](https://github.com/johan8124/civictrail/blob/main/lib/action-packet/packet.ts): `lib/action-packet/packet.ts`

### Official routing

- [Official route catalog](https://github.com/johan8124/civictrail/blob/main/lib/routes/index.ts): `lib/routes/index.ts`
- [Verified source registry](https://github.com/johan8124/civictrail/blob/main/lib/source-registry/registry.ts): `lib/source-registry/registry.ts`

### Other components

- **Person**
- **Human reviewer**

## Connections

- Person → Case intake: enters case
- Case intake → Triage API: posts case
- Triage API → Triage orchestrator: runs triage
- Triage orchestrator → Strands agent: requests analysis
- Strands agent → Typed agent tools: calls tools
- Triage orchestrator → Classification guard: guards workflow
- Triage orchestrator → Readiness computation: computes readiness
- Readiness computation → Deterministic rule engine: evaluates evidence
- Readiness computation → Evidence ledger: records findings
- Triage orchestrator → Official route catalog: resolves route
- Official route catalog → Verified source registry: reads verified sources
- Triage orchestrator → Evidence ledger: records classification and route
- Triage orchestrator → Action packet: builds packet
- Triage API → Case intake: returns result
- Case intake → Result views: renders result
- Result views → Human reviewer: presents for review