Genericity Matrix
Summary
This page states precisely what is library-backed, what is template-provided, and what is app-specific and must be authored. Use it to scope a new build and to know, for any given capability, whether to call a library, copy template code, or write it yourself.
Tier A — Library-backed (use; never reimplement)
These capabilities already exist as internal libraries. Reach them through the
library registry MCP (find_library(capability)) and read the library's own MCP
for its API. Writing a private copy of any of these is a defect.
| Capability | Library | MCP |
|---|---|---|
| Persistence: repositories, cache, populate, transactions | Mongo Ops (mongo_ops) |
:8007 |
| Dependency injection / composition | Hexa (hexa) |
:8008 |
| Deterministic multi-step transformation engine | DAG Pipe (dagpipe) |
:8006 |
| Spec-first HTTP edge, client, codegen | OpenAPI First (openapi_first) |
:8004 |
| Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) | Omniread (omniread) |
:8003 |
| Read-only email ingestion | Mail Intake (mail_intake) |
:8002 |
| JWT auth primitives (register, login, introspect) | Py JWT (jwtlib) |
:8005 |
| Documentation build (MkDocs + MCP) | Doc Forge (docforge) |
:8001 |
Tier B — Template-provided (copy from templates/app, then adapt)
These are reusable internal components shipped inside the template — they are not independent libraries. Copy them as-is, then rename/populate only what is app-specific. They give every app the same wiring shape as the reference app.
| Component | Template location | Action |
|---|---|---|
| Layering & dependency rule | the package layout + import rules | keep |
| Composition root shape | init.py (get_svc/get_db, idempotency) |
keep |
| Spec-first web edge | interfaces/openapi.py, thin handlers bound to operationId |
keep |
| CRUD slice pattern | domain/<resource>/{models.py, ports/db.py, ports/service.py, converters.py} |
rename + fill |
| Generic CRUD service | infra/adapters/service.py (CrudsServiceAdaptor) |
keep |
| Repository factory | infra/db/repos/mongo.py (_repo_factory) |
keep |
| Worker poll + status loop | worker.py |
keep |
| Progress bus + streaming | bus port + in-memory adapter + SSE endpoint | keep |
| Human-in-the-loop | durable pause + question document + resolve endpoint + resume map | keep |
| HTTP response cache | cache_response decorator + generation invalidation |
keep |
| Key-value store | KV store port + Redis adapter + in-memory fallback | keep |
| LLM client pool | provider-select + retry pool scaffold | keep |
| Pipeline scaffold | pipelines/shared/{ports,loader,registry}.py + pipelines/<family>/ |
rename + fill |
| Operator scripts | scripts/ (init() / get_svc() / shutdown()) |
rename |
| Testing harness | integration fakes + fixture-parity pattern | keep |
| Project scaffolding | pyproject.toml, Dockerfile, docker-compose.yaml, .env.example, openapi.yaml |
rename + fill |
Tier C — 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 | the transformation graph |
| Pattern/rule resources | data-driven policy |
| Fixtures & golden outputs | test data |
The two axes
Everything app-specific reduces to two axes:
- Resource model — the set of resources, their fields, relationships, and the OpenAPI contract.
- Pipeline family — only if inputs require multi-step transformation.
If you can specify those two axes, the rest of the app follows mechanically: Tier A is imported, Tier B is copied, and Tier C is the only thing you author.