The Atlas

Donna's documentation, bound to its code

Journeys

First hour with Donna

Orientation: what Donna is, the one architectural idea everything follows from, and where to go next. Four short reads plus the docs map.

5 stops →

The BFF trust boundary

How auth actually works, prose bound to the server code: the global guard, the httpOnly cookie session, and the authed client that refreshes on 401.

5 stops →

How a feature ships here

The superpowers build loop, with a real shipped feature as evidence: brainstorm → spec → plan → TDD → review → merge-commit PR.

5 stops →

The lq-ai contract & upstream loop

Donna implements no legal-AI logic — it consumes a contract. This is what happens when the contract isn't enough: file an ask, relay it, bump the pin.

5 stops →

Getting Started

The front door for a new contributor. README is run-it-now (Docker + Compose, Node 22, the shifted ports, the admin fixture); CLAUDE.md is the engineering guide that explains the whole project model — the BFF, the cardinal rules, the superpowers build loop, and how to pick up the roadmap. Read README to stand it up, CLAUDE.md before your first change.

CLAUDE.md — engineering guide for Donna Before your first change — the map of how to build in Donna well.
Donna Your first stop: cloning the repo and standing the stack up.

Product

What Donna is and why, independent of the code. PRODUCT.md is the vision — a reading-first, transparency-first frontend that makes the LQ.AI legal-AI backend usable and controllable without implementing any legal-AI logic itself. The docs index points at everything else and reminds you the richest, most current guide lives in-app at /about.

Donna — `docs/` index When you need to find which doc covers a topic.
Donna — Product Overview First, to understand what Donna is and the scope it deliberately holds.

Architecture

How Donna is actually built, verified against the tree. ARCHITECTURE-ANALYSIS walks the BFF trust boundary, the streaming chat pipeline, the citation→doc- panel flow, the Automations state machine, and the real tech stack — with honest shipped/partial/deferred status. The repository-explorer README documents the sibling static docs site this Atlas complements.

Donna — Architecture & Technology Analysis Before building on a subsystem — the canonical, code-verified structure.
Donna — Repository Explorer To regenerate or understand the static repository-explorer site.

Contributing & Releases

How the project is run and what protects it. CONTRIBUTING is the short contributor path into CLAUDE.md plus the quality bar; BRANCHING explains the Altien-fork two-branch model (altien-main is dev, main mirrors upstream); CHANGELOG records the v0.1.0 first public release. Two rules recur everywhere: never edit vendor/lq-ai, always merge (never squash).

Branching policy — Altien fork Before creating a branch in the Altien fork, or pulling upstream.
Changelog To see exactly what shipped in the first public release.
Contributing to Donna Before opening a PR — the workflow and quality gates in brief.

Decisions

The durable record of the one decision that changes what backend you are on: which lq-ai commit the vendored submodule is pinned to. lq-ai-pin.md is the running bump log — read its top entry to know the current pin and what each bump unblocked.

Decision: lq-ai backend pin When bumping the pin, or to check whether a capability is already upstream.

Upstream Requests

The Donna→lq-ai contract negotiation. When the published API can't do what a feature needs, the gap is written here as a proposed contract (endpoint, field names, why) rather than patched into the submodule — then relayed upstream and pinned when it merges. A mix of resolved asks (the four P1 baseline asks, anonymization-in-receipts, per-message file attach) and open ones.

Roadmap

What's deferred and why, with the context to pick it up. The future roadmap sorts remaining work into upstream-blocked vs buildable-now; the autonomous- workflows scope is the original (now-shipped) Automations analysis, preserved as the template for how a backend-driven segment gets scoped before code.

Autonomous workflows — implementation scoping (Donna) As the model for scoping a new backend-driven segment before coding.
Donna — future roadmap When deciding what to build next, or when an upstream change lands.

Research

The design research behind the reading-first interface: a full scope and a screen-by-screen UX reconstruction of MikeOSS, written to guide a frontend that adopts its document-forward visual language on top of LQ.AI's verified- citation, anonymization and tier-enforcement engine.

Mike-LQ Frontend Scope When building the reskinned frontend, as the implementation contract.
MikeOSS UX Breakdown — Reference for the Mike-LQ Frontend Build When implementing a visual surface, alongside the scope doc.

Design Archive

The superpowers design + execution archive: a spec and a task-by-task plan for every shipped phase, plus point-in-time session handoffs and notes. Indexed for full-text search and readable in full, but not curated or drift-checked — these are historical records that go stale by design. Read the closest analog before building something new.