cgalo5758
ac2760a0fe
Write the eight domain-model cards under `docs/models/`, mark M10 10i Done, and update the design docs to v16. Also records Doc 44, which ratifies Decisions 129-133 as amended, and the Doc-39 conformance check that satisfied its gate.
4.4 KiB
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:
- Member-console features — the general-purpose capability roadmap (audit log, REST API, metering-as-capability). Lives in milestones.md.
- 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; the mapping lives in fedwiki-service.md, which is the only status doc where tier names (Public/Standard/Flexible) belong.
- 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".
- 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.