# Architect

> The engineering handbook for how we design, build and review software — one source for people and coding agents.

Cross-project knowledge only: the design method, the artefacts it produces, the standing architecture default, the settled per-stack choices, and the practices that cut across them. Nothing here is client-specific.

Load on demand. Detect the stack from the repository rather than the prompt, then read the two or three pages it maps to — not the whole site. `/docs/start/how-to-read-this` carries the loading table.

Precedence when sources disagree: a direct instruction in the conversation, then the repository's own CLAUDE.md or AGENTS.md, then the code itself, then this site. A page that loses to the code is a page to correct, not to ignore.

Every URL below returns markdown. Drop the `.md` suffix for the rendered page.

## Overview

- [Home](https://architect.factoriel.app/docs/index.md)

## Start here

- [Start here](https://architect.factoriel.app/docs/start.md): Enter the handbook as a person or a coding agent, then load only what the work requires.
- [How to read this](https://architect.factoriel.app/docs/start/how-to-read-this.md): What to load, in what order, driven by the repository rather than the prompt — and what wins when two sources disagree.
- [Working agreement](https://architect.factoriel.app/docs/start/working-agreement.md): The level of context assumed, the non-negotiable principles, and the rule that a finished thought is not handed back as a to-do list.
- [Evidence and forecast](https://architect.factoriel.app/docs/start/evidence-and-forecast.md): Every claim carries a pointer someone can open; every multi-step goal is priced before it starts; every check is proportional to what the change can break.
- [Reporting](https://architect.factoriel.app/docs/start/reporting.md): KISS, no prose — the work-report template, and the four other modes that replace it when the question is not a work report.
- [Secrets](https://architect.factoriel.app/docs/start/secrets.md): A secret is never revealed, whatever its source — the value never reaches the transcript, and exposure is handled by rotation, not by deletion.
- [Git conventions](https://architect.factoriel.app/docs/start/git.md): Commits carry the logged-in identity and nothing else — no co-author trailers, no tool attribution, and no push that was not asked for.

## How-to guides

- [How-to guides](https://architect.factoriel.app/docs/how-to.md): Goal-oriented procedures for designing a system, producing its artefacts and turning accepted rules into executable work.
- [Follow the design method](https://architect.factoriel.app/docs/method.md)
- [Set up the UI system](https://architect.factoriel.app/docs/how-to/set-up-ui-system.md): Install Tailwind and shadcn/ui so copied primitives, tokens, variants and feature boundaries have one durable home.
- [Build an application shell](https://architect.factoriel.app/docs/how-to/build-an-app-shell.md): One chooser, two chromes, and the arithmetic that lets a rail collapse without anything moving — so a navigation design can be tried rather than argued about.
- [Name and wire navigation](https://architect.factoriel.app/docs/how-to/navigation-and-breadcrumbs.md): One destination list feeding the rail, the trail and the home cards — so a screen cannot be called two things by two people.
- [Document a project](https://architect.factoriel.app/docs/how-to/document-a-project.md): Install the canonical product reference, module references and work registers, then connect them with stable requirement identifiers.
- [Write a brief](https://architect.factoriel.app/docs/artefacts/brief.md)
- [Interview and challenge actors](https://architect.factoriel.app/docs/artefacts/panels.md)
- [Model a domain](https://architect.factoriel.app/docs/artefacts/domain-model.md)
- [Resolve open questions](https://architect.factoriel.app/docs/artefacts/open-questions.md)
- [Write a module reference](https://architect.factoriel.app/docs/artefacts/specification.md)
- [Record a decision](https://architect.factoriel.app/docs/artefacts/decision-records.md)
- [Plan delivery](https://architect.factoriel.app/docs/how-to/plan-delivery.md): Turn accepted requirements into outcome stories, size safe vertical slices and place them behind explicit delivery gates.
- [Derive executable tasks](https://architect.factoriel.app/docs/artefacts/tasks.md)
- [Improve layout and spacing](https://architect.factoriel.app/docs/practices/layout-and-spacing.md)
- [Review motion and polish](https://architect.factoriel.app/docs/practices/motion-and-polish.md)
- [Review an existing design](https://architect.factoriel.app/docs/method/red-flags.md)
- [Audit a Java backend](https://architect.factoriel.app/docs/prompts/security-auditor.md)

## Standards

- [Engineering standards](https://architect.factoriel.app/docs/standards.md): The required working rules, standing architecture default, settled technology choices and cross-stack disciplines.
- [Working agreement](https://architect.factoriel.app/docs/start/working-agreement.md)
- [Evidence and forecast](https://architect.factoriel.app/docs/start/evidence-and-forecast.md)
- [Reporting](https://architect.factoriel.app/docs/start/reporting.md)
- [Secrets](https://architect.factoriel.app/docs/start/secrets.md)
- [Git conventions](https://architect.factoriel.app/docs/start/git.md)
- [Architecture default](https://architect.factoriel.app/docs/architecture.md)
- [Hexagonal architecture](https://architect.factoriel.app/docs/architecture/hexagonal.md)
- [The operation](https://architect.factoriel.app/docs/architecture/the-operation.md)
- [Feature structure](https://architect.factoriel.app/docs/architecture/feature-structure.md)
- [Micro-frontends](https://architect.factoriel.app/docs/architecture/micro-frontends.md)
- [Stack choices](https://architect.factoriel.app/docs/stacks.md)
- [Java](https://architect.factoriel.app/docs/stacks/java.md)
- [Spring Boot](https://architect.factoriel.app/docs/stacks/spring-boot.md)
- [Go](https://architect.factoriel.app/docs/stacks/go.md)
- [Go services](https://architect.factoriel.app/docs/stacks/go-services.md)
- [Astro](https://architect.factoriel.app/docs/stacks/astro.md)
- [TanStack Start](https://architect.factoriel.app/docs/stacks/tanstack-start.md)
- [Vite](https://architect.factoriel.app/docs/stacks/vite.md)
- [Tailwind and shadcn/ui](https://architect.factoriel.app/docs/stacks/tailwind-shadcn.md)
- [Railway](https://architect.factoriel.app/docs/stacks/railway.md)
- [Testing](https://architect.factoriel.app/docs/practices/testing.md)
- [The design system](https://architect.factoriel.app/docs/practices/design-system.md)
- [Design craft](https://architect.factoriel.app/docs/practices.md)
- [Agent prompt standard](https://architect.factoriel.app/docs/prompts.md)

## Reference

- [Reference](https://architect.factoriel.app/docs/reference.md): Lookup material — authority maps, choice matrices, checks, tools, adopted standards and exact terminology.
- [Page classification map](https://architect.factoriel.app/docs/reference/page-map.md): Every handbook page classified by the reader's job and by whether it owns a rule.
- [Artefact authority map](https://architect.factoriel.app/docs/artefacts.md)
- [Stack choice matrix](https://architect.factoriel.app/docs/stacks.md)
- [Domain model notation](https://architect.factoriel.app/docs/reference/domain-model-notation.md): The GraphQL SDL, diagram and use-case conventions used to record an accepted domain model.
- [The checking scripts](https://architect.factoriel.app/docs/reference/checks.md): Three scripts that answer questions nobody can answer by reading — documentation consistency, requirement coverage, and an independent panel.
- [Tools](https://architect.factoriel.app/docs/reference/tools.md): The second-opinion model, the browser, the documentation fetcher, and the identity toggle — with the invocation details that are load-bearing.
- [Standards adopted](https://architect.factoriel.app/docs/reference/standards.md): Every naming and structuring scheme in force here, with where it comes from — so it can be looked up rather than taught.
- [Glossary](https://architect.factoriel.app/docs/reference/glossary.md): The terms this site uses in a specific sense, and the ones it deliberately refuses.

## Rationale

- [Rationale](https://architect.factoriel.app/docs/rationale.md): Why the standards exist, which costs they avoid, and where their boundaries and trade-offs lie.
- [Open systems](https://architect.factoriel.app/docs/method/open-systems.md)
- [Configurability boundary](https://architect.factoriel.app/docs/method/configurability.md)
- [Eight principles](https://architect.factoriel.app/docs/method/principles.md)
- [Four lenses](https://architect.factoriel.app/docs/method/lenses.md)
- [Naming](https://architect.factoriel.app/docs/method/naming.md)
- [Red flags](https://architect.factoriel.app/docs/method/red-flags.md)
- [Why hexagonal architecture](https://architect.factoriel.app/docs/architecture/hexagonal.md)

## Optional

- [Every page, concatenated](https://architect.factoriel.app/llms-full.txt): the entire site as one file — read it only when the loading table above is not enough