# Beacon

Beacon is a private, multi-workspace web application for small communities to discover films, series, anime and games through people they trust.

## Stack

Node.js 24 LTS, pnpm 10, Next.js 16 App Router, React 19, TypeScript strict, Tailwind CSS, Better Auth, PostgreSQL 17 and Drizzle ORM. The supported runtime is Node 22+.

## Local development

1. Copy `.env.example` to `.env` and set a unique `BETTER_AUTH_SECRET` of 32+ characters.
2. Start PostgreSQL: `podman compose -f docker-compose.dev.yml up postgres -d`.
3. `pnpm install`
4. `pnpm db:migrate && pnpm db:seed`
5. `pnpm dev`

Open `http://localhost:3000`. Development accounts are `patch@beacon.local`, `rook@beacon.local` and `nova@beacon.local`; their passwords are respectively `BeaconDev!Patch2026`, `BeaconDev!Rook2026` and `BeaconDev!Nova2026`. They are strictly local development credentials.

## Commands

`pnpm lint`, `pnpm typecheck`, `pnpm test`, `pnpm build`, `pnpm test:e2e`, `pnpm db:generate`, `pnpm db:migrate`, `pnpm db:seed`, and `pnpm podman:dev` are the primary commands. `GET /api/health` reports application and database readiness.

## Docker and deployment

`podman compose -f docker-compose.dev.yml up --build` runs the app and PostgreSQL. The image uses the standard Dockerfile format, Next standalone output and a non-root user; startup waits for PostgreSQL and applies versioned migrations, never seeds. It is suitable as a single web service plus PostgreSQL in Coolify.

## Architecture

The application is a modular monolith. Pages and route handlers coordinate application code; repositories own Drizzle access; server guards validate session, membership and roles. Routes explicitly include their active workspace (`/w/el-yermo`). See [architecture.md](docs/architecture.md), [domain-model.md](docs/domain-model.md), and the initial [ADR](docs/decisions/0001-initial-architecture.md).

## Immediate roadmap

The next iteration will add TMDB movie and series search with normalized persistence, caching and recommendation creation. AniList and IGDB are currently contracts only; no external provider calls exist.