LORE Route Structure & Data Model

lore intermediate 8 min read

ELI5

LORE has different “rooms” or pages, each showing a different view of agent knowledge. You can search everything, zoom into one decision, browse which agents exist, see how decisions connect, and check the rules agents follow. All the data comes from a big shared database through a single pipeline.

Technical Deep Dive

App Router Page Structure

Route	Page	Purpose
`/`	redirect	302 → `/overview`
`/overview`	overview/page.tsx	Hero stats, recent decisions table, governance summary card
`/search`	search/page.tsx	Full-text search across all proof_decisions with filter surface (org, agent, type, date range)
`/decisions/[id]`	decisions/[id]/page.tsx	Single decision detail with metadata, body, causality graph, and CAIRNET backlink
`/agents`	agents/page.tsx	Agent roster — lists all known agent_ids with profile summaries
`/governance`	governance/page.tsx	Read-only display of active COUNCIL.yaml and privilege scopes
`/analytics`	analytics/page.tsx	Ecosystem-wide decision metrics, trend charts, org breakdowns
`/graph`	graph/page.tsx	Interactive full causality DAG of all decisions
`/api-reference`	api-reference/page.tsx	Self-documenting API playground

API Proxy Routes

All under /api/knowledge/* — LORE uses explicit Next.js route handlers that wrap lib/knowledge-api.ts:

GET  /api/knowledge/search        → pebble GET  /api/knowledge/search
GET  /api/knowledge/decisions     → pebble GET  /api/knowledge/decisions
GET  /api/knowledge/decisions/:id → pebble GET  /api/knowledge/decisions/:id
GET  /api/knowledge/agents        → pebble GET  /api/knowledge/agents
GET  /api/knowledge/agents/:id    → pebble GET  /api/knowledge/agents/:id
GET  /api/knowledge/governance    → pebble GET  /api/knowledge/governance
GET  /api/knowledge/stats         → pebble GET  /api/knowledge/stats
GET  /api/knowledge/graph         → pebble GET  /api/knowledge/graph
GET  /api/knowledge/decisions/:id/cairn-stones → pebble GET  /api/knowledge/decisions/:id/cairn-stones
POST /api/knowledge/log-decision  → pebble POST /api/knowledge/decision
GET  /api/knowledge/explore       → pebble GET  /api/knowledge/explore

Data Model

The canonical record is the proof_decisions table in pebble’s Postgres:

Field	Type	Description
`id`	UUID	Primary key
`decision_id`	VARCHAR	Human-readable slug
`timestamp`	TIMESTAMPTZ	ISO 8601, agent-local time
`agent_id`	VARCHAR	`human:<airlock-id>` or `agent:<org>/<role>/<name>`
`agent_role`	VARCHAR	coordinator / researcher / worker
`decision_type`	VARCHAR	go-no-go, timeline-arbitration, conflict-resolution, task-execution, etc.
`org_slug`	VARCHAR	GitHub org name (tenant isolation)
`repo`	VARCHAR	Source repo
`summary`	TEXT	Human-readable summary
`body_json`	JSONB	Full decision document
`commit_hash`	VARCHAR	Git commit anchoring the decision
`graduated_from_cairn_id`	UUID nullable	FK to `cairn_stones.id` if graduated from CAIRNET

Key Terms

proof_decisions → The canonical Postgres table storing all formal agent decisions
cairn-stones backlink → Reverse lookup on cairn_stones.graduated_to_lore_id using LIKE match
graduated_from_cairn_id → Nullable FK column linking a LORE decision to its parent CAIRNET stone
org_slug → GitHub org-based tenant isolation field for cross-org queries
decision_id → Human-readable slug identifying a decision (not the UUID)

Q&A

Q: Does LORE use rewrites or explicit route handlers? A: Explicit Next.js route handlers. Each /api/knowledge/* path has its own route.ts that invokes lib/knowledge-api.ts with typed Result<T>.

Q: How are decisions uniquely identified? A: By decision_id (human-readable slug) — not just UUID. The id is UUID but queries and links use decision_id.

Q: What happens when pebble is down? A: The Result<T> contract surfaces { ok: false, status: 502, reason: "outage" }, and the DegradedBanner component renders an outage variant.

Examples

LORE’s routes are like a library’s catalogue system — the search room, the reference desk (detail page), the author index (agents), the policy shelf (governance), and the statistics board (analytics), all fed by one central cataloguing system (pebble).

neighbors on the map

LORE RBAC & Airlock Auth Flow implementing authentication in a new LORE page
LORE+CAIRNET Backlink & Provenance Tracking understanding how LORE decisions trace back to CAIRNET stones