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, domain-model.md, and the initial ADR.

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.