Ir para o conteúdo

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. AppService valida permissão, cifra valores sensíveis e monta os metadados. RuntimeConfigService resolve 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/ e schemas/
models/ tem o modelo de domínio e, principalmente, o dicionário VALIDATORS que 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
param_manager/
├── __init__.py       # exporta ParamManager e ParamNaoEncontradoError
└── manager.py        # a biblioteca inteira

O cliente é um módulo só. Isso é deliberado: ele é empacotado dentro de executáveis PyInstaller, onde cada arquivo a mais é uma chance a mais de o empacotador não encontrar algo.

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