member-console/design/documents/meta-data-model-design-process.md

Data Model Design Process

How We Work Through Architectural Decisions

Purpose: This document describes the process, approach, and style used to develop the Member Console data model. It serves as a guide for continuing this work across conversation sessions, ensuring consistency in how issues are explored, decisions are documented, and the model evolves.

---

1. Context

The Member Console is open source software designed for cooperative technology organizations. It is not a product built for a single company's immediate needs — it is infrastructure intended for reuse by future tech cooperatives with diverse institutional arrangements. This context shapes every design decision:

• Flexibility over premature simplification. We do not defer architectural questions as "edge cases" when they represent the diversity of institutional arrangements the software must support. A cooperative where one member sponsors another's workspace is not an edge case. An agency managing client-funded projects is not an edge case. These are core business logic.

• Days of thinking to prevent months of rework. The investment in exploratory documentation before schema commitment is deliberate. A structural decision embedded in a database schema is expensive to change once applications depend on it.

• The GCP principle. Billing attachment and resource governance are orthogonal policy axes. "Who controls a resource" and "who pays for a resource" are genuinely distinct questions. The data model must not structurally fuse them. This principle, drawn from analysis of GCP's resource hierarchy, is a foundational design commitment.

---

2. The Design Cycle

Each open issue follows a consistent cycle:

Step 1: Problem Articulation

State what the issue is, why it matters, and what constraints any solution must satisfy. The problem statement should make clear why the current model is insufficient — not just "this is missing" but "this is missing and here is the concrete scenario that breaks."

Step 2: Design Space Exploration

Develop multiple strategies to their logical conclusions. Do not evaluate prematurely. Each strategy should be described with:

• Its structure (how entities relate, what the schema looks like)
• Its strengths (what it handles well)
• Its weaknesses (what it handles poorly or cannot express)
• Where it works best (what kind of platform or institutional arrangement it suits)

The goal is to map the full terrain of possibilities before committing. Typically three to four strategies are sufficient to triangulate the tradeoff space.

Step 3: Scenario Evaluation

Test each strategy against concrete, real-world scenarios that span the range of institutional complexity the software must support. At minimum:

• Solo freelancer (one person, one org, one workspace)
• Small team with a single plan
• Enterprise with departmental billing
• Agency managing client-funded workspaces
• Cross-organization sponsorship or mutual aid
• Mixed or composite funding for a single workspace

Strategies that fail on core scenarios are eliminated. Strategies that handle all scenarios but with different tradeoff profiles are compared.

Step 4: Recommendation and Rationale

Select a strategy and document why. The rationale should address:

• Which constraints it satisfies and how
• What tradeoffs it accepts and why those are acceptable
• How it handles the simple case (the model must not burden solo users with enterprise complexity)
• How it handles the complex case (the model must not prevent enterprises from expressing their institutional arrangements)
• What risks it introduces and how they are mitigated

Step 5: Schema Integration

Update the data model reference to reflect the decision. This includes:

• New or modified table definitions with field-level detail
• Relationship documentation
• Constraint documentation
• "Changes from prior version" annotations where applicable
• Moving the issue from "Open Issues" to "Resolved Decisions" with a summary of the rationale

Step 6: Impact Assessment

Document how the decision affects other open issues. Some decisions resolve parts of other issues or change their framing. Some create new dependencies. The issue dependency graph should be updated.

---

3. Document Structure

The Data Model Reference

The data model reference (data-model-reference.md) is the canonical source of truth for the schema. It contains:

• Table definitions with field-level detail, types, purposes, constraints, and relationships.
• Resolved Decisions documenting architectural choices that have been made, with rationale and references to exploratory documents.
• Open Issues documenting known problems that require exploratory work before schema changes can be made.
• Recommended Issue Resolution Order showing dependencies between issues and a suggested sequence.

The reference is updated after each resolved decision. It is the document a new contributor would read to understand the current state of the model.

Exploratory Documents

Each issue produces one or more exploratory documents (e.g., Document 5, 5.1, 5.2). These are working artifacts that develop the design space and arrive at recommendations. They follow the design cycle described above.

Exploratory documents are numbered by issue. Sub-explorations that arise during analysis of an issue are numbered with a decimal (e.g., 5.1 is a sub-exploration of issue 5).

Naming convention: descriptive title reflecting the question being explored, not the issue number. The issue number appears in the document metadata.

Exploratory documents are retained as design rationale even after their recommendations are integrated into the data model reference. They explain why the model is the way it is, which is as important as what the model is.

Relationship Between Documents

Exploratory Document (develops strategies, evaluates, recommends)
        │
        ▼
Data Model Reference (integrates decision, updates schema, tracks issues)
        │
        ▼
Next Exploratory Document (addresses next issue, informed by updated reference)

---

4. Style and Tone

Analytical Style

• Develop before evaluating. Describe each strategy fully before comparing. Premature evaluation biases the exploration.
• Use concrete scenarios, not abstract arguments. "An agency managing client workspaces" is more useful than "cross-organizational resource sharing." Name the actors, describe their needs, show where the model serves or fails them.
• Name the tradeoffs. Every design decision trades something for something else. State both sides explicitly. "This adds a junction table (cost) in exchange for composable multi-source funding (benefit)" is better than "this is more flexible."
• Respect the problem's complexity. Some problems are genuinely hard. Do not pretend a simple answer exists when it doesn't. Do not add complexity when simplicity suffices. The goal is to find the solution whose complexity matches the domain's complexity — no more, no less.

Writing Style

• Prose-first. Use tables and diagrams to supplement prose, not replace it. The reasoning should be readable as continuous argument.
• Direct and precise. Avoid hedging language when a clear statement is warranted. "This model cannot express composite funding" is better than "this model might have challenges with composite funding scenarios."
• The reader is assumed to be technically sophisticated but not familiar with the specific decisions made in prior sessions. Each document should be self-contained enough to be understood without reading the full conversation history.

Schema Documentation Style

• Every table has a conceptual introduction explaining what the entity is and why it exists as a distinct entity.
• Every field has a stated purpose, not just a type.
• Constraints are documented explicitly, not left implicit in the schema.
• Relationships are documented with cardinality notation.
• Changes from prior versions are annotated so the evolution of the model is traceable.
• Known issues on a table are cross-referenced to the relevant open issue.

---

5. Principles

These principles have emerged through the design process and guide ongoing work:

1. Separate concerns with different lifecycles. Identity, governance, billing, and resource management change at different rates and for different reasons. They should be structurally independent.

2. Billing and governance are orthogonal. Who pays for a resource and who controls a resource are different questions with different answers. The schema must not force them into the same hierarchy.

3. Simple by default, composable when needed. Every structural feature that exists for complex institutional arrangements must be invisible to users with simple needs. Auto-created defaults, hidden intermediary entities, and sensible single-path flows for the common case.

4. Design for the cooperative ecosystem, not a single cooperative. Decisions that optimize for one organization's current needs at the expense of institutional diversity are wrong. The model serves a class of organizations, not one.

5. Entities earn their existence. Every table in the schema must justify itself with a distinct lifecycle, a distinct set of stakeholders, or a distinct set of data requirements that would be awkward to serve from another entity. Junction tables justify themselves by enabling relationships that would otherwise be impossible to express.

6. The schema is the contract. Application logic changes easily; schema changes propagate painfully. Invest the design effort at the schema level. Get the entities, relationships, and constraints right. Application behavior built on a sound schema is straightforward; application behavior compensating for a flawed schema is perpetually fragile.

7. Patronage is a cooperative concept, not an operational concept. The cooperative's relationship with its patrons is about value contributed and membership standing. Internal resource allocation, workspace cost tracking, and usage analytics serve different stakeholders and should live in different parts of the model.

---

6. Current State

Resolved

Decision	Summary
Resource pool model	Pools bridge billing and resources. Billing accounts fund pools; workspaces draw from pools.
Patronage scope	Patronage is attributed to patrons and products, not workspaces.
Metered usage routing	Pool-level metered configuration with explicit billing targets and spending controls.
Role inheritance removed	Flat permission arrays. Inheritance deferred until demonstrated need.
Stripe references removed	Payment processor references will live in integration schemas.
Subscription semantics	Subscriptions are a billing mechanism, not the sole path to product access.

Open Issues (in recommended resolution order)

Phase 1: Identity & Access Foundations

• Issue 2: Invitation State Machine
• Issue 1: Service Accounts & Actor Model
• Issue 3: Roles & Permissions Design

Phase 2: Resource & Billing Mechanics

• Issue 4: Entitlement & Quota Architecture
• Issue 6: Subscription, Purchase & Product Access Semantics
• Issue 7: Cross-Organization Billing Scenarios

Phase 3: Cross-Cutting Concerns

• Issue 8: Temporal Modeling Strategy
• Issue 9: Audit Log Architecture
• Issue 10: Integration Schema Architecture

Exploratory Documents Produced

Document	Title	Status
5	Workspace-Centric vs. Billing-Centric Resource Models	Complete; decision integrated
5.1	Multi-Billing-Account Entitlement Resolution	Complete; decision integrated
5.2	Metered Usage and Patronage Attribution Scope	Complete; decision integrated