Documentação do Araru

Fonte de verdade técnica e arquitetural do projeto. O código é a autoridade final; estes documentos descrevem o estado verificado em agosto de 2026 e separam explicitamente implementação atual de direções futuras.

Identidade e uso da marca: Araru.

Começar

• Visão geral
• Desenvolvimento local
• Variáveis de ambiente
• Estrutura do projeto

Arquitetura atual

• Sistema e boundaries
• Fluxos de dados
• Storage
• Readers
• Jobs e caches
• Administração, usuários e perfis
• Decisões arquiteturais

Implementação

• Frontend: rotas e estado, biblioteca, reader e PWA
• Backend: configuração, PostgreSQL e Redis, catálogo e metadados, operação e segurança
• API: inventário de endpoints
• Readers: formatos, performance e progresso
• Infraestrutura

Qualidade e operação

• Estratégia de testes
• Matriz de cobertura
• Runbook
• Troubleshooting
• Convenções
• Guias de mudança
• Definition of Done

Evolução

• ADRs
• Limitações atuais
• Evolução do backend
• Escalabilidade
• Clientes futuros

Contexto para agentes

Agentes de código devem começar em docs/llm/README.md. Esse conjunto resume arquitetura, domínio, invariantes, testes e protocolo de alteração sem misturar roadmap com implementação.

Arquitetura resumida

flowchart LR
  U[Browser/PWA] -->|HTTP| F[React + Nginx/Vite]
  F -->|/api e /arquivos| B[Node.js + Express]
  B --> DB[(PostgreSQL)]
  B --> R[(Redis)]
  B --> FS[Filesystem local]
  B --> CC[Cache de capas]
  B -. opcional .-> GD[Google Drive]
  B -. enriquecimento .-> MP[Google Books / Open Library]

Estado atual: repositórios independentes para Web React, Server Express/PostgreSQL, Redis para cache e documentação. O Compose oficial publica a interface em 8080 e a API em 3001 por padrão.

npm install
npm run dev
# ou
docker compose up -d --build --wait