🏗️ Arquitetura¶

Visão geral¶

flowchart LR
    subgraph Cliente
        U[👤 Usuário]
    end

    subgraph Deploy["Containers (Dokploy)"]
        FE["🖥️ Frontend<br/>Flet Web (:8080)"]
        BE["⚙️ Backend<br/>Django REST API (:8001)"]
        DOCS["📚 Docs<br/>MkDocs Material (:80)"]
    end

    subgraph Infra["Infraestrutura on-premise"]
        SQL[("🗄️ SQL Server<br/>PegasusImpercia")]
        AD[("🗝️ Active Directory<br/>ciaimper.com.br")]
    end

    IA["🤖 Maritaca Sabiá API"]

    U -->|HTTPS| FE
    U -->|HTTPS| DOCS
    FE -->|"REST /api (rede interna do compose)"| BE
    BE -->|pymssql| SQL
    BE -->|LDAP/NTLM| AD
    BE -->|HTTPS| IA

Containers¶

Container	Runtime	Porta	Responsabilidade
`backend`	Django + DRF	8001	Toda a lógica de negócio, acesso ao SQL Server e ao AD
`frontend`	Flet Web	8080	Interface do painel — nunca acessa banco/AD diretamente
`docs`	MkDocs Material (Nginx)	80	Este site de documentação

Duas categorias de URL¶

Um ponto importante da arquitetura: existem duas formas diferentes de o frontend se comunicar com o backend, e confundi-las quebra o deploy:

Uso	Variável	Exemplo	Por quê
Chamada servidor-a-servidor (dados da API)	`API_BASE_URL`	`http://backend:8001/api`	Roda dentro do container do frontend, resolve pelo nome interno do Docker
Link aberto no navegador do usuário (gráficos, exportação)	`API_PUBLIC_URL`	`https://api-painelciaimper.syncronnet.com.br`	O navegador do usuário não enxerga a rede interna do Docker — precisa do domínio público

Bancos de dados da aplicação¶

Não confundir os dois bancos envolvidos:

PegasusImpercia (SQL Server) — o banco de produção do ERP que o painel analisa (via pymssql, somente leitura na maioria das operações).
sqlite local (db.sqlite3) — o banco interno do Django, usado só para autenticação/login do próprio painel. Em deploy com containers separados, fica num volume Docker compartilhado (sqlite_data) entre frontend e backend, porque os dois processos fazem authenticate() contra ele.

Rede e conectividade¶

O backend precisa alcançar:

SQL Server (DB_SERVER) — em produção, usar o IP externo do servidor (a VPS não está na rede local).
Active Directory (AD_HOST, IP 192.168.0.2) — está numa rede privada, só acessível via VPN/túnel. Sem isso, a aba Active Directory não funciona a partir do deploy em nuvem.

VPN pendente

Está planejada uma VPN (OpenVPN) entre a VPS e a rede local para resolver esse acesso — até lá, AD_HOST e (se usado o IP interno) DB_SERVER só respondem a partir de dentro da rede/VPN local.