docs(standards): split genericity matrix and infra adapters into Tier A/B/C
This commit is contained in:
@@ -3,7 +3,9 @@
|
||||
## Summary
|
||||
|
||||
All external systems are reached through adapters in `infra/`. Prefer an
|
||||
existing internal library over writing a new adapter.
|
||||
existing internal library over writing a new adapter; where no library exists,
|
||||
copy the Tier B scaffold from `templates/app`. See the Genericity Matrix for the
|
||||
Tier A / B / C split.
|
||||
|
||||
---
|
||||
|
||||
@@ -31,11 +33,13 @@ existing internal library over writing a new adapter.
|
||||
|
||||
- Transactions use a session context manager provided by the library.
|
||||
|
||||
**Library:** the Mongo operations library (see registry). Do not write raw
|
||||
Motor calls in the domain.
|
||||
**Tier A — Library (Mongo Ops).** Do not write raw Motor calls in the domain;
|
||||
consult the registry and the library's MCP before touching the driver.
|
||||
|
||||
## HTTP response cache
|
||||
|
||||
**Tier B — template.** Copy from `templates/app`; not a standalone library.
|
||||
|
||||
A generic GET cache sits behind a decorator.
|
||||
|
||||
```python
|
||||
@@ -50,6 +54,8 @@ async def list_items(request): ...
|
||||
|
||||
## Event / progress bus
|
||||
|
||||
**Tier B — template.** Copy from `templates/app`.
|
||||
|
||||
A port with an in-memory default adapter (`publish`, `get_events`). Swap for a
|
||||
durable broker in production (see Worker & Progress).
|
||||
|
||||
@@ -59,10 +65,12 @@ External fetchers (files, mail, HTTP) are adapters that wrap ingestion
|
||||
libraries. Construct them in the composition root and inject into
|
||||
orchestrators.
|
||||
|
||||
**Libraries:** the ingestion library (formats) and the mail library (email).
|
||||
**Tier A — Libraries:** Omniread (formats) and Mail Intake (email).
|
||||
|
||||
## LLM clients
|
||||
|
||||
**Tier B — template.** Copy the pool scaffold from `templates/app`.
|
||||
|
||||
When a pipeline calls a model provider, route through a pool adaptor that
|
||||
handles provider selection, retries, and client lifecycle:
|
||||
|
||||
@@ -75,10 +83,17 @@ Providers are selected by `LLM_PROVIDER` and configured by environment.
|
||||
|
||||
## Key-value store
|
||||
|
||||
**Tier B — template.** Copy from `templates/app`.
|
||||
|
||||
For report/snapshot storage, provide a pluggable store port with a Redis
|
||||
adapter and an in-memory fallback.
|
||||
|
||||
## Rule
|
||||
|
||||
If a capability already exists as a library (DB, DI, ingestion, mail, auth,
|
||||
docs), **use it**. Writing a private copy of a library is a defect.
|
||||
- **Tier A (libraries: DB, DI, ingestion, mail, auth, docs, pipelines)** — use
|
||||
the library; writing a private copy is a defect. Query `find_library` first.
|
||||
- **Tier B (cache, progress bus, LLM pool, KV store, composition shape, worker,
|
||||
tests)** — these are template code, not libraries: copy them from
|
||||
`templates/app` rather than searching the registry.
|
||||
- **Tier C (models, business logic, pipeline families, rules)** — author them
|
||||
yourself.
|
||||
|
||||
Reference in New Issue
Block a user