Escopo & Arquitetura

Junho de 2026

O que estamos construindo: um fork independente de país da Base Adresse Nationale (a plataforma nacional de endereços da França) — para que qualquer país possa rodar a mesma stack com sua própria geografia administrativa, formato de endereço e tiles de mapa. A BAN existente da França é a fonte upstream e a implementação de referência; o fork é validado com dados e fluxos franceses antes de ser adaptado para outros países.

O que a plataforma produz

O editor (mes-adresses) é o lado da entrada — a ferramenta que os municípios usam para criar e manter uma Base de Endereços Local (BAL/LAB). A saída real da plataforma é:

Saída	Descrição	Freq. de atualização
API de geocodificação	Endpoint HTTP `/search?q=endereço` → coordenadas + resultado estruturado. O principal produto consumido por aplicações downstream, ferramentas de SIG e serviços de emergência.	Tempo real
Download do CSV nacional	~25 mi de linhas de endereço (França). Uma posição por endereço, licença aberta. O conjunto de dados em massa canônico.	Diária
Tiles vetoriais (MVT)	Camada de tiles de endereços para embutir em qualquer mapa MapLibre/Mapbox.	Tempo real
WFS / WMS	Serviços OGC para ferramentas de SIG tradicionais.	Mensal

Uma BAL criada no editor percorre o pipeline e, por fim, aparece nas respostas de geocodificação e no CSV nacional. Esse é o resultado visível. O portal público (adresse.data.gouv.fr) é uma interface gráfica sobre o geocodificador e os arquivos de download, específica da implantação francesa — veja a seção do Portal.

O pipeline de seis repositórios

O pipeline completo, da edição de endereços até a saída geocodificável, abrange seis componentes:

mes-adresses

Next.js · TypeScript

Interface do editor — cria e edita a base de endereços local

↓

mes-adresses-api

NestJS · PostgreSQL + PostGIS · Redis

Backend do editor — armazena a BAL e dispara a publicação para o api-depot

↓

publica o arquivo CSV da BAL

api-depot

NestJS · PostgreSQL

Gateway de submissão — versiona arquivos BAL, gerencia autorizações e notifica a plataforma

↓

webhook NOTIFY_BAN

ban-plateforme

Express.js · MongoDB · Redis

Motor de agregação — consolida todas as BALs + outras fontes, produz exportações CSV + addok

↓

pacote addok (exportação CSV)

addok-docker

Python · Docker

Geocodificador — carrega a exportação do ban-plateforme e atende consultas /search na porta :7878

↓

adresse.data.gouv.fr fora do escopo

Next.js · design system DSFR do governo francês

Explorador público + portal de download — uma interface gráfica sobre o geocodificador. Não faz parte da stack modular.

adresse.data.gouv.fr está fora do escopo. Ele é construído sobre o design system DSFR do governo francês — portá-lo exige uma reformulação visual completa, não apenas tradução. Os consumidores downstream (ferramentas de SIG, apps de roteamento, serviços de emergência) integram diretamente a API do geocodificador. Substituição sugerida para a demo: uma página MapLibre GL (1–2 dias) consultando o geocodificador. Sem necessidade de localização.

Escopo de i18n: o que realmente precisa de infraestrutura de tradução

Componente	Tem UI?	Precisa de i18n?	Justificativa
`mes-adresses`	Sim — editor completo	Sim — ~260 strings	O único app voltado ao usuário na stack. `next-intl` configurado; catálogos EN + ES disponíveis.
`mes-adresses-api`	Não — apenas API REST	Não	As mensagens de erro da API permanecem em inglês técnico. O frontend faz a tradução exibida.
`api-depot`	Não — apenas API REST	Não	~24 strings, técnicas. Mantidas em inglês.
`ban-plateforme`	Não — motor de agregação	Não	Nenhuma superfície voltada ao usuário.
`addok-docker`	Não — API do geocodificador	Não	Retorna JSON estruturado. Neutro quanto ao idioma.
`adresse.data.gouv.fr`	Sim — portal público	Descartado	Fora do escopo. Exigiria i18n + reformulação visual completa.

O trabalho de i18n está restrito a um repositório: mes-adresses, ~260 strings. Configurar o next-intl e extrair todas as ~260 strings para messages/fr.json. Adicionar um idioma depois significa criar um novo arquivo JSON — sem mudanças de código. Esforço estimado: 16–24 h.

Detalhamento da contagem de strings

Categoria	Strings	Observações
Strings de UI do fluxo do app	~260	Rótulos, toasts, mensagens de validação, textos de status — o que os usuários veem no editor
`components/help`	~150 linhas	Texto instrucional longo — baixa prioridade, entregar por último
Páginas legais / de acessibilidade	~100 linhas	Conteúdo institucional do governo francês — reescrito por país, não traduzido
`accent-tool.tsx`	43	Não são strings para traduzir — eles SÃO os caracteres acentuados (ferramenta de teclado para nomes de ruas)

A metodologia correta é fazer grep das linhas que contêm caracteres acentuados do francês, excluir as categorias que não são de UI (texto de ajuda, páginas institucionais, a ferramenta de teclado de acentos), extrair apenas os literais de string entre aspas e deduplicar. Uma varredura de regex mais ampla sobre todos os literais de string gera uma contagem enganosa, por capturar strings técnicas em inglês, caminhos de API e constantes de TypeScript.

Enum no banco — problema à parte

Seis valores de tipo de posição são armazenados como strings em francês no banco de dados: 'entrée', 'bâtiment', 'délivrance postale', 'montée', 'formation spéciale', 'présentation'. É isso que aparece como "entrée" nos pins do mapa. Não dá para resolver só com o next-intl — exige uma migração TypeORM para chaves neutras quanto ao idioma no banco (entrance, building, …) e, então, a tradução de exibição via catálogo de i18n.

Tornando a stack modular: o que abstrair

Oito peças específicas da França precisam ser generalizadas. Em ordem de prioridade:

#	O quê	Onde	Abstração	Esforço
1	Identificador de unidade administrativa código INSEE de comuna em todo lugar	`mes-adresses-api` `api-depot` `ban-plateforme`	Substituir `commune: string` pelo genérico `locality_id: string`. Definir a interface `LocalityService`; FR COG = implementação padrão.	Alto
2	Banco de dados administrativo da França embutido `@etalab/decoupage-administratif` compilado na API	`mes-adresses-api/libs/shared/src/utils/cog.utils.ts`	Abstrair `getLocality(id)`; o FR COG passa a ser uma fonte de dados plugável. Baseado no pipeline `yarn update-cog` existente.	Alto
3	Fontes de tiles de mapa URLs do governo francês fixas em 3 arquivos JSON de estilo	`mes-adresses/src/components/map/styles/*.json` `styles/index.ts`	Converter o JSON estático em objetos parametrizados por variáveis de ambiente. Adicionar `NEXT_PUBLIC_MAP_TILES_URL`, `NEXT_PUBLIC_MAP_GLYPHS_URL`, `NEXT_PUBLIC_MAP_SPRITES_URL`.	Médio
4	API de busca de localidades `geo.api.gouv.fr` para autocompletar comunas	`mes-adresses/src/lib/geo-api/index.ts`	URL já controlada por variável de ambiente (`NEXT_PUBLIC_GEO_API_URL`). Reimplementar `ApiGeoService.searchLocalities()` + `getLocality()`. Dois métodos; o resto do app permanece igual.	Baixo
5	Framework de i18n no editor ~260 strings em francês fixas no código	`mes-adresses/src/**`	Configurar o `next-intl`, extrair todas as strings para `messages/fr.json`. Adicionar um idioma = novo arquivo JSON.	Alto
6	Enum de tipo de posição strings em francês no banco: `'entrée'`, `'bâtiment'`…	`mes-adresses-api` entidade + coluna do banco	Armazenar chaves neutras quanto ao idioma no banco (`'entrance'`, `'building'`…); traduzir os valores exibidos no frontend. Exige uma migração TypeORM.	Baixo
7	Larguras de colunas de identificadores franceses `commune_deleguee varchar(5)`, `code_voie varchar(4)`	`mes-adresses-api/libs/shared/src/entities/`	Generalizar os tamanhos das colunas; renomear para `sub_locality_id`, `street_id`. Exige migração.	Baixo
8	Autorização / habilitação ProConnect (SSO do governo francês)	`api-depot` fluxo de habilitação	Tornar o provedor de autenticação configurável. Fase 1: apenas pin por e-mail (já existe como fallback). ProConnect = plugin opcional.	Médio

Frentes de trabalho

WS1 Extração de strings + enum do banco 16–24 h

Configurar o next-intl no mes-adresses e extrair todas as ~260 strings em francês para os catálogos de tradução. As strings permanecem em francês no fr.json; adicionar um idioma significa adicionar um novo arquivo JSON sem mudanças de código.

Configurar o next-intl — estratégia de chaves/namespaces, pluralização, formatação de datas/números
Extrair todas as ~260 strings para messages/fr.json
Migração TypeORM dos 6 valores de enum de tipo de posição do banco → chaves neutras quanto ao idioma
Envolver os componentes do Evergreen UI onde necessário; tratar pluralização
Entregável: app rodando em francês com zero strings fixas no código

WS2 Camada de modularidade 60–100 h

Implementar as oito abstrações do slide de Modularidade. Ordem de prioridade: identificador de localidade + abstração do COG (itens 1–2) → variáveis de ambiente dos tiles de mapa (item 3) → serviço de busca geográfica (item 4) → migração do enum de posição (item 6). Os itens 7–8 têm prioridade menor e podem vir depois.

Definir a interface LocalityService; FR COG = implementação padrão
Converter os arquivos JSON de estilo de mapa em objetos parametrizados por variáveis de ambiente
Generalizar o campo commune e as larguras de coluna relacionadas nos 3 repositórios de backend
Enum de tipo de posição: migração de banco para chaves neutras quanto ao idioma

WS3 Integração do pipeline para a demo 16–28 h

Integrar o pipeline de submissão e geocodificação usando as variáveis de ambiente e interfaces de serviço estabelecidas na WS2. Os serviços públicos franceses são mantidos onde não escrevem na BAN real; tudo o que escreve é auto-hospedado localmente.

Manter como público: geo.api.gouv.fr (busca de comunas), tiles de mapa do governo francês
Auto-hospedar: api-depot, ban-plateforme (com MongoDB), addok-docker
Configurar via variáveis de ambiente definidas na WS2 — sem URLs de serviço fixas no código
Verificar de ponta a ponta: criar BAL → publicar no api-depot local → ban-plateforme consolida → addok retorna o endereço

WS4 Testes manuais & demo 8–14 h

Verificar o pipeline completo de ponta a ponta com dados franceses. Conjunto de dados inicial: uma comuna de exemplo + BAL com voies e numéros. Construir a página de demo leve do geocodificador. Fluxos principais a testar:

Criar uma BAL → adicionar voies + numéros → publicar → o geocodificador retorna o endereço
Toda a UI do editor exibe corretamente em francês, sem chaves quebradas
O download do CSV contém o endereço submetido

Resumo da estimativa

Frente de trabalho	Esforço
WS1 Extração de strings + enum do banco	16–24 h
WS2 Camada de modularidade (8 abstrações)	60–100 h
WS3 Integração do pipeline para a demo	16–28 h
WS4 Testes manuais + página de demo	8–14 h
Total	~100–166 h