# Beacon agent guide

## Purpose and stack

Beacon helps small communities discover media through trusted recommendations. It is a Next.js 16 / React 19 / TypeScript strict modular monolith using PostgreSQL, Drizzle, Better Auth, Tailwind and Vitest.

## Architecture rules

Use Server Components by default. Never access Drizzle from React components, pages, route handlers or Server Actions: use a feature repository/application module. Keep domain names neutral (`Recommendation`, never a branding service). Validate session, membership, role and resource workspace on the server. Encapsulate external providers; do not expose secrets or raw provider payloads.

Do not add dependencies without justification, `any`, ignored TypeScript errors, microservices, Redis, direct schema push in production, edited applied migrations, unnecessary client components, real test data, dead files, or removed tests to pass CI. Update an ADR when changing architecture.

## Conventions

Use kebab-case filenames, PascalCase components, `@/` imports and public `index.ts` only for deliberate module boundaries. Zod validates server input and environment. Throw typed application errors, log structured context without secrets, and test behavior rather than implementation. Use conventional commits.

## Workflow

Before work, read this guide and `docs/`, inspect the target module and its invariants, then make the smallest coherent change. After work run `pnpm format`, `pnpm lint`, `pnpm typecheck`, `pnpm test`, and `pnpm build` when relevant; use Podman for local containers; report files, verification and risks.

## Scope boundaries

Do not add real metadata integrations, recommendation algorithms, AI, mobile apps, push notifications, gamification, episode tracking, bulk imports, social login, WebSockets or job queues yet.