PopChoice Documentation
The project control center for PopChoice architecture, operations, roadmap, and evaluation work.
PopChoice is a movie recommendation app built around Next.js, OpenAI embeddings, PostgreSQL with pgvector, Redis-backed BullMQ workers, and TMDB metadata. This documentation site is the Git-backed source of truth for how the project is built, operated, and evolved.
Start Here
- Development covers the local development loop.
- Architecture Boundaries explains where code should live.
- Services describes the background services and catalog jobs.
- API Reference describes app route families, auth expectations, and operational endpoints.
- Product Behavior Specs captures current quiz, recommendation, catalog, and memory behavior.
- Architecture Roadmap tracks the system roadmap.
- Recommendation Roadmap tracks recommendation and AI product work.
Operations
- Setup, Environment Reference, Schema And Migrations, and Coolify cover local and deployment setup.
- CI/CD explains checks, release automation, and deployment flow.
- Observability Metrics, Alerts, Logs, Traces, Uptime, and Runbooks cover production health.
Product And Quality
- Maintainability Checklist is the engineering quality bar for future changes.
- Documentation Governance explains where docs live, how to add pages, and when to create issues.
- Design Guidelines and Storybook Theming document the UI system.
When adding new long-lived project knowledge, prefer adding or updating a page in this docs tree and linking any related GitHub issues from there.