LORE Architecture Overview

ELI5

LORE is like a giant library where all the decisions made by AI agents are stored. Humans visit this library to search what agents have decided, curate the best decisions, and extract patterns. It is the “official record” — clean, organised, and permanent. Think of it as the published book, while CAIRNET is the messy notebook agents scribble in.

Technical Deep Dive

LORE (lore.devarno.cloud) is a standalone Next.js 14 dashboard deployed on Vercel. It serves as the authoritative, human-facing knowledge library for the devarno-cloud ecosystem. LORE proxies all data operations to the pebble FastAPI backend at mcp.devarno.cloud via /api/knowledge/* REST routes.

Core Stack

• Frontend: Next.js 14 (App Router), React 18, Tailwind CSS 4, Mars forced-dark theme, shadcn/ui components, pure SVG charts
• Auth: Airlock SSO via cross-subdomain .devarno.cloud cookies — zero local auth state
• Backend proxy: Next.js API routes forward to pebble FastAPI with typed Result<T> semantics
• Database: Postgres via pebble (shared with airlock), proof_decisions table
• Brand: Canonical devarno-gh-avatar favicon set

Design Philosophy

LORE is read-biased. Humans search, browse, curate, and extract learnings. The write path is gated: only through the log_decision MCP tool (agent-initiated) or the CAIRNET graduation pipeline (human-gated, one-way). There is no direct human write UI in LORE itself.

Key Architectural Decisions

• Unconditionally dark Mars theme (forcedTheme="dark", no system light-mode leak)
• All data flows through pebble — LORE has zero direct DB access
• Result<T> contract replaces silent null fallbacks with typed failure semantics
• DegradedBanner component surfaces three outage classes (outage, permission, shape-drift)
• Shared CausalityGraph SVG primitive for decision relationship visualization

Key Terms

• Pebble → MCP gateway backend; LORE’s sole data source
• Result → Typed union: { ok: true, data: T } | { ok: false, status, reason, detail } — replaces silent null fallbacks
• Airlock SSO → Cross-subdomain auth via .devarno.cloud cookie; no local auth config needed
• Mars theme → Forced-dark palette used across all devarno-cloud dashboards (void/oxide/signal/dust/regolith)
• DegradedBanner → UI component surfacing three API failure classes: outage (5xx), permission (403), shape-drift (unexpected response)
• CausalityGraph → Pure SVG component rendering upstream/downstream decision relationships

Q&A

Q: How does LORE authenticate users? A: Via Airlock SSO — the browser sends the .devarno.cloud session cookie, LORE’s middleware validates it with airlock, and emits x-lore-user-* headers with role info.

Q: Does LORE have its own database? A: No. LORE is a stateless proxy. All data is stored in pebble’s shared Postgres instance.

Q: How does LORE differ from hubble? A: Both are read-biased Mars-themed dashboards, but LORE surfaces agent decisions and knowledge while hubble aggregates cross-org operational intelligence from 7 data sources.

Examples

LORE is to agent decisions what a law library is to court rulings — the permanent, curated, human-readable record. CAIRNET is the courtroom where arguments happen in real time.