Beacon/docs/architecture.md

Architecture

Beacon is a single Next.js deployment connected to PostgreSQL. Presentation (src/app, src/components) calls server application modules; repositories in src/features/*/repositories are the only path to Drizzle. Domain language remains Recommendation, Workspace and MediaItem; “Beacon” is presentation branding.

Browser → App Router → server guard/use case → repository → Drizzle → PostgreSQL
                         ↘ metadata provider contract (future)

Server Components are the default. Client Components are limited to theme selection, mobile active navigation and the login form. Better Auth owns credential hashing and session cookies. requireUser, requireWorkspaceMember and requireWorkspaceRole validate authorization on the server; middleware is only an early redirect optimization.

Errors use typed application errors and route handlers map them to safe HTTP responses. Pino redacts secrets. Environment is parsed by Zod at startup. Tests use Vitest for unit contracts; integration tests are reserved for a PostgreSQL test database and Playwright covers browser routing. UI strings are presently English and concentrated in components/configuration; a dedicated i18n library is intentionally deferred.

External metadata adapters normalize results to MediaSearchResult and MediaDetails; raw provider responses never cross the application boundary. The cache table is ready for future use.