root@construct:~/projects/tjes$
<-- voltar para /projects
Ilustração: um tribunal desenhado como planta em neon, com documentos saindo das colunas para servidores

Plataforma do TJ-ES

Protótipo de plataforma de gestão do Tribunal de Justiça do Espírito Santo

PythonFlaskVueBootstrapPostgreSQLDocker
Passe o mouse ou foque uma peça: ela acende com as ligações.
quem usaPrograma · dados fictíciosTribunal de Justiça do ESserviços externosProdução (só a TI acessa)2 Design system1 Servidor do Tribunal5 Autenticação3 Repo do programa9 API Flask (P19)6 Front-end Vue (P19)4 Suíte de arquitetura7 Outros projetos12 Sistema de orçamento8 GitLab do Tribunal11 PostgreSQL10 Homologação da TI
12 peças11 ligações4 áreas

>Contexto

O Tribunal de Justiça do Espírito Santo tem 20 projetos de modernização no programa Inovação a Serviço da Justiça, divididos em eixos e times diferentes. Eles nasceram separados, mas dividem peças caras: autenticação, perfis e auditoria, contratos, patrimônio e a própria cara das telas. Se cada time fizer a sua, a mesma peça sai várias vezes, e quem herda tudo no fim é a TI do Tribunal.

Sou engenheiro de software, com bolsa de pesquisa, no programa desde 01/10/2026; a primeira PoC da estrutura compartilhada saiu em 19/09, antes do início oficial. Desde 21/10 atuo em todos os eixos: cuido do design system e dos padrões de arquitetura dos 20 projetos e ajudo os times a ligar as pontas.

No eixo de Engenharia, sigo construindo o Projeto 19 (gestão de obras, contratos e serviços), para a Secretaria de Engenharia, e também estou no Projeto 20 (cadastro técnico imobiliário). Também escrevi a proposta de acesso técnico para a TI do Tribunal: como o programa trabalha sem conta nova, sem acesso a produção e sem dado real fora do Tribunal.

>Arquitetura (HLD)

Infraestrutura do Tribunal de Justiça do ES, zona de produção, só a TI acessa: stack no padrão que a TI definiu em 06/10 (Python 3 com Flask, Vue com Bootstrap, PostgreSQL, Docker). Front-end Vue (P19): SPA em Vue 3 e Vite com Bootstrap, telas montadas só com componentes do design system. API Flask (P19): Python 3.13 em Docker, sete contextos, domínio e casos de uso sem framework, banco nem I/O, adaptadores HTTP, de banco e de sistemas externos na borda, raiz de composição escolhendo o adaptador de cada porta. PostgreSQL: banco de destino atrás da porta de repositório; no desenvolvimento local um repositório em memória atende a mesma porta. Autenticação: contexto de acesso. Sem fila e sem job.

Infraestrutura do Tribunal de Justiça do ES, fora de produção: GitLab do Tribunal com a cópia do código e um pipeline com a mesma checagem; homologação e publicação pela TI; os outros projetos do programa (20 projetos, um padrão).

Ambiente do programa, só dados fictícios: repositório do programa; suíte de arquitetura rodada pelo make check a cada push (contratos do import-linter e regras do dependency-cruiser; ruff, mypy, xenon e pytest com cobertura no back-end; vue-tsc, ESLint, Vitest e build no front-end e no design system); design system compartilhado, pacote Vue 3 sobre Bootstrap 5.3 com tokens pelo método do Carbon da IBM e a marca do portal do Tribunal.

Desenvolvimento local: o Flask sobe numa porta, o Vite repassa as chamadas de /api para ele e um repositório em memória fica no lugar do PostgreSQL.

Externo: sistema de orçamento, acessado pela API dele ou substituído por um arquivo de exemplo.

Servidor do Tribunal (Secretaria de Engenharia) → Front-end Vue: navegador.

Servidor do Tribunal → Autenticação: login.

Front-end Vue → API Flask: REST em /api; a rota só traduz HTTP para um caso de uso.

Vite → Flask (desenvolvimento local): chamadas de /api repassadas para a porta do Flask.

API Flask → PostgreSQL: SQL pela porta de persistência.

API Flask → Sistema de orçamento: porta de orçamento, chamada síncrona ao importar um orçamento; dois adaptadores escolhidos pela configuração na raiz de composição: cliente da API ou arquivo de exemplo.

Design system → Front-end Vue (P19): componentes.

Design system → Outros projetos: componentes.

Repo do programa → Suíte de arquitetura: todo push roda o make check.

Repo do programa → GitLab do Tribunal: cópia do código.

GitLab do Tribunal → Homologação da TI: homologação.

Homologação da TI → API Flask: publicação em produção, só pela TI do Tribunal.

Componentes

  • Design system compartilhado :: Pacote Vue 3 sobre Bootstrap 5.3, com tokens pelo método do Carbon da IBM e a marca do portal do Tribunal, de onde saem as telas do P19 e dos outros projetos.
  • Front-end Vue por projeto :: SPA em Vue 3 e Vite que monta as telas só com componentes do design system e chama a API do projeto por REST.
  • API Flask por contexto :: Back-end em Python 3.13 organizado em sete contextos, com domínio e casos de uso sem framework, banco nem I/O, e adaptadores HTTP, de banco e de sistemas externos na borda.
  • Porta de orçamento :: Traz o orçamento do sistema de orçamento por API ou de um arquivo de exemplo; a configuração escolhe o adaptador, e domínio e casos de uso não mudam.
  • Persistência :: PostgreSQL, o banco do padrão da TI; hoje um repositório em memória atende a mesma porta.
  • Suíte de arquitetura :: Contratos do import-linter e regras do dependency-cruiser rodam no make check a cada push e reprovam quem quebra a regra da dependência.
  • Fluxo de entrega :: Código no repositório do programa, só com dados fictícios, copiado para o GitLab do Tribunal; homologação e publicação em produção só pela TI do Tribunal.

>Trade-offs

Flask, Vue, Bootstrap e PostgreSQL, o padrão da TI do Tribunal.

Alternativa descartada: React e Node com TypeScript, a stack da primeira PoC, de 19/09.

Por quê: A TI apresentou o padrão do Tribunal em 06/10, e é ela quem mantém o código depois que o programa acaba. A decisão antiga ficou registrada como substituída.

Regras de arquitetura verificadas por teste.

Alternativa descartada: Regra escrita num documento e cobrada na revisão de código.

Por quê: Com vários times no mesmo padrão, a regra precisa reprovar sozinha. Trocar o arquivo de exemplo pela API real, ou a memória pelo PostgreSQL, vira trocar um adaptador na raiz; domínio e casos de uso não mudam.

Design system aprovado como protótipo antes de virar componente Vue.

Alternativa descartada: Escrever os componentes Vue direto e ajustar depois.

Por quê: Pedi a opinião da coordenação e dos times antes de fixar a forma de uso: o que falta para cada projeto e o que mudaria. Componente só entra no pacote com teste.

>Destaques

  • >Proposta de acesso com 4 compromissos: nenhuma conta nova no Tribunal para as soluções novas, zero acesso a produção, nenhum dado real fora do Tribunal e todo o código copiado no GitLab do Tribunal.
  • >4 contratos de arquitetura no back-end e 10 regras no front-end; no back-end, complexidade acima de 5, mais de 4 parâmetros ou cobertura abaixo de 90% reprovam a checagem.
  • >Protótipo do design system com 6 componentes documentados em Uso, Estilo, Código e Acessibilidade, tema claro e escuro e 3 telas clicáveis do P19.

>Curiosidades

  • *Em 19/09, 12 dias antes do início oficial, escrevi no grupo do squad que tinha ficado a manhã de bobeira e já tinha feito uma pequena PoC com uma estrutura compartilhada.
  • *O protótipo do design system abre sem internet: fontes, ícones e Bootstrap vêm dentro do pacote, nada de CDN.
  • *No P19, o domínio não pode importar nem os, json ou logging: o contrato io-free-domain reprova qualquer I/O.
  • *Código 100% em inglês e tela em português: um glossário numa ADR leva orçamento para budget, medição para measurement e diário de obra para site_diary.
Plataforma do TJ-ES | The Broad Way | Kinho.dev