# Genericity Matrix

## Summary

This page states precisely what is **reusable as-is**, what is a **template to
adapt**, and what is **app-specific and must be authored**. Use it to scope a
new build.

---

## Reusable as-is (do not rewrite)

| Area | Artifact |
|---|---|
| Layering & dependency rule | the package layout and import rules |
| Composition root | the `init.py` shape, idempotency, `get_svc` overloading |
| Web edge | `OpenAPIFirstApp` bootstrap, handler-name = `operationId`, thin handlers |
| CRUD slice | the four-file pattern (model / ports-db / ports-service / converters) |
| Generic CRUD service | the base service adaptor |
| Repository factory | base / populating / cached selection |
| Worker | the poll loop, backoff, retry, status machine |
| Progress bus | the bus port + in-memory adapter + streaming endpoint |
| Human-in-the-loop | the durable pause + question document + resolve endpoint + resume map |
| Infra adaptors | HTTP cache decorator, KV store port, LLM pool scaffold |
| Testing | integration harness with fakes, fixture-parity pattern |
| Docs | GSDFC + generated stubs + MCP bundle pipeline |

## Template to adapt (copy, then change names)

| Artifact | Change |
|---|---|
| `pyproject.toml` | project name, dependencies |
| `Dockerfile` / `docker-compose.yaml` | service name, ports, services |
| `.env.example` | connection strings, provider keys |
| `openapi.yaml` | every path/schema/operationId |
| `scripts/` | seed and operator tasks |

## App-specific (must be authored)

| Artifact | Why |
|---|---|
| Resource models | the business shape |
| Repository populate/cache rules | the relationships |
| Service business logic | domain behaviour |
| Pipeline families (if any) | the transformation graph |
| Pattern/rule resources | data-driven policy |
| Fixtures & golden outputs | test data |

## The two axes

Everything app-specific reduces to **two axes**:

1. **Resource model** — the set of resources, their fields, relationships, and
   the OpenAPI contract.
2. **Pipeline family** — only if inputs require multi-step transformation.

If you can specify those two axes, the rest of the app follows mechanically.