# Ares Next — Design Document

**Data:** 2026-08-05
**Status:** Aprovado (brainstorming)

---

## 1. Objetivo

Aplicativo desktop multiplataforma (Windows, Linux, macOS) moderno para **compartilhamento e download de arquivos autorizados** (próprios, software livre, domínio público ou licenciado). Inspirado em clientes P2P clássicos (Ares), com arquitetura atual, segurança em primeiro plano e base para evolução comercial.

O **backend roda na VPS** Hokma (`13.140.174.24`), **isolado** dos demais projetos, sob o domínio **ares.hokmatech.com**.

---

## 2. Decisões de arquitetura (validadas)

| Decisão | Escolha | Motivo |
|---|---|---|
| Modelo de rede | **Híbrido** | Transferência P2P direta + índice / tracker central no VPS |
| Protocolo P2P | **libp2p (Rust)** | NAT traversal, relay, cripto e robustez mantidas pela comunidade |
| Framework desktop | **Tauri 2** | Binário leve, core em Rust, seguro, multiplataforma |
| Frontend | **React + TypeScript + Tailwind** | Ecossistema maduro, temas claro/escuro, acessibilidade |
| Backend | **Rust + axum** | Mesma linguagem do core, alto throughput, controle de rede |
| Banco de dados | **SQLite (FTS5)** | Zero-config, embarcado no backend e no desktop |
| Identidade | **Ed25519 por dispositivo** | Sem contas; peer ID = hash da chave; assinatura de metadados |
| Integridade | **BLAKE3 por chunk + arquivo inteiro** | Rápido e verificável incrementalmente |
| Deploy | **Coolify (projeto isolado) + Cloudflare** | Sem misturar com hokma-api, n8n, evolution |
| Domínio | **ares.hokmatech.com** | Registro A → `13.140.174.24` + Proxy Host no Coolify |

---

## 3. Visão geral da arquitetura

```
┌───────────────────────────────┐
│   Desktop App (Tauri 2)        │
│   React + TS + Tailwind (UI)   │
│   ┌─────────────────────────┐  │
│   │ Rust core (libp2p)       │  │
│   │ downloads/uploads/player │  │
│   │ SQLite local             │  │
│   └───────────▲─────────────┘  │
└──────┬────────┼──────────────┬─┘
   b   │        │              │
   e   │  HTTPS │              │ libp2p (direto)
   m   │        │              │
┌──────▼──────┐ │r      ┌──────▼──────┐
│  Backend    │ │       │  Outros     │
│  axum+VPS   │ │       │  pares      │
│  SQLite/FTS │ │       │ (desktop)   │
└─────────────┘ └───────┴─────────────┘
```

- **Busca, metadados, tracker e coordenação** ficam no servidor.
- **Bytes dos arquivos** trafegam par-a-par via libp2p (sessão cifrada).
- **NAT impossível** → relay libp2p no servidor como último recurso (bytes cifrados).

---

## 4. Estrutura de pastas (monorepo)

```
ares-next/
├── server/                  # Backend na VPS (Rust + axum + SQLite)
│   ├── src/
│   │   ├── main.rs           # bootstrap + config + rotas
│   │   ├── config.rs         # env/lepo, domínio, limites
│   │   ├── api/             # handlers REST (health, search, announce, peers, stats)
│   │   ├── ws/              # tracker WebSocket em tempo real
│   │   ├── store/           # SQLite + FTS5 + migrações
│   │   ├── search/          # buscador com filtros e ordenação
│   │   ├── validate/        # validação de metadados (coerência, tipo, licença)
│   │   ├── rate/            # rate limit por peer
│   │   └── relay/           # relay libp2p (último recurso NAT)
│   ├── migrations/          # SQL versionadas
│   └── Dockerfile            # multi-stage build
├── app/                     # Desktop App (Tauri 2 + React + TS + Tailwind)
│   ├── src-tauri/           # core Rust (commands, identity, network, etc)
│   └── src/                 # UI React
├── crates/                  # libs compartilhadas do workspace
│   ├── identity/            # Ed25519 → peer ID
│   ├── integrity/           # BLAKE3, verificação de chunks
│   ├── metadata/            # tipos, assinatura de anúncios
│   └── protocol/            # encoding de chunks, verificação
├── docs/
│   └── superpowers/specs/     # specs de design
└── README.md
```

Na VPS: projeto Coolify dedicado `ares-next` → container único → domínio `ares.hokmatech.com`, dados em `/opt/ares-next/data` (Volumes/backup independentes).

---

## 5. Contrato da API (Fase 1 — aprovado)

Base: `/api/v1`

| Método/rota | Descrição |
|---|---|
| `GET /health` | status + versão |
| `GET /search?q=&type=&cat=&limit=&offset=&sort=` | busca FTS5 com filtros/ordenação |
| `GET /files/{file_id}` | metadados + assinatura |
| `POST /announce` | publicar metadados assinados (Ed25519) |
| `GET /peers/{file_id}` | pares com o arquivo + endereços |
| `WS /tracker/ws?peer_id=&file_id=` | tempo real: status, slots, peers |
| `GET /stats` | agregados (nº de arquivos, hosts, bytes) |

Validação no servidor: coerência de hash/tamanho, type-sniffing (extensão + magic bytes), política de extensões proibidas, licença declarada, rate limit por peer.

---

## 5. Segurança (transversal)

- **Cifração:** Noise (libp2p) para transferência; TLS no transporte backend.
- **Integridade:** checks BLAKE3 por chunk e arquivo, verificação a cada download.
- **Assinaturas:** metadados assinados com a chave Ed25519 do publicador.
- **Arquivos executáveis:** quarentena com aviso + confirmação explícita.
- **Corrupção:** re-download de chunk inválido; hashes conferidos.
- **Entradas:** validação robusta, limites de tamanho, rate limiting.
- **Logs:** estruturados e separados (request/app/security) com rotação.

---

## 6. Qualidade

- **SOLID / Clean Architecture / Clean Code / DRY / KISS.**
- **Testes:** unitários por módulo + integração da API.
- **Revisão de código** por fase (agent de revisão).
- **Entregas curtas,** codare commitadas por fase.

---

## 7. Riscos e mitigação

| Risco | Mitigação |
|---|---|
| Servidor como ponto único de busca | Fallback opcional via DHT/gossipsub na fase 2+ |
| Conteúdo abusivo | Validação de metadados, licença declarada, moderação |
| NAT/firewalls difíceis | relay libp2p limitado por rate; múltiplos transports |
| Complexidade do libp2p | isolamento em crate dedicada + testes de integração |

---

## 8. Roteiro de fases

1. **Fase 0 — Fundação:** monorepo, workspace cargo, crates identity/metadata, CI básico.
2. **Fase 1 — Backend na VPS:** axum + SQLite/FTS5 + search + announce + tracker/WS + deploy isolado Coolify.
3. **Fase 2 — Núcleo P2P:** `network` crate, transação por chunks, NAT, relay.
4. **Fase 3 — Downloads/Uploads:** gerenciador com banda, prioridade, pausa/retoma.
5. **Fase 4 — Interface:** busca, biblioteca, player, configurações, aparência.
6. **Fase 5 — Security & Qualidade:** revisão final, testes E2E, docs.

---

## 9. Escopo imediato (Fase 0 + 1)

1. Fundamentar o monorepo git (Commit inicial da spec).
2. Scaffold do `server/` cargo (axum + rsqlite FTS5) compilando.
3. Endpoints health/search/announce/peers/stats + WS tracker.
4. Deploy isolado no Coolify (projeto `ares-next`, domínio ares.hokmatech.com, TLS automático).
5. DNS Cloudflare (registro A) + validação em produção.