ADR-022 — Mock Data Scope

ADR-022 — Mock Data Scope

Status

Accepted

Context

During MVP development, sample data has appeared at various points in the codebase: real feature pages that do not yet have a backend available, showcase components, and backend seed commands. This dispersion creates two concrete risks: fabricated data reaching production disguised as real data, and multiple incompatible sources of truth existing for the same example records.

Maintaining multiple independent mock data sets (one per feature, one per showcase, one for seed) was considered but this multiplies maintenance debt and ensures the data diverges over time.

Decision

Mock data has exactly two permitted uses in this project:

1. Database seeding — when DEBUG=True, mock data populates the PostgreSQL database via Django management commands. The backend uses this data to boot into a functional state during local development.

2. Showcase — mock data is used directly (without going through the database or the API) to display component examples on /showcase pages ([[adr-012-design-system|ADR-012]]).

No other context may use hardcoded data. Real application pages (/roster, /organigram, /structure, /coverage, etc.) must consume live API data exclusively.

The centralized source for mock data is frontend/src/app/shared/mocks/, whose entry point consists of TypeScript exports over a single JSON file representing a complete example clinic. This directory is the mock data SSOT for both contexts.

The two loading flows always start from the same JSON file and diverge from there:

• Database seeding: the JSON (or its backend counterpart) is read by a Django management command that inserts records via the ORM in dependency order (entities without FK first). It runs once when bootstrapping the local environment with DEBUG=True. The result is a functional database that the API serves normally.

• Showcase: the JSON is imported by a TypeScript module that exports typed collections. Showcase components import those collections directly and use them in the template without any HTTP calls. The pattern is always the same: JSON → typed exports → showcase component.

External image URLs (e.g., third-party avatar CDNs) are prohibited. All mock profile photos must reference local assets under /assets/ (avatar system: [[adr-014-user-entity|ADR-014]]).

Consequences

Feature pages that do not yet have an implemented endpoint must show an empty state or a skeleton, never inline fabricated data. This maintains a clear separation between “the backend has no data” and “the backend does not exist.”

The frontend/src/app/shared/mocks/ directory centralizes maintenance: a change in clinic-bienestar.json propagates to the showcase and to any seed helper that imports it. No divergent copies exist.

The prohibition on external image URLs eliminates external network dependencies in offline development environments and in the showcase. Local assets in /assets/avatars/ are versioned alongside the code.

Showcase pages can continue using mock data directly without going through httpResource() or any real endpoint, because their purpose is to exhibit components in isolation, not data integration.

Any new code that introduces hardcoded data outside of shared/mocks/ or outside a Django management command is a violation of this decision and must be rejected in code review.