#Arquitetura das APIs

O Gera Base mantem duas superficies de API durante a migracao gradual para Litestar.

#API legada

A API legada fica no servico principal app.py e usa rotas /api/*.

Ela ainda sustenta fluxos historicos da aplicacao:

• autenticacao por sessao;
• gerenciamento visual de templates;
• criacao de bancos e adicao de tabelas em Postgres;
• integracao com n8n;
• logs, backups e rotas administrativas compartilhadas.

Enquanto telas antigas dependerem dessas rotas, elas devem continuar estaveis.

#API versionada

A API versionada fica em litestar_app.py e usa rotas /api/v1/*.

Ela e a superficie recomendada para novas integracoes:

• contratos versionados;
• autenticacao por Bearer token;
• OpenAPI em /schema e /schema/swagger;
• modulos de dominio em gera_base/modules/.
• rotas administrativas versionadas para usuarios, tokens, logs, backups, jobs, metricas e previa de importacao.
• rotas versionadas para CRUD de templates, conversao DDL, views do JSON Viewer e Biblioteca SQL.

#Regra de evolucao

Novas integracoes externas devem preferir /api/v1/*. Rotas legadas devem receber correcoes, compatibilidade e migracoes graduais.

Quando uma rota legada for substituida, mantenha o comportamento antigo ate que:

1. a rota versionada tenha teste;
2. a documentacao da API esteja atualizada;
3. telas e automacoes tenham sido ajustadas;
4. exista um plano claro de remocao ou compatibilidade.

#Cuidados

• Nao remover rotas /api/* sem revisar telas HTML/JS e workflows n8n.
• Nao mover logica grande de app.py em uma unica alteracao.
• Preferir extrair funcoes puras e cobri-las com testes antes de trocar handlers HTTP.
• Nao expor senhas, tokens ou connection strings em respostas publicas.