Repository and Standards

A consistent repository layout and a short list of firm rules make a codebase easier to work in, review, and audit. This page describes both. Most rules exist because breaking them caused a real problem somewhere.

Repository layoutCopy Anchor Link

assistant/
  apps/
    web/                    frontend
    api/                    HTTP API, orchestrator, SSE
    workers/                ingestion, sync, eval, retention jobs
  packages/
    model-gateway/          provider adapters, routing, limits, cost
    retrieval/              search, fusion, re-ranking, ACL filters
    ingestion/              parsers, chunkers, enrichment, embedding
    guardrails/             input, content, and output checks
    tools/                  tool definitions and the tool service client
    prompts/                prompt loader, renderer, token budgeting
    shared/                 types, errors, event schemas, request context
  prompts/                  versioned prompt templates (see below)
  config/
    model-routes.yaml
    prompts.yaml
    eval-gates.yaml
  evals/
    datasets/               golden, regression, safety, retrieval sets
    judges/                 judge prompts and calibration data
    runner/                 eval harness
  infra/                    infrastructure as code
  docs/
    adr/                    architecture decision records
    governance/             system card, use cases, model records
    runbooks/

Why this layout:

• Model access, retrieval, guardrails, and tools are packages with clear interfaces, so the orchestrator composes them, and each can be tested and replaced on its own.
• Prompts, routes, and gates are files in the repository, reviewed like code and visible in diffs.
• Evals live next to the code they test, and run in the same CI.
• Governance docs live in the repository, so they update in the same pull request as the change they describe.

General conventionsCopy Anchor Link

Rules for AI codeCopy Anchor Link

These are firm. Reviewers block pull requests that break them.

Model callsCopy Anchor Link

• All model calls go through the model gateway. No provider SDK imports outside packages/model-gateway. A lint rule enforces this.
• Use logical model names (answer, fast, judge), never concrete model IDs, outside route config.
• Every call sets an output token limit.
• Every call receives the request context, so tenant rules, tracing, budgets, and cancellation apply.

PromptsCopy Anchor Link

• Prompts live in prompts/ as versioned files. No prompt text in application code, beyond trivial glue.
• Published versions are immutable. To change a prompt, add a new version and update config/prompts.yaml.
• Templates use explicit variables. Rendering fails on missing variables.
• Untrusted content is always delimited and escaped using the renderer's helpers, never concatenated by hand.

// Wrong: hand-built prompt with untrusted text concatenated in
const prompt = `Answer using these docs:\n${chunks.map((c) => c.text).join('\n')}\nQ: ${question}`;

// Right: versioned template, renderer escapes and delimits sources
const prompt = prompts.render('answer', ctx, { sources: chunks, question });

Retrieval and dataCopy Anchor Link

• Every search goes through the retrieval package, which requires a request context and applies tenant and ACL filters. There is no unfiltered search function exported.
• Never log content. Use IDs.
• Cache keys include tenant ID and, for anything derived from retrieval, permission scope. Use the shared cache key helper.

ToolsCopy Anchor Link

• Every tool declares kind: read | write. Write tools go through confirmation. There is no way to mark a write tool as auto-run without an explicit, reviewed exception in config.
• Tool argument schemas are strict: enums, lengths, and formats wherever possible.
• Tool results are compact: a mapper selects the fields the model needs.

OutputCopy Anchor Link

• Model output is rendered only through the safe markdown component in the frontend. No dangerouslySetInnerHTML or equivalent with model output.

Enforcing rules automaticallyCopy Anchor Link

Rules that depend on reviewers remembering them will eventually be broken. Automate what you can:

Architecture decision recordsCopy Anchor Link

Significant decisions are recorded as ADRs in docs/adr/. Write one when you:

• Add or replace a major dependency, such as a vector store or provider.
• Change a cross-cutting pattern, such as how permissions are resolved.
• Make a trade-off that future engineers will question.

See the template in Key decisions.

Checklist for new codeCopy Anchor Link

• Model calls use the gateway, logical names, token limits, and the request context.
• Prompts are versioned files rendered through the template engine.
• Search goes through the retrieval package with filters applied.
• Logs contain IDs, not content.
• Cache keys use the shared helper.
• New tools declare read or write, with strict schemas and compact results.
• Model output reaches the browser only through the safe renderer.