Architecture Zero

A self-hosted AI assistant platform where trust is measured, not claimed.

Most "AI systems" are a text box, an API key, and a prompt. This is the rest: hybrid retrieval with a cross-encoder reranker behind a swappable provider seam, tiered access control enforced at four surfaces, an ingest-time injection gate that quarantines hostile content before it can reach an answer, and a judged evaluation harness that scores the system's correctness, groundedness, freshness, and honesty - then publishes those numbers on a public trust panel derived live from stored runs. If a number is on the panel, a run produced it; nothing is hand-set.

Every piece here shipped somewhere real first. The platform is derived from the shared core of production instances that have been running, measured, and incident-hardened - the code carries those lessons as working constraints, not war stories. Nothing in this repository is aspirational.

What's in the box

• Grounded chat - streaming answers with source citations, an agentic tool loop (workspace file tools, clearance-gated, off by default), and honest failure modes: an empty model turn - a refusal stop, a completion with no text - is answered with one plain sentence at the provider's exit, never a blank bubble.
• A built-in onboarding assistant - the platform ships pre-loaded with its own documentation, so a fresh install explains, onboards, and troubleshoots itself from the first question. See the section below.
• Retrieval that earns its rank - vector + full-corpus BM25 fusion, per-source diversity, then a cross-encoder reranker. The reranker is a provider seam: in-process ONNX (baked into the image), a remote scoring endpoint for a GPU box, or a hosted API - selected per call by config, with a fallback chain that degrades to slower, never dumber.
• Departments and tiers - corpus partitions with clearance floors, enforced identically at retrieval, at the file tools, at the answer layer, and on both sides of the federation seam. Unlisted departments fail closed to Owner-only. A long-running work log lives in its own department, searched only when a question is actually history-shaped, with recency weighting inside it.
• The injection gate - every document is scanned at ingestion for instruction overrides, role hijacks, exfiltration patterns, and hidden Unicode. Hot findings in untrusted content are quarantined for owner review; the owner's own content is tagged, never withheld. Content from federated peers gets the same scan at the chat boundary.
• Judged evals - five rubrics (correctness, faithfulness, freshness, honesty, and a knows-it's-gone check for documents the owner removed on purpose) with a pinned judge that must differ in provider family from the writer, a locked holdout cohort with the tuned-vs-holdout GAP as an overfitting alarm, a mechanically-graded injection-resistance cohort run against a live poisoned plant, retrieval recall with a named-miss gaps list, and a corpus-SHAPE fingerprint on every run so runs measured against a different corpus shape cannot be silently compared (content edits that leave chunk counts alone are not yet visible to it - see the ROADMAP).
• Eco Mode - federate instances: peers contribute labeled, boundary-scanned chunks to answers, with per-peer health tracking and a circuit breaker so a down peer costs nothing. Clearance holds across the seam without either instance trusting the other's word for it: a peer key's scope bounds what LEAVES, a local clearance floor bounds who may RECEIVE, and both answer to the same ladder.
• Operations - route-level authorization on every endpoint pinned by a two-sided test sweep, TOTP MFA with optional enforcement, password re-authentication on every write that raises authority, audit receipts per answer (latency, time-to-first-token, which rerank provider actually served), consistent live backups, and fail-open controls that report their live state so "off" is visible.

Quickstart

Prerequisites: Docker with the compose plugin, and an Ollama install on the host with the embedding model pulled (ollama pull nomic-embed-text) plus a chat model if you want local inference (ollama pull qwen3:8b). On a Linux host, make Ollama listen beyond loopback - its service binds 127.0.0.1 by default, and the containers reach the host through the docker bridge address, so a stock install is unreachable from them until it listens on all interfaces:

sudo systemctl edit ollama    # add:  [Service]  Environment="OLLAMA_HOST=0.0.0.0"
sudo systemctl restart ollama

(Docker Desktop on macOS and Windows does not need this. Port 11434 stays closed at your firewall; this only changes which local interfaces answer.)

The embedder is required whichever provider answers chat. Only the chat model is swappable for a cloud API; embeddings speak the Ollama dialect to EMBED_BASE and have no provider seam. With nothing reachable there the instance still boots, ingestion fails per file, and any question asked with retrieval on - the default - returns a 500 rather than an answer. /api/health reads only the self-check's last pass against the chat endpoint (it calls nothing itself), so it reports healthy throughout. /api/health/ready is the check that sees it: while the instance has documents to serve (the shipped knowledge/ folder counts), its retrieval-lane check embeds a fixed sentence through EMBED_BASE, at boot and on every pass, and readiness answers 503 while that fails.

git clone https://github.com/architecture-zero/architecture-zero
cd architecture-zero
cp .env.example .env    # set JWT_SECRET_KEY - the backend refuses to boot on the placeholder
docker compose up -d --build

Create the Owner account and ask your first question. Claiming a deployment takes a code that the backend prints to its own logs at boot - docker compose logs backend - so a deployment that is reachable before you finish setup cannot be taken by whoever gets there first:

docker compose logs backend | grep -A2 "claim code"

Then open http://localhost:5173 - a fresh deployment routes straight to the claim screen. Paste the code, pick a username and password, and you are signed in as the Owner.

Or claim it from the API instead, which is the same endpoint the screen calls:

curl -X POST localhost:8000/api/auth/setup -H "Content-Type: application/json" \
  -d '{"username":"owner","password":"<strong password>","claim_code":"<from the logs>"}'

Your first question needs no documents of your own: the instance boots already knowing itself (see the built-in onboarding assistant), and the runbook's deploy steps end with the exact call to make.

The platform is API-first: everything - chat (streaming SSE at /api/chat), ingestion, users, evals, the trust panel - is served over a documented HTTP surface, so any client works. A reference web client ships with it (frontend/): chat with citations, the claim screen, and an admin panel covering the trust panel, knowledge base, quarantine review, users, the system prompt, chat controls, guest access, settings, models, audit, monitoring, backup and the ingest queue. It is a reference, not a requirement - the API is the product, and the client is one consumer of it. Full walkthrough: docs/runbook.md.

The built-in onboarding assistant

Architecture Zero does not just ship with documentation - the assistant is its own support channel, pre-loaded with its own manual. The shipped corpus is the product's documentation: a getting-started guide, an operations troubleshooting guide keyed to the exact error strings the code emits (paste the error, retrieve its explanation), the security model, and a guide to what the evaluation numbers mean - plus a synthetic demo company so departments, tiers, and history routing demonstrate without anyone's real data. All of it ingests automatically on first boot.

So the moment the Owner account exists, you can ask the instance itself - "how do I add my first documents?", "why was my upload withheld?", "what does the recall number mean?" - and get a cited answer from its own corpus - retrieval is on by default, so a plain request is already grounded (send "use_rag": false to ask without the corpus). The shipped evaluation seed asks the same class of support questions, so the first run scores how well the instance onboards its own operator - support quality as a measured number from day one.

The assistant also answers from the instance itself, not only from documentation. "What does the ingestion injection scan do?" is a documentation question; "is the scan actually on, on this instance, right now?" is answered from records generated at boot from the live database and ranked above everything else in the context. Those records are Owner clearance, so lower tiers still use the posture surfaces (GET /api/status, and the public trust panel at GET /api/trust). The records carry no document names, no account names, and nothing a user typed - only values the code produced or that passed an allowlist.

That starter corpus is the operator's to replace, and once it is gone nothing in it answers "how do I sign in?" for the people who use the instance. So the product also carries its own help: five short pages for week one - signing in, how answers work, documents and who can see them, data and privacy, a map of the admin panel - shipped inside the backend image and synced at boot into a reserved collection that is never a department. The Help button on the chat shell asks those pages alone: a help question is never answered from your documents, a normal question is never answered from a help page, and the pages never appear in the Knowledge Base tab, the document count or the evaluation fingerprint. HELP_DOCS=false turns the lane off.

Extending it

There is no SDK - the platform's own seams are the developer surface:

• the ingestion gate choke point: every ingestion path shares one gate, so anything you build that writes to the corpus inherits scanning by construction;
• the rerank provider seam: any endpoint speaking the scoring contract can serve ranking;
• the provider registry: any OpenAI-dialect model API is a registry entry plus a key, not an adapter.

Commercial modules exist for the enterprise edges (data connectors with permission-aware sync, SSO), built on this same core in a separate product - see MODULES.md for the honest map of what exists beyond the core and how modules graduate into it.

Repository layout

• backend/app/ - the platform (FastAPI)
• backend/tests/ - the suite CI runs on every push and on the daily schedule
• backend/scripts/ - the measurement harness (retrieval A/B arms, noise bands, answer-layer runs, outside-model holdout authoring, the live-fire injection probe)
• frontend/ - the reference web client (React + Vite, served by nginx)
• scripts/acceptance.sh - end-to-end check against a RUNNING deployment
• knowledge/ - the shipped corpus (help docs + demo company)
• docs/ - operator docs, ingested as corpus
• docker-compose.yml, backend/Dockerfile, frontend/Dockerfile - the single-VM shape

Development

python -m venv .venv
.venv/bin/pip install -r backend/requirements-dev.txt          # Windows: .venv\Scripts\pip
cd backend && ../.venv/bin/python -m pytest tests -q           # Windows: ..\.venv\Scripts\python

The suite mocks the vector store and embedder: no network, no keys, no GPU.

The client, in a container - this works everywhere, including on machines whose OS refuses to load unsigned native modules (see below):

cd frontend
docker run --rm -v "$PWD:/app" -v /app/node_modules -w /app node:24-alpine \
  sh -c "npm ci && npm run type-check && npm test && npm run build"

Or on the host, if you have Node 24+ and your OS allows it:

cd frontend && npm install
npm run type-check && npm test && npm run build
npm run dev          # see the note below before using this

npm run dev proxies /api to http://backend:8000 - the compose service name, which resolves only inside the compose network. Running it on the host against the stock deployment, the page loads and every API call fails to resolve: point vite.config.ts at http://localhost:8000 first, and expect vite to pick a different port since compose already holds 5173.

On Windows, the host path may not work at all, and the error will not tell you why. Smart App Control (on by default on many Windows 11 installs) and corporate WDAC policies block unsigned native binaries, and npm ships native modules unsigned as a matter of course - so vite cannot load its own rollup binary. Every one of npm run dev, npm test and npm run build fails; only npm run type-check still works, since TypeScript is pure JavaScript. Use the container command above. Nothing about deploying is affected: docker compose up --build builds the client inside Linux, where the policy does not apply.

CI runs both suites plus a full-history secret scan, a private-residue guard (a denylist grep that fails the build if lineage from the private deployments this template descends from appears in the tree), dependency and static-analysis scanning (pip-audit, bandit, trivy), and both Docker image builds on every push to main. The scanning jobs and the backend suite also run daily, because the two things they catch - a new CVE filed against a pin that has not moved, and a guard that quietly stopped holding - both arrive without a commit. Findings that cannot be fixed are not silently muted: every entry in the pip-audit ignore list carries its reasoning, what the ignore rests on, and what would retire it.

Known limitations (main, reviewed 2026-10-01)

Stated here rather than discovered later. Each is tracked in ROADMAP.md.

• Sessions end after 30 minutes and you sign in again. Closed 2026-09-21: the reference client now refreshes silently at the fetch layer (frontend/src/sessionRefresh.ts, installed before the first render) - one refresh and one replay on a 401, one refresh at a time across tabs under a Web Lock, the refresh token sent only to the page's own origin or the configured API base. It has its own tests. The banner still appears when a refresh is refused, which is the only case where a session is really lost.
• One box. Queued ingest runs on a worker thread inside the backend, not a separate process, because the vector store is an embedded database on a local directory - a second writing process would corrupt the index. This scales up, not out. The one-turn-at-a-time guard on chat (a second message on a conversation that is still answering is refused with 409) keeps its slots in the same process for the same reason: a second replica would make it per-replica.
• Stop ends the stream, not the generation. Closed 2026-10-01: the web framework cancels a streaming response on a disconnect without closing its synchronous generator, which had left the model generating - on a hosted model, paid tokens - until the abandoned generator was collected. The chat route now answers with ClosingStreamingResponse (backend/app/closing_stream.py), which closes the generator as soon as the response is over, and holds the provider stream in closing(), so the close reaches the provider's connection. Its tests drop a real connection mid-answer (backend/tests/test_stream_close.py).
• /metrics needs METRICS_TOKEN for a scraper. A user session expires faster than a scrape interval matters, so set the static token if you want Prometheus to pull. Unset, the endpoint is still reachable with a signed-in request that holds view_analytics (the Owner, or the Admin preset).
• The client is a reference implementation. It exercises the whole API and is what the acceptance suite drives, but it is a starting point to build on rather than a finished product surface.
• Client test coverage is narrow and deliberately so. The automated tests that mount the chat client cover one rule thoroughly: a message bubble is marked as unstored exactly when no row for it exists on the server, checked across every way a stream can end. That rule is where the defects were, and getting it wrong deletes conversation history, so it is tested as an invariant with a case per stream outcome - together with the paths that touch it or the user's identity (the refusals made before storage, leaving a conversation mid-answer, sign-in and sign-out resets). Since 2026-10-03 two more rules have their cases: the admin panel's saves (a failed read never becomes a write, each switch saves only its own key, a Save stays dark until something changed) and the History list (grouping, rename, a delete that asks once). The rest of the client - layout, model selection, the setup wizard - is covered by the acceptance suite driving a real deployment, not by unit tests. Read a green frontend suite as "those rules hold", not "the client is verified".

License

Apache-2.0. See LICENSE and NOTICE.