162 lines
7.5 KiB
Markdown
162 lines
7.5 KiB
Markdown
# 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. |