BokehTV — Backend (Express.js API)

The BokehTV backend is a TypeScript-driven, high-performance REST API designed to manage user authentication, watchlist activity, and media discovery via the TMDB API. It follows a layered service architecture (ADR-001) for maintainability and scalability.

---

🛠 Core Stack

• Framework: Express.js
• Language: TypeScript (strict mode)
• Database: PostgreSQL via Prisma ORM
• Cache: Redis (Upstash)
• Validation: Zod (ADR-007)
• Logging: Structured JSON with Winston (ADR-010)
• Metrics: Prometheus & Grafana (ADR-012)
• Auth: JWT (15min Access / 7d Refresh in HttpOnly Cookies)

---

🏗 Subdirectory Structure

• src/auth/ — Authentication controllers and service logic.
• src/content/ — Media search and TMDB proxy logic.
• src/watchlist/ — User-specific collection management.
• src/common/ — Shared middleware, Zod schemas, and structured response envelopes.
• prisma/ — Shared database schema and safe migrations.

---

🚀 Development Setup

1. Environment Configuration

Copy the template and fill in your details:

cp .env.example .env

Ensure you have a valid TMDB_READ_ACCESS_TOKEN and DATABASE_URL.

2. Database & Cache

Ensure your local PostgreSQL and Redis servers (via Docker) are running:

docker-compose up -d postgres redis

3. Install & Start

npm install
npx prisma migrate dev
npm run dev

The API will start at http://localhost:5000/api/v1.

---

📊 API Contract (V1)

All responses follow the locked response envelope (ADR-008):

{
  "success": true,
  "data": { ... },
  "meta": null,
  "error": null
}

• POST /auth/login — Sign in and get refresh token cookies.
• GET /content/trending — Discovery endpoint proxy.
• GET /watchlist — Fetch the authenticated user's collection.

---

🏗 Deployment

Deployed automatically to Railway via Dockerfile upon merge to main. Monitoring stack available via Prometheus and Grafana for live production metrics tracking.