# Build brief — a focused alternative to Letterboxd

> **Verdict:** Not faithfully · **Buildability:** 9/100 · **Category:** Social Media
> **Source:** https://www.canitbevibecoded.com/letterboxd
> Independent editorial assessment from Can It Be Vibe Coded? Not affiliated with, endorsed by, or derived from Letterboxd. Verify current pricing and capabilities before acting.

## Context

**Letterboxd** — A social diary for films: log what you watch, rate it, review it, and read everyone else's takes. It currently costs $1.58/mo.

The logging half of Letterboxd is trivial: a table of films, a date, a rating, a note. The half people actually open the app for is everyone else, friends' four-star shrugs, review pages with thousands of jokes, lists that function as film school syllabi, and the year-end stats that only mean something because they are comparable. A one-shot build gives you a private diary with no one in it, and you will still need TMDB to get posters and metadata that do not look broken. If you genuinely only want a watch log, build it and enjoy the speed. If you want the film internet, you are not building the film internet this weekend.

This brief describes a focused, single-operator replacement for the part of Letterboxd that is genuinely reproducible. It is deliberately narrower than the product it replaces, and it says so in writing. Build the useful core; do not pretend to have rebuilt the rest.

## What you are building

A local film diary that searches TMDB for a title, logs a watch date, rating and review, and shows your history plus a stats page.

- Draft, queue, and track content for the few networks you actually use.
- A responsive interface with real empty, loading, success, and error states.

## Requirements

### Functional

- Node 20+.
- SQLite (no server to run).

### Data and integrations

- TMDB API key for film metadata and posters.

Each of these needs a real account, credential, or quota. Set them up before writing feature code.

### Non-functional

- Accessibility: semantic markup, labelled controls, visible focus, and reduced-motion support.
- Security: server-side secrets, validated input, and no credentials in the client bundle.
- Reliability: retries with backoff on external calls, and a clear failure state when a provider is down.
- Portability: the operator can export their data and leave without losing it.

## Implementation brief

Build a local-first personal film diary web app. Single user, no accounts, no cloud, no telemetry.

Stack, non-negotiable:
- Next.js 15 with the App Router, TypeScript, Tailwind.
- SQLite via better-sqlite3, one file at ./data/diary.db, schema created on first run.
- No auth, no external services except TMDB for metadata.

Secrets:
- .env.local with TMDB_API_KEY. Commit .env.example only. Fail loudly with a readable message if the key is missing.

Data model:
- films: tmdb_id (primary key), title, year, director, runtime, poster_path, overview, cached_at.
- entries: id, tmdb_id, watched_on (date), rating (0.5 to 5 in half steps, nullable), review (text, nullable), rewatch (boolean), liked (boolean), created_at.
- watchlist: tmdb_id, added_at, note.

Features in scope:
- Search box that hits TMDB search, shows posters and years, one click to log. Cache the film row locally so the app works offline for anything already logged.
- Log form: watched date defaults to today, half-star rating widget, review textarea, rewatch and liked toggles.
- Diary view grouped by month, newest first, poster grid plus compact list toggle.
- Film detail page: local metadata, every entry you have for it, rating history.
- Watchlist page with add from search and a one-click promote to a diary entry.
- Stats page: films per year and per month, rating distribution histogram, top directors by count, total runtime in hours and days, longest streak of consecutive days with a log.
- CSV import that accepts the Letterboxd export format (Name, Year, Watched Date, Rating, Review, Rewatch) and matches to TMDB with a manual disambiguation queue for anything ambiguous.
- CSV export of everything.

Explicitly out of scope: any social features, follower graphs, comments, aggregate ratings, streaming availability, mobile apps, push notifications, deployment config.

Deliver: working app, README with setup in under five commands, seed script that inserts three sample entries so the stats page is not empty on first load.

## Delivery standard

- Inspect the repository first, then write a short implementation plan before writing code.
- Deliver the smallest complete end-to-end workflow first; every primary control must work against persisted data.
- Use real validation and storage; never substitute fake dashboards, decorative controls, hard-coded success states, or mock integrations.
- Include responsive layouts plus genuine empty, loading, success, validation, and failure states.
- Keep secrets server-side in environment variables, provide .env.example, and never commit credentials or user data.
- Add structured logs around every external call and return actionable errors without leaking sensitive details.
- Write unit tests for the core logic and one automated test of the main user journey.
- Finish with a README covering setup, architecture, data location, backups, tests, deployment, and known limitations.

## Acceptance criteria

- [ ] A clean install starts the app using only the README and .env.example.
- [ ] The primary journey works from first visit through saved result, reload, edit, export, and deletion where applicable.
- [ ] Invalid input, missing configuration, provider failure, and an empty database each have a usable state.
- [ ] The interface works at 390px and 1440px, is keyboard navigable, and shows visible focus on every control.
- [ ] Tests, type checking, linting, and a production build all pass with no ignored failures.
- [ ] No part of the interface implies a live integration, security guarantee, or scale capability that was not actually built and verified.

## Non-goals

Do not build these, and do not claim to have replaced them:

- Every other human: friends' ratings, popular reviews, comment threads.
- Curated and community lists, which are most of the discovery value.
- Aggregate ratings and the histogram that tells you if a film is divisive or just bad.
- Mobile apps, offline logging, share cards, streaming availability data.
- Importing your existing history back out of anything without a CSV wrangle.

## What you still own after launch

- Secure credentials, rotate secrets, and handle provider rate limits.
- Run migrations, backups, restores, and dependency updates.
- Test the critical journey after every model, API, or hosting change.
- Monitor failures and fix the edge cases a first prompt will miss.

## Risk

**Operational risk.** The code is achievable; dependable data, integrations, and ongoing operations are the real cost.

Editorial confidence in this assessment: medium. No reviewed project implementation is linked yet.

---

Generated by [Can It Be Vibe Coded?](https://www.canitbevibecoded.com) · Full report: https://www.canitbevibecoded.com/letterboxd