# Development Strategy

How we get from here to the target architecture.

## The target

The `design/` directory mirrors the normative surfaces of the membcons-db design repository: a 7-module, 63-table architecture (`design/data-model.md`, v16). It is the compass — not a blueprint to build all at once.

| Module | Type | Tables | Question |
|--------|------|--------|----------|
| identity | Domain | 5 | Who is this actor, and how do they authenticate? |
| organization | Domain | 8 | What containers exist, and who can access them? |
| entitlements | Domain | 12 | What capabilities are available, and who provisioned them? |
| billing | Domain | 20 | Who pays, what do they pay for? |
| cooperative | Domain | 2 | What value has this member contributed? |
| audit | Cross-cutting | 5 | What happened, when, and by whom? |
| integration | Cross-cutting | 2 | How does the platform exchange data with external systems? |

Dependencies flow strictly downward: identity → organization → entitlements → billing → cooperative. Cross-cutting modules (audit, integration) observe all domain modules without occupying a position in the chain.

## Four roadmaps

Four distinct roadmaps intersect this repository, and scope confusion between them is how deployment-specific details leak into general-purpose milestones:

1. **Member-console features** — the general-purpose capability roadmap (audit log, REST API, metering-as-capability). Lives in [milestones.md](milestones.md).
2. **Wiki Cafe's FedWiki Service** — a *consumer* of member-console. Our job is to build the features that enable that service, not to execute its roadmap. Its tier spec is the [Discourse post](https://forum.wiki.cafe/t/fedwiki-services/67); the mapping lives in [fedwiki-service.md](fedwiki-service.md), which is the only status doc where tier names (Public/Standard/Flexible) belong.
3. **Open-source launch** — publicizing member-console as a general-purpose project (M10). Drives presentation, first-run experience, and "every visible affordance does what it says".
4. **Design affordances** — the capability surface implied by `design/` (see "Design as compass" below). Sets the long-run direction milestones draw from.

Each milestone in milestones.md carries a **Serves:** line naming its driving roadmap(s). Rules of thumb: tier names stay in fedwiki-service.md; a Wiki-Cafe-only need becomes deployment configuration of a generic capability, not a milestone phase; and anything the service needs but member-console cannot observe (e.g. bytes on the wire) is provider/infra scope — member-console only ingests, records, enforces, and bills.

## Approach

- **Capability-driven**: Build features as they become necessary, not modules for their own sake.
- **Vertical slices**: Each milestone cuts through multiple modules, building the minimum needed from each.
- **Honest thickness**: Don't artificially thin modules to create shortcuts. If the design says a table is needed, include it.
- **Design as compass**: We build toward `design/`, not all of it at once.

## Migration strategy

- **Approach**: Single goose instance, module-prefixed migration files collected in dependency order.
- **Module ownership**: Each module has its own migrations directory. At boot, migrations are collected from all modules in dependency order and run through a single goose instance with one version table.
- **Dependency order**: identity → organization → billing → entitlements (→ audit, integration, cooperative when needed).

## Repository structure

```
internal/
├── identity/           ← core module
│   ├── migrations/
│   └── ...
├── organization/       ← core module
│   ├── migrations/
│   └── ...
├── billing/            ← core module
│   ├── migrations/
│   └── ...
├── entitlements/       ← core module
│   ├── migrations/
│   └── ...
├── fedwiki/            ← integration: FedWiki-specific tables + logic
│   ├── migrations/
│   └── ...
├── auth/               ← cross-cutting (exists)
├── middleware/          ← cross-cutting (exists)
├── db/                 ← shared db infrastructure, migration orchestration
└── ...
```

Core modules live as top-level packages under `internal/`. Integration providers (like `fedwiki/`) sit alongside them. If integrations grow, they can move to `internal/integrations/` without schema changes.