Araru Documentation

The project’s technical and architectural source of truth. Code is the final authority; these documents describe the state verified in August 2026 and explicitly separate current implementation from future directions.

Brand identity and usage: Araru.

Getting started

• Overview
• Local development
• Environment variables
• Project structure

Current architecture

• System boundaries
• Data flows
• Storage
• Readers
• Jobs and caches
• Administration, users, and profiles
• Architectural decisions

Implementation

• Frontend: routing and state, library, reader and PWA
• Backend: configuration, PostgreSQL and Redis, catalog and metadata, operations and security
• API: endpoint inventory
• Readers: formats, performance and progress
• Infrastructure

Quality and operations

• Testing strategy
• Coverage matrix
• Runbook
• Troubleshooting
• Conventions
• Change guides
• Definition of Done

Evolution

• ADRs
• Current limitations
• Backend evolution
• Scalability
• Future clients

Context for agents

Code agents should start at docs/llm/README.md. This set summarizes architecture, domain, invariants, tests, and the change protocol without mixing the roadmap with implementation.

Architecture at a glance

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

Current state: independent repositories for the React Web client, Express/PostgreSQL Server, Redis cache, and documentation. The official Compose setup publishes the interface on 8080 and the API on 3001 by default.

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