Arquitetura do Ecossistema Ekonavi

Documentação técnica da arquitetura do ecossistema Ekonavi, incluindo microserviços, integrações blockchain e fluxos de dados.

Visão Geral da Arquitetura

Arquitetura de Microserviços

┌─────────────────────────────────────────────────────────────────┐
│                     Ekosis Ecosystem                            │
├─────────────────────────────────────────────────────────────────┤
│  Frontend Layer (React + TypeScript + Vite)                     │
├──────────────────────┬──────────────────────┬───────────────────┤
│  ekonavi.com         │  admin.ekonavi.com   │  ekonavi.com      │
│  Main Platform       │  Admin Interface     │  Public Dashboard │
├──────────────────────┴──────────────────────┴───────────────────┤
│  Backend Layer                                                  │
├──────────────────────┬──────────────────────┬───────────────────┤
│  api.ekonavi.com     │  docs.ekonavi.com    │  Shared Libraries │
│  Core API            │  Docusaurus Docs     │  lib/*            │
└──────────────────────┴──────────────────────┴───────────────────┘
│                    Infrastructure Layer                          │
├─────────────────────────────────────────────────────────────────┤
│  Database           │  Blockchain          │  Storage            │
│  PostgreSQL/Hasura  │  ERC1155 Contracts   │  IPFS/Pinata       │
│  GraphQL API        │  Multi-chain Support │  Cloudflare R2     │
└─────────────────────────────────────────────────────────────────┘

Tecnologias Principais

Frontend Stack

Tecnologia	Uso
React 18	Framework UI
TypeScript	Linguagem
Vite	Bundler
TailwindCSS + shadcn/ui	Estilização
Zustand + React Query	Gerenciamento de estado
React Router	Roteamento
React Hook Form + Zod	Formulários e validação

Backend Stack

Tecnologia	Uso
Cloudflare Workers	Runtime
TypeScript	Linguagem
Hono.js	Framework
PostgreSQL	Banco de dados
Hasura GraphQL Engine	Camada GraphQL
JWT + Wallet Signatures	Autenticação
Cloudflare R2 + IPFS	Armazenamento
Ethereum/Polygon (ERC1155)	Blockchain

Infrastructure Stack

Tecnologia	Uso
Cloudflare Pages + Workers	Deploy
Neon PostgreSQL (Serverless)	Banco de dados
Cloudflare R2 + Pinata IPFS	Armazenamento
Cloudflare DNS	DNS
GitHub Actions	CI/CD

Detalhamento dos Microserviços

1. ekonavi.com — Plataforma Principal

Interface principal para todos os usuários (Produtores, Verificadores, Avaliadores, Certificadores).

Rotas principais organizadas por papel:

Públicas: Landing page, login, registro
Autenticadas: Dashboard, perfil, carteira, notificações
Produtor: Projetos, relatórios, certificados
Verificador: Verificações, atribuições, ferramentas de campo
Avaliador: Avaliações, metodologias, analytics
Certificador: Certificações, templates, gestão de NFTs

2. admin.ekonavi.com - Interface Administrativa

Gestão administrativa do ecossistema, aprovação de papéis e monitoramento.

Funcionalidades:

Gestão de usuários e aprovação de papéis
Gestão de workflows e metodologias
Integração blockchain (minting de tokens)
Analytics e métricas da plataforma

3. data.ekonavi.com - Dashboard Público

Transparência pública através de métricas agregadas ESG sem PII.

Seções:

Estatísticas gerais e impacto ambiental
Status das redes blockchain e tokens
Distribuição geográfica e por bioma
Séries temporais de impacto

4. api.ekonavi.com - API Central

API REST centralizada para todas as operações do ecossistema.

Estrutura da API:

# Autenticação
/v1/auth/*: login, register, refresh, logout

# Gestão de usuários
/v1/users/*: profile, role-request, notifications

# Workflows por papel
/v1/producers/*: projects, reports, certificates
/v1/verifiers/*: assignments, verifications
/v1/valuators/*: valuations, methodologies
/v1/certifiers/*: certificates, templates

# Administração
/v1/admin/*: role-requests, users, system-config

# Blockchain (ABCI)
/abci/contracts/*: mint-role-token, mint-entity-token

# Dados públicos
/v1/public/*: counts, impact, blockchain stats

Fluxos de Dados

Fluxo de Autenticação

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant API as API
    participant DB as Database
    participant BC as Blockchain

    U->>F: Login (email/wallet)
    F->>API: POST /v1/auth/login
    API->>DB: Validate credentials
    DB->>API: User data + roles
    API->>BC: Verify wallet tokens (if wallet login)
    BC->>API: Token ownership confirmation
    API->>F: JWT + user data
    F->>U: Authenticated session

Fluxo de Criação de Projeto ESG

sequenceDiagram
    participant P as Producer
    participant F as ekonavi.com
    participant API as api.ekonavi.com
    participant DB as PostgreSQL
    participant IPFS as IPFS/Pinata

    P->>F: Create new project
    F->>API: POST /v1/producers/projects
    API->>DB: Save project data
    API->>IPFS: Store project documents
    IPFS->>API: Return IPFS hash
    API->>DB: Update project with IPFS hash
    DB->>API: Project created
    API->>F: Project data + ID
    F->>P: Project created successfully

Fluxo de Aprovação de Papel

sequenceDiagram
    participant U as User
    participant F as ekonavi.com
    participant A as admin.ekonavi.com
    participant API as api.ekonavi.com
    participant BC as Blockchain

    U->>F: Request role (Producer)
    F->>API: POST /v1/users/role-request
    API->>API: Store role request

    Note over A: Admin reviews request
    A->>API: PUT /v1/admin/role-requests/{id}/approve
    API->>BC: POST /abci/contracts/mint-role-token
    BC->>BC: Mint Producer token to user wallet
    API->>U: Notification: Role approved
    U->>F: Can now access Producer features

Segurança e Autenticação

Email/Password + 2FA - Login tradicional com autenticação de dois fatores
OAuth (Google) - Login social via Google
Web3 Wallet - Autenticação via MetaMask/WalletConnect com assinatura de mensagem

Role-Based Access Control (RBAC)

Hierarquia de papéis:

Admin: Todas as permissões
Certificador: Herda de Avaliador + certificações, NFTs
Avaliador: Herda de Verificador + avaliações, metodologias
Verificador: Herda de Produtor + verificações, coleta de dados
Produtor: Projetos, relatórios, certificados (leitura)

Ambientes de Deploy

Ambiente	Domínio	Database	Blockchain
Development	localhost	Local PostgreSQL	Hardhat local
Staging	staging.ekonavi.com	Neon PostgreSQL (branch)	Ethereum Sepolia
Production	ekonavi.com	Neon PostgreSQL (main)	Ethereum + Polygon

Visão Geral da Arquitetura​

Arquitetura de Microserviços​

Tecnologias Principais​

Frontend Stack​

Backend Stack​

Infrastructure Stack​

Detalhamento dos Microserviços​

1. ekonavi.com — Plataforma Principal​

2. admin.ekonavi.com - Interface Administrativa​

3. data.ekonavi.com - Dashboard Público​

4. api.ekonavi.com - API Central​

Fluxos de Dados​

Fluxo de Autenticação​

Fluxo de Criação de Projeto ESG​

Fluxo de Aprovação de Papel​

Segurança e Autenticação​

Autenticação Multi-Modal​

Role-Based Access Control (RBAC)​

Ambientes de Deploy​