Architecture Overview
Vidra follows clean architecture principles with a strict boundary between domain logic, business rules, and infrastructure adapters. This page gives you a mental model of how the pieces fit together — from the edge layer down to storage and workers.
High-Level Architecture
The diagram below shows every major subsystem and how requests flow from external clients through the API layer to data, storage, workers, and federation. Focus on the Vidra API Server block at the center — all business logic lives there.
Request Flow
Every HTTP request passes through Nginx, then the Chi router, then a middleware stack (authentication, rate limiting, CORS), and finally a handler that calls a use case. The cache-hit path (Redis → return) bypasses PostgreSQL entirely; the cache-miss path queries the database and back-fills the cache.
Clean Architecture Layers
Dependency arrows always point inward — External adapters depend on Application interfaces; Application depends on Core models. The Core layer has zero external dependencies. The table below maps each layer to its directory in the repository.
Layer Responsibilities
| Layer | Directory | Responsibility |
|---|---|---|
| Domain | internal/domain/ | Core models, error types, no external dependencies |
| Ports | internal/port/ | Interface definitions (repository contracts) |
| Use Cases | internal/usecase/ | Business logic, orchestrates domain + ports |
| Handlers | internal/httpapi/ | HTTP request/response, input validation |
| Repositories | internal/repository/ | PostgreSQL data access via SQLX |
| Workers | internal/worker/ | Background jobs (transcoding, cleanup) |