# Arquitetura do Sistema Vim

Este documento descreve a arquitetura detalhada dos serviços hospedados no servidor Vim, que utiliza Dokku como plataforma de deploy PaaS (Platform as a Service) self-hosted.

## Visão Geral da Arquitetura

O servidor Vim opera como uma plataforma de hospedagem de aplicações baseada em contêineres, utilizando o Dokku como camada de abstração sobre o Docker. Esta arquitetura permite o deploy rápido de aplicações diversas sem a complexidade de um cluster Kubernetes completo, sendo ideal para projetos de médio porte e equipes que precisam de simplicidade na gestão de deploys.

A infraestrutura é composta por três camadas principais: a camada de proxy reverso (Nginx), a camada de aplicação (Dokku com Docker) e a camada de dados (PostgreSQL gerenciado pelo Dokku). O Nginx atua como ponto de entrada para todo o tráfego HTTP/HTTPS, direcionando as requisições para os apps corretos baseando-se no domínio solicitado. O Dokku gerencia os contêineres das aplicações, criando automaticamente imagens Docker a partir do código fonte pushado via Git e expondo as aplicações em portas internas que o Nginx redireciona.

## Diagrama de Arquitetura

```mermaid
flowchart TB
    subgraph Internet ["Internet"]
        direction LR
        Users1((Usuários))
        Devs((Desenvolvedores))
    end
    
    subgraph Vim ["Servidor Vim"]
        subgraph Proxy ["Proxy Reverso"]
            Nginx[Nginx<br/>Ports: 80, 443]
        end
        
        subgraph Dokku ["Plataforma Dokku"]
            DCore[Dokku Core<br/>Dokku<br/>Docker<br/>Buildpacks]
            
            subgraph Apps ["Aplicações Hospedadas"]
                direction LR
                GoHorseBE[GoHorse<br/>Backend]
                GoHorseFE[GoHorse<br/>Frontend]
                GoHorseBO[GoHorse<br/>Backoffice]
                GoHorseSD[GoHorse<br/>Seeder]
                GoHorseJobs[GoHorse<br/>Jobs]
                Sextando[API<br/>Sextando]
                SextandoFE[Frontend<br/>Sextando]
                Agno[Agno<br/>Orquestrador]
            end
        end
        
        subgraph Databases ["Bancos de Dados"]
            PGMain[(PostgreSQL<br/>Main)]
            PGAgno[(PostgreSQL<br/>Agno-DB)]
        end
        
        subgraph Cache ["Camada de Cache"]
            Redis[(Redis)]
        end
        
        subgraph Storage ["Armazenamento"]
            Volumes[Volumes<br/>Docker]
        end
    end
    
    Internet -->|HTTPS/443| Nginx
    Devs -->|Git Push| Nginx
    
    Nginx -->|Route by Host| DCore
    DCore --> GoHorseBE
    DCore --> GoHorseFE
    DCore --> GoHorseBO
    DCore --> GoHorseSD
    DCore --> GoHorseJobs
    DCore --> Sextando
    DCore --> SextandoFE
    DCore --> Agno
    
    GoHorseBE --> PGMain
    GoHorseJobs --> PGMain
    Sextando --> PGMain
    Agno --> PGAgno
    
    GoHorseJobs --> Redis
    
    GoHorseBE --> Volumes
    GoHorseFE --> Volumes
    Sextando --> Volumes
    SextandoFE --> Volumes
```

## Descrição dos Componentes

### Camada de Proxy Reverso

O Nginx funciona como proxy reverso principal, escutando nas portas 80 (HTTP) e 443 (HTTPS). Ele recebe todas as requisições externas e as direciona para os apps corretos baseando-se no cabeçalho Host da requisição. O Nginx também é responsável por terminar o TLS para as conexões HTTPS, fornecendo certificados SSL para os domínios configurados. Esta camada é crítica para a segurança e performance das aplicações, pois concentra o tráfego e permite configuraçõescentralizadas de cache, compressão e balanceamento de carga.

A configuração do Nginx para o Dokku utiliza mapeamento dinâmico de portas. Quando um app é criado no Dokku, ele recebe uma porta aleatória alta (greater than 10000), e o Dokku configura automaticamente o Nginx para rotear o tráfego do domínio configurado para essa porta específica. Este sistema permite que múltiplas aplicações coexistam no mesmo servidor sem conflitos de portas.

### Plataforma Dokku

O Dokku é a peça central da infraestrutura, funcionando como um mini PaaS similar ao Heroku. Ele automatiza o processo de deployment de aplicações, desde o recebimento do código via Git até a disponibilização do container rodando. O Dokku utiliza buildpacks para detectar automaticamente a linguagem de programação da aplicação e escolher o processo de build adequado, suportando Node.js, Python, Go, Ruby, Java, PHP e outras linguagens.

Cada aplicação no Dokku roda em seu próprio container isolado, com variáveis de ambiente configuráveis e links para serviços externos como bancos de dados PostgreSQL e Redis. O Dokku também gerencia automaticamente a reconstrução de containers quando novas versões são pushadas, facilitando significativamente o fluxo de CI/CD.

### Aplicações Hospedadas

O ecossistema do servidor Vim é composto por três projetos principais: GoHorse, Sextando e Agno Orquestrador. Cada um destes projetos segue uma arquitetura de microservices com frontend, backend e eventualmente serviços auxiliares como seeders e jobs.

O GoHorse é o ecossistema mais completo, composto por cinco aplicações distintas. O backend (gohorse-backend) expõe a API principal na porta 5000 e conecta-se ao PostgreSQL main para persistência de dados. O frontend (gohorse-frontend) é a interface web principal доступна na porta 3000. O backoffice (gohorse-backoffice) é a área administrativa disponível na porta 3001. O seeder (gohorse-seeder) é um serviço auxiliar que popula o banco de dados com dados iniciais ou de teste. O gohorsejobs é um serviço de processamento de tarefas assíncronas que utiliza Redis para gerenciamento de filas.

O projeto Sextando também segue uma arquitetura similar, com uma API backend e um frontend separado. Ambos os componentes estão configurados com SSL e acessível via domínios próprios. O Agno Orquestrador é um serviço especializado que utiliza seu próprio banco de dados PostgreSQL (agno-db) isolado do banco principal.

### Camada de Dados

O servidor utiliza PostgreSQL 17 como banco de dados principal, gerenciado pelo plugin Dokku Postgres. O banco "postgres-main" é compartilhado entre as aplicações GoHorse e Sextando, permitindo que cada aplicação tenha seu próprio schema dentro do mesmo banco. Esta abordagem é eficiente em termos de recursos, mas requer cuidado com a nomeação de tabelas para evitar conflitos entre os projetos.

Existe também um banco dedicado "agno-db" rodando PostgreSQL 18.1, utilizado exclusivamente pelo serviço Agno Orquestrador. Esta separação é intencional para isolar os dados de aplicações críticas e permitir diferentes configurações de backup e manutenção para cada serviço.

### Camada de Cache

O Redis é utilizado principalmente pelo serviço GoHorse Jobs para gerenciamento de filas de tarefas assíncronas. O Redis fornece persistência opcional e é configurado com um limite de memória de 128MB, o que é suficiente para o volume atual de jobs processados. A utilização do Redis permite que tarefas pesadas sejam processadas em background sem impactar a responsividade das APIs principais.

## Fluxo de Dados

O fluxo de uma requisição típica começa quando um usuário acessa um domínio configurado, como "gohorsejobs.dokku.rede5.com.br". A requisição chega ao servidor na porta 443 (HTTPS) e é recibida pelo Nginx. O Nginx verifica o domínio solicitado e faz proxy_pass para a porta interna onde o container Dokku está escutando. O container processa a requisição, eventualmente consultando o PostgreSQL ou Redis, e retorna a resposta que segue o caminho inverso até o usuário.

Para deploys, o fluxo começa quando um desenvolvedor faz "git push dokku main" para o repositório Git do projeto. O Dokku recebe o push, detecta a linguagem da aplicação via buildpack, executa o build appropriate (npm install e build para Node.js, por exemplo), cria uma nova imagem Docker e substitui o container antigo pelo novo. Após alguns segundos, a nova versão está disponível em produção.

## Considerações de Segurança

A arquitetura atual implementa várias camadas de segurança. O isolamento de containers garante que cada aplicação tenha seu próprio ambiente isolado, impedindo que falhas de segurança em uma aplicação comprometam as outras. O Nginx como proxy reverso permite configuração centralizada de TLS e cabeçalhos de segurança. As variáveis de ambiente sensíveis (como senhas de banco) são armazenadas no contexto do Dokku e não são expostas nos containers.

Recomenda-se futuramente implementar variáveis de ambiente sensíveis através do plugin Dokku Docker Options e considerar a adição de um WAF (Web Application Firewall) para proteção contra ataques comuns como SQL injection e XSS.