Architecture¶
System context¶
Who talks to whom, across the whole product:
flowchart LR
accTitle: Param Manager product context
accDescr: The user application uses the param-manager library, which speaks HTTP to the fast-param-manager API and keeps a local copy in TinyDB. The desktop front, an extra of the library, also goes through it. The API stores data in MongoDB and delegates identity to Keycloak, exporting telemetry to the OpenTelemetry collector.
APP["Your application<br/>Python"] --> LIB["param-manager<br/>client library · PyPI"]
LIB -->|HTTPS| API["fast-param-manager<br/>API"]
LIB --> TDB[("local TinyDB<br/>one file per instance")]
API --> MONGO[("MongoDB")]
API -->|OIDC · JWKS| KC["Keycloak"]
API -.OTLP.-> OTEL["otel-collector<br/>Tempo · Loki · Prometheus"]
FRONT["Desktop front<br/>param-manager[front] extra"] --> LIB
The two artifacts are released separately, and whatever crosses the arrow between them is contract — see Compatibility.
The server layers¶
The server is strictly layered, and one rule holds everything together: a controller never touches the database. The full flowchart of a request, with Keycloak, cryptography and telemetry alongside, is in API overview.
Each layer owns something the others are not licensed to take over:
controllers/- Translates HTTP into a business call. Declares dependencies through
Depends— this is where the decision of who may call what lives. It does not know MongoDB exists. services/- The rules.
AppServicevalidates permission, encrypts sensitive values and assembles metadata.RuntimeConfigServiceresolves configuration that can change without a redeploy. repositories/- The only place that talks to Mongo. This is where the conditional write that guards against concurrent updates lives.
models/andschemas/models/holds the domain model and, most importantly, theVALIDATORSdictionary that defines what each parameter type accepts.schemas/holds the API's request and response contracts.
Dependency injection is a test contract¶
The controller module exposes the get_app_service factory and re-exports
get_current_user and require_admin. The test suite overrides exactly those
names through app.dependency_overrides. Changing how they are imported
breaks the tests without breaking the application — the worst possible order in
which to find out about a problem.
Concurrency¶
Concurrent state on the server is versioned by AppModel.params_version, a
counter. Never by updated_at. The two used to be the same field, and while
they were, any date normalization on the audit side turned every write into a
conflict — with a diffuse symptom and no failing test.
Read resolution in the client¶
The full flowchart, with all four steps and every exit, is in Client overview.
The order is not accidental. Each step costs more than the previous one, and the last one — TinyDB — exists so that the absence of the API is degradation rather than failure.
Writes have none of this: create_app, upsert_params, delete_param and
delete_app always hit the network, always with a token, and never consult the
cache.
Repository layout¶
fast_param_manager/
├── controllers/ # routers: parameter, auth, admin
├── services/ # AppService, RuntimeConfigService, AuthService
├── repositories/ # AppRepository, RuntimeConfigRepository
├── models/ # ParamModel, ParamType, VALIDATORS, AppModel
├── schemas/ # request and response contracts
├── middlewares/ # keycloak_auth
├── core/ # config, database, metrics, logging, dependencies
└── security/ # crypto_utils
Where state lives¶
| State | Where | Lifetime |
|---|---|---|
| Parameters | MongoDB, one document per application | Permanent |
| Read authentication mode | MongoDB, configuration collection | Permanent, editable by an admin |
| Parameter cache | Client process memory | cache_duration seconds |
| API error mark | Client process memory | api_error_cooldown seconds |
| Survival copy | TinyDB, one file per instance | Until overwritten |
| Keycloak token | Client process memory | Until it expires |