codebase-map.md

Codebase Map

Where things live. The architecture rules carry no paths on purpose, so this is the single place that says — and tests/architecture/codebase-map.arch.test.ts holds it to the tree in both directions.

src/
├── contexts/    # bounded contexts — no barrel, nothing reaches inside another
│   ├── distribution/    # where content comes from and how it is fetched
│   │   ├── application/
│   │   ├── domain/
│   │   │   ├── catalog-parsers/
│   │   │   └── ports/
│   │   └── infrastructure/
│   ├── framework/    # the installation record and everything done to a project
│   │   ├── application/
│   │   │   ├── clean/
│   │   │   ├── doctor/
│   │   │   ├── flows/
│   │   │   ├── framework/
│   │   │   │   └── translator/
│   │   │   ├── global/
│   │   │   ├── install/
│   │   │   │   └── content/
│   │   │   ├── ownership/    # machine plugin claims and safe project detach
│   │   │   ├── plugin/
│   │   │   ├── recipes/
│   │   │   ├── restore/
│   │   │   ├── setup/
│   │   │   ├── shared/
│   │   │   └── uninstall/
│   │   ├── domain/
│   │   │   ├── formats/
│   │   │   ├── manifest/
│   │   │   ├── plugins/
│   │   │   ├── ports/
│   │   │   └── recipes/
│   │   └── infrastructure/
│   ├── tools/    # what a project targets, and what each target declares
│   │   ├── domain/
│   │   │   ├── capabilities/
│   │   │   ├── formats/
│   │   │   ├── models/
│   │   │   ├── ports/
│   │   │   └── profiles/    # one directory per tool
│   │   │       ├── claude/
│   │   │       ├── codex/
│   │   │       ├── copilot/
│   │   │       ├── cursor/
│   │   │       ├── kilo/
│   │   │       ├── opencode/
│   │   │       └── vscode/
│   │   └── infrastructure/
│   ├── telemetry/    # what each billed model call consumed, read from a tool's own transcripts
│   │   ├── application/
│   │   │   ├── forget/    # what measurement keeps on a machine, shown and erased
│   │   │   ├── identity/    # who, if anyone, the measurement names
│   │   │   ├── report/    # what the stored calls consumed in a period, along one axis
│   │   │   └── switch/    # opting a repository in or out, and leaving it clean of the previous version
│   │   ├── domain/
│   │   │   ├── declaration/    # the task a person declares, and whether work is bound to one
│   │   │   ├── formats/
│   │   │   ├── consent/    # a clone's identity, and when it consented
│   │   │   ├── identity/    # the identifier a person chose to be named by
│   │   │   ├── legacy/    # what the previous version wrote, by name and location
│   │   │   ├── ports/
│   │   │   │   ├── bindings/    # the declarations kept beside the ledger, and the lock their writers share
│   │   │   │   ├── forget/
│   │   │   │   ├── identity/
│   │   │   │   └── switch/
│   │   │   ├── report/    # attribution of a call, the days of a report, the axes it splits by
│   │   │   └── switch/    # the previous version's config block, Claude's retention
│   │   └── infrastructure/
│   │       ├── consent/    # reading a clone's identity from the file system, and the consent history file
│   │       ├── declaration/    # where a declaration is kept: git config and the telemetry dir
│   │       ├── forget/    # erasing the telemetry dir, the previous version's files, git config keys
│   │       ├── identity/    # the identity file in the telemetry dir
│   │       └── switch/    # the project config, what an earlier measurement left in a repository, and Claude settings; the clone's consent in git config is `git-consent-adapter.ts`, beside this folder
│   └── translate/    # canonical source to target-native content
│       ├── application/
│       │   └── strategies/
│       ├── domain/
│       │   └── formats/
│       └── infrastructure/
├── kernel/    # shared vocabulary — imports no context, carries no business logic
│   ├── materialization/    # where content lands and how its links follow
│   ├── ports/    # a port two or more contexts both need
│   └── reading/    # getting at a file's location and its content safely
├── presentation/    # everything that talks to a human — depends on contexts, never the reverse
│   ├── commands/    # one file per command, wiring only
│   ├── display/    # rendering a result
│   │   └── telemetry/    # the telemetry report, which outgrew one file beside the others
│   └── prompts/    # asking the user; the decision stays in the context
└── runtime/    # technical services that are not a context
    ├── assets/
    ├── auth/
    │   └── ports/
    ├── filesystem/
    ├── git/
    ├── http/
    ├── platform/
    ├── project-root/
    ├── prompter/
    ├── self-update/
    └── wiring/    # one composition module per context, plus the composition root

Areas

• src/kernel/: what two or more contexts both speak. No context import, no business logic.
• src/contexts/: the five bounded contexts. Nothing reaches inside another; the allowed edges are in architecture.md.
• src/presentation/: commands, rendering, prompts. Depends on contexts, never the reverse.
• src/runtime/: services that are not a context — http, git, auth, assets, filesystem, self-update — and the wiring that composes everything.
• tests/: mirrors src/, one tier per file extension. tests/architecture/ holds the ratchets, tests/golden/ the snapshots, tests/helpers/ports/ the doubles.
• assets/: configs inlined at build time, schemas copied beside the binary.
• scripts/: bundle budget, mutation runner, smoke harness.

Entry points

• src/cli.ts → dist/cli.js, bin aidd.
• src/runtime/wiring/framework.ts — the composition root. Start here when wiring anything.

Where to add things

What	Where
a command	presentation/commands/, plus the use case in whichever context owns the concept
a prompt	presentation/prompts/; the decision it feeds stays in the context
a use case	the context whose concept it serves. There is no landing zone: one that fits nowhere means the contexts are wrong
a tool	one profile directory under contexts/tools/domain/profiles/
a transform shared by two profiles	contexts/tools/domain/formats/; used by one, that profile's own directory
a port used by one context	that context's domain/ports/, adapter in its infrastructure/
a port used by two	kernel/ports/, adapter in runtime/
a runtime service	runtime/<service>/, wired from runtime/wiring/