Arquitetura¶
Visão de contexto¶
Quem fala com quem, no produto inteiro:
flowchart LR
accTitle: Contexto do produto Param Manager
accDescr: A aplicação do usuário usa a biblioteca param-manager, que fala HTTP com a API fast-param-manager e guarda uma cópia local em TinyDB. O front desktop, extra da biblioteca, também passa por ela. A API guarda os dados no MongoDB e delega identidade ao Keycloak, exportando telemetria para o coletor OpenTelemetry.
APP["Sua aplicação<br/>Python"] --> LIB["param-manager<br/>biblioteca cliente · PyPI"]
LIB -->|HTTPS| API["fast-param-manager<br/>API"]
LIB --> TDB[("TinyDB local<br/>um arquivo por instância")]
API --> MONGO[("MongoDB")]
API -->|OIDC · JWKS| KC["Keycloak"]
API -.OTLP.-> OTEL["otel-collector<br/>Tempo · Loki · Prometheus"]
FRONT["Front desktop<br/>extra param-manager[front]"] --> LIB
Os dois artefatos são liberados separadamente, e o que atravessa a seta entre eles é contrato — ver Compatibilidade.
As camadas do servidor¶
O servidor é estritamente em camadas, e a regra que sustenta tudo é uma só: controller nunca toca no banco. O fluxograma completo de uma requisição, com Keycloak, criptografia e telemetria nas laterais, está em Visão geral da API.
Cada camada tem uma responsabilidade que as outras não têm licença para assumir:
controllers/- Traduz HTTP em chamada de negócio. Declara as dependências por
Depends— é aqui que mora a decisão de quem pode chamar o quê. Não sabe que MongoDB existe. services/- As regras.
AppServicevalida permissão, cifra valores sensíveis e monta os metadados.RuntimeConfigServiceresolve configuração que pode mudar sem redeploy. repositories/- O único lugar que fala com o Mongo. É aqui que vive a escrita condicional que protege contra gravação concorrente.
models/eschemas/models/tem o modelo de domínio e, principalmente, o dicionárioVALIDATORSque define o que cada tipo de parâmetro aceita.schemas/tem os contratos de entrada e saída da API.
Injeção de dependência é contrato de teste¶
O módulo de controller expõe a fábrica get_app_service e reexporta
get_current_user e require_admin. A suíte de testes substitui exatamente
esses nomes via app.dependency_overrides. Mudar a forma como eles são
importados quebra os testes sem quebrar a aplicação — o que é a pior ordem
possível para descobrir um problema.
Concorrência¶
O estado concorrente do servidor é versionado por AppModel.params_version, um
contador. Nunca por updated_at. Os dois já foram o mesmo campo, e enquanto
foram, qualquer normalização de data no lado da auditoria transformava toda
escrita em conflito — com sintoma difuso e nenhum teste falhando.
A resolução de leitura no cliente¶
O fluxograma completo, com os quatro degraus e todas as saídas, está em Visão geral do cliente.
A ordem não é acidental. Cada degrau é mais caro que o anterior, e o último degrau — o TinyDB — existe para que a ausência da API seja degradação, e não falha.
A escrita não tem nada disso: create_app, upsert_params, delete_param e
delete_app vão sempre à rede, sempre com token, e nunca consultam cache.
Estrutura dos repositórios¶
fast_param_manager/
├── controllers/ # routers: parameter, auth, admin
├── services/ # AppService, RuntimeConfigService, AuthService
├── repositories/ # AppRepository, RuntimeConfigRepository
├── models/ # ParamModel, ParamType, VALIDATORS, AppModel
├── schemas/ # contratos de request e response
├── middlewares/ # keycloak_auth
├── core/ # config, database, metrics, logging, dependencies
└── security/ # crypto_utils
Onde o estado vive¶
| Estado | Onde | Vida útil |
|---|---|---|
| Parâmetros | MongoDB, um documento por aplicação | Permanente |
| Modo de autenticação de leitura | MongoDB, coleção de configuração | Permanente, editável por admin |
| Cache de parâmetros | Memória do processo cliente | cache_duration segundos |
| Marca de erro da API | Memória do processo cliente | api_error_cooldown segundos |
| Cópia de sobrevivência | TinyDB, um arquivo por instância | Até ser sobrescrita |
| Token do Keycloak | Memória do processo cliente | Até expirar |