---
title: Architecture
description: "One repo, flat subdirectories, and why the docs lead the code."
---

# Architecture

## One repo. No code.

```text
be-internal/                  ◀── ONE GitHub repo. The only one.
├── docs/
│   ├── be-category-name/      an area: a team, a product, a system
│   ├── be-category-name/
│   ├── be-category-name/
│   ├── handbook/                 how to work here
│   └── how-to-fly/               how the system works
├── .claude/                      the harness — one, shared
└── CLAUDE.md                     the rules
```

There are no repos inside this one. No source, no builds, no packages.
Everything here is research, architecture and requirements.

## The docs lead, the code follows

```text
   PRODUCT SIDE                       ENGINEERING
   be-internal/docs/                  the codebase
  ┌─────────────────────┐            ┌─────────────────────┐
  │  what we WANT       │ ── PR ───▶ │  what gets BUILT    │
  │  source of truth    │            │                     │
  │                     │ ◀─ proves ─│  meets the reqs     │
  └─────────────────────┘            └─────────────────────┘

   the arrow never reverses:
   the codebase does not get to redefine the requirement
```

We architect from what we want, not from what exists. Docs that describe the
code inherit its compromises and stop being a target. That is why this repo
has no read access to source — see [Handoff](/how-to-fly/handoff).

## Flat subdirectories

```text
   docs/be-*                    docs/products/be-*/specs/
        │                       docs/teams/be-*/notes/
        │  one level                 │
        ▼                            ▼
   new area = new folder        which folder was it in?
   published immediately        depth is where staleness hides
```

One level under `docs/`. A folder is a sidebar group; a file is a page. Add
a folder and it is on the site — no registry, no routing config.

## The name carries the category

```text
   be  -  category  -  name
   │           │            │
   │           │            └── which one
   │           └─────────────── what kind of area it is
   └─────────────────────────── ours
```

Grouping comes from sorting the names, not from a parent folder. That is
what keeps flat survivable as areas multiply.

## What it costs

Every area repeats structure — its own `meta.ts`, its own conventions. Flat
trades tidy grouping for zero lookup, and zero lookup is what a cold agent
needs first.