Architecture

One repo, flat subdirectories, and why the docs lead the code.

Architecture

One repo. No code.

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

   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.

Flat subdirectories

   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

   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.