A TV series tracking app

• Episode tracking with progress indicators per season
• Lists for favorites, watchlist, in progress, and watched
• Discover with filters for genre, country, language, and streaming services
• Plex scrobbling via webhooks for automatic tracking
• CSV import for migrating watch history
• User profiles with follow/following
• Yearly stats with charts, world map, and viewing streaks
• Where to watch showing streaming availability in your region

• Node.js 22+
• pnpm 10+
• AWS account with configured profiles

1. Install dependencies:

pnpm install

2. Configure environment variables for AWS hosted zone IDs and SST secrets.

3. Start the development server:

pnpm sst dev

• TMDB – TV series metadata
• mdblist – IMDb ratings and curated lists

• Next.js 16 (App Router, Server Components) – React 19 frontend
• OpenNext – Deploy Next.js to AWS Lambda + CloudFront
• Hono – API on AWS Lambda
• OpenAuth – Authentication (Google, Email OTP)
• DynamoDB – Database with Streams for real-time list updates
• SST v3 – Infrastructure on AWS
• Turborepo – Monorepo orchestration
• XState – State machines for session management
• Zustand – Client state
• Tailwind CSS – Styling
• Valibot – Schema validation
• Biome – Formatting and linting

• Single auth() function for Next.js extending OpenAuth's client — overloaded for RSC, Route Handlers, and Middleware with a cookie jar abstraction to handle the RSC cookie limitation, paired with XState for client-side token refresh
• DynamoDB Streams trigger Lambdas to auto-update lists when episodes are marked watched and follower/following counts when users follow/unfollow
• Cost protection via AWS Budget alerts + CloudWatch metrics that auto-disable CloudFront
• Dominant color extraction from images with WCAG contrast correction
• Edge functions for blocking malicious requests at CloudFront

├── apps/
│   ├── web/                  # Next.js frontend
│   ├── api/                  # Hono API (Lambda)
│   └── auth/                 # OpenAuth service
├── packages/
│   ├── constants/            # Shared constants
│   ├── schemas/              # Valibot schemas & types
│   ├── utils/                # Shared utilities
│   └── kill-switch/          # Cost protection handlers
└── infra/
    ├── api.ts                # API Gateway + Lambda
    ├── auth.ts               # Auth service
    ├── web.ts                # Next.js via OpenNext
    ├── dns.ts                # Route 53 config
    ├── email.ts              # SES email
    ├── waf.ts                # WAF rules
    ├── secrets.ts            # SST Secrets
    ├── scrobbleQueue.ts      # SQS + Lambda for Plex
    ├── watchedStatus.ts      # Daily cron for list updates
    ├── dominantColor.ts      # Image color extraction
    ├── distributionDisabler.ts   # Cost protection
    └── dynamo/
        ├── cache.ts          # Cache table (TTL)
        ├── follow.ts         # Follow relationships + stream subscriber
        ├── lists.ts          # User lists
        ├── users.ts          # User accounts
        ├── watched.ts        # Watched episodes + stream subscriber
        ├── preferredImages.ts    # Admin image overrides
        └── webhookTokens.ts  # Plex webhook tokens

• pnpm sst dev – Start dev server
• pnpm format-and-lint – Check formatting and lint
• pnpm format-and-lint:fix – Fix issues
• pnpm check-types – TypeScript checks

Deployed via GitHub Actions:

• Push to main → Production (tvseri.es)
• PR to main → Preview (pr-{n}.dev.tvseri.es)