Arquitetura Técnica
1. Resumo Executivo
O Elo Orgânico é uma plataforma de gestão integrada para ciclos de compartilhamento de produtos orgânicos. O sistema é construído sobre uma arquitetura de Monorepo utilizando PNPM Workspaces e Turborepo, priorizando alta performance, tipagem estrita e isolamento de domínio através de uma estratégia de Contextos Delimitados (Bounded Contexts).
A arquitetura é projetada para um modelo de "Plataforma Singleton / Instância Multi-Tenant", garantindo que o marketplace global e as operações específicas de cada comunidade sejam desacoplados lógica e fisicamente no nível raiz.
2. Estrutura do Monorepo & Papéis das Aplicações
A base de código é organizada em Contextos de Domínio na raiz. Distinguimos entre Portal (Plataforma) e Instância (Comunidade). O diagrama a seguir ilustra as relações entre os pacotes e o fluxo de dependências:
| Diretório | Nome do Pacote | Papel | Responsabilidade |
|---|---|---|---|
| portal/apps/web | @elo-portal/web | Singleton | Esqueleto do futuro hub de onboarding SaaS e fundação da plataforma. |
| portal/apps/api | @elo-portal/api | Singleton | Fundação da API de gestão global, orquestração de tenants. |
| portal/packages/core | @elo-portal/core | Library | SSOT para a fundação da plataforma global. |
| instance/apps/api | @elo-instance/api | Instância | API REST Fastify para uma instância de comunidade específica. |
| instance/apps/web | @elo-instance/web | Instância | React SPA (Admin/Loja) para uma instância de comunidade específica. |
| instance/packages/core | @elo-instance/core | Library | SSOT para instâncias de comunidade (API & Web App). |
| studio/ | @elo-organico/studio | Tooling | Tokens de marca, ativos de design e estilização global. |
| tools/ | @elo-organico/tools | Tooling | Infraestrutura MCP, scripts de automação e utilitários de projeto. |
| docs/ | @elo-organico/docs | Docs Hub | Hub oficial de documentação do projeto e landing page técnica. |
2.1. Filosofia de Contexto Delimitado (Bounded Context)
- Isolamento de Contexto: Cada diretório raiz (
instance/,portal/) representa um Bounded Context. Lógica e modelos são duplicados quando necessário para manter a independência, seguindo princípios de DDD. - Implantação (Deployment):
- Portal: Projetado como uma camada singleton para futuro onboarding SaaS. Atualmente em estágio de fundação/esqueleto.
- Hub de Documentação: O hub oficial do projeto para documentação (EloDocs) e especificações técnicas.
- Instância: Múltiplos pares de API/Web serão instanciados no futuro modelo SaaS, um para cada comunidade.
3. Estratégia de Build e Resolução de Workspace
Empregamos uma Arquitetura Híbrida de Alta Performance otimizada pelo Turborepo para gerenciar dependências internas e orquestração de tarefas.
3.1. Orquestração de Tarefas (Turborepo)
O Turborepo é o motor por trás da nossa produtividade no monorepo. Ele lida com:
- Grafo de Dependências: Identifica automaticamente quais pacotes precisam de build ou validação com base em alterações locais.
- Acoplamento de Infraestrutura: Orquestra serviços do Docker Compose como pré-requisitos para o desenvolvimento das aplicações (ex:
pnpm instance:upinicia bancos de dados antes da API). - Caching: Acelera builds, type-checking e lints ao ignorar módulos que não foram alterados.
- Outputs Unificados: Padroniza artefatos de build em
dist/(para apps e core) ebuild/(para Docusaurus).
4. Comandos Operacionais
Utilizamos uma interface unificada no package.json raiz para gerenciar todo o monorepo.
| Comando | Descrição | Orquestração |
|---|---|---|
pnpm instance:dev | Stack de Comunidade Completo (Infra + API + Web) | Turbo + Docker Compose |
pnpm instance:up | Apenas Infraestrutura de Comunidade (MongoDB + Redis) | Docker Compose |
pnpm instance:down | Para o Stack de Comunidade e limpa as portas | Docker Compose + Shell |
pnpm portal:dev | Stack de Plataforma Completo (Fundação) | Turbo + Docker Compose |
pnpm mcp:up | Inicia a infraestrutura de ferramentas de IA (MCP) | Docker Compose |
pnpm docs:dev | Inicia a Base de Conhecimento (Modo Desenvolvimento) | PNPM Filter |
pnpm typecheck | Valida o TypeScript em todo o monorepo | Turbo |
pnpm lint | Executa a lintagem para todos os workspaces | Turbo |
5. Princípios Arquiteturais
- Fonte Única de Verdade (SSOT): Estruturas de dados da comunidade devem ser definidas em
@elo-instance/core. Regras da plataforma estão em@elo-portal/core. - Configuração Herdada: ESLint e TSConfig são centralizados na raiz, com extensões localizadas fornecendo refinamentos específicos de contexto sem duplicar o rigor base.
- Domain-Driven Design (DDD): A lógica de negócio é organizada em domínios (
auth,cycle,product) para facilitar a modularidade.- Isolamento Estrito de Domínio: Importações entre contextos (ex: Portal importando da Instância) são estritamente proibidas via regras de ESLint para evitar vazamentos arquiteturais.
- Princípios SOLID:
- Responsabilidade Única: Cada módulo tem um propósito específico.
- Aberto/Fechado: Aberto para extensão, fechado para modificação.
- Substituição de Liskov: Comportamento consistente de subtipos.
- Segregação de Interface: Interfaces enxutas e específicas.
- Inversão de Dependência: Depender de abstrações, não de concreções.
6. Stack Tecnológica
6.1. Gestão de Pacotes & Orquestração
- Runtime: Node.js 22+ (LTS).
- Gerenciador de Pacotes: PNPM v11 (Gestão estrita de dependências via symlinks e armazenamento de conteúdo via hard-link).
- Gestão de Dependências: PNPM Catalogs (Controle de versão centralizado para dependências compartilhadas usando o protocolo
catalog:). - Orquestrador de Tarefas: Turborepo (Cache otimizado e execução paralela).
- Tooling: TypeScript 6, ESLint 9 (Flat Config), Prettier 3, Vite 8.
6.2. Backend (Camada de API)
- Framework: Fastify v5 (Otimizado para alto throughput).
- ORM/ODM: Mongoose com MongoDB (Replica Set ativado para transações ACID).
- Validação: Zod (Integrado via pacotes core específicos de domínio).
- Processamento: BullMQ + Redis para tarefas assíncronas.
6.3. Frontend (Camada de UI)
- Framework: React 19.
- Gestão de Estado: Zustand (Estado atômico e performático).
- Estilização: TailwindCSS v4 + CSS Modules para estilos escopados.
- Animações: GSAP (Feedback interativo de alta fidelidade).
7. Padrões Arquiteturais
7.1. Camadas de Responsabilidade (Backend)
Cada domínio segue uma hierarquia estrita para isolar preocupações: Controller -> Service -> Repository -> Model
- Controller: Gerencia I/O HTTP, definições de rota e validação de esquemas Zod.
- Service: Orquestra regras de negócio, lógica complexa e transações entre modelos.
- Repository: Abstrai a lógica de persistência de dados (Repository Pattern) para manter os serviços independentes do banco de dados.
- Model: Define a estrutura do banco de dados Mongoose e as regras de integridade de dados.
Exemplo de Implementação (Repository Pattern)
Para manter a tipagem estrita e o desacoplamento, os repositórios recebem o modelo Mongoose via injeção de dependência.
// instance/apps/api/src/domains/auth/auth.repository.ts
import type { Model } from 'mongoose';
import type { IUser } from '@elo-instance/core';
export class AuthRepository {
constructor(private readonly userModel: Model<IUser>) {}
async findByEmail(email: string): Promise<IUser | null> {
return this.userModel.findOne({ email }).exec();
}
async create(data: Partial<IUser>): Promise<IUser> {
return this.userModel.create(data);
}
}
7.2. Injeção de Dependência
Gestão modular através de decoradores do Fastify e um registro centralizado para desacoplar componentes e facilitar testes.
8. Infraestrutura & Implantação
Projetado para Excelência Self-Hosted na Hetzner Cloud.
7.1. Orquestração
- Docker Compose: Orquestra todo o stack (Apps, DB, Cache, servidores MCP).
- Nginx: Opera como Proxy Reverso e servidor de arquivos estáticos para builds de produção.
7.2. Rede & Latência
Todos os componentes residem em uma rede privada do Docker para latência sub-milissegundo entre APIs e Bancos de Dados.
9. Studio & Automação (Arquitetura)
Os workspaces de Studio e Tools fornecem a infraestrutura para o alinhamento entre design e código, pipelines de automação e engenharia assistida por IA.
- Alinhamento de Design e Ativos: Gerenciado no Workspace Studio.
- Ponte Contextual de IA e Automação: Gerenciado no Workspace Tools.
10. Padrões de Segurança
O Elo Orgânico segue uma estratégia de segurança em múltiplas camadas. Para detalhes detalhados de implementação, consulte o documento de Arquitetura de Segurança.
- Proteção contra Bots: Integração com Cloudflare Turnstile para todos os pontos de entrada de autenticação.
- Mitigação de Brute-Force: Limitação de taxa baseada em IP e lógica de bloqueio de conta.
- Tipagem Estrita: Modo Estrito do TypeScript ativado em todo o projeto.
- Integridade de Build: Aprovações automatizadas de scripts de build via
pnpm.onlyBuiltDependencies. - Integridade de Dados: MongoDB Replica Set (
rs0) para confiabilidade transacional e conformidade ACID. - Validação: Validação rigorosa com Zod em cada ponto de entrada (Requisições API, Variáveis de ambiente, contratos internos).
Última Atualização: Junho de 2026