FliX

A personal journal for everything watched and played.

FliX tracks films, TV shows, and games with ratings, reviews, dates, and locally stored artwork/review images.

Stack

• Astro (SSR mode)
• TypeScript
• Tailwind CSS
• Node.js (runtime)
• Bun (package manager)
• SQLite (better-sqlite3)

Can Astro handle the backend?

Yes. This project uses Astro server routes/endpoints for backend logic:

• src/pages/api/items.ts
  • Accepts form data.
  • Fetches metadata from IMDb/Steam/GOG/Wiki links.
  • Downloads artwork to local storage.
  • Stores item + dates + review + images in SQLite.
• src/pages/media/[...path].ts
  • Serves locally stored images from disk.

Because Astro is running in SSR server mode (output: "server"), it can do file I/O, DB access, and external fetch calls.

Metadata and image ingestion

When you add an item with a source URL, FliX tries to fetch metadata from that page (best effort).

Source detection (source_kind) currently recognizes:

• IMDb (imdb.com) -> imdb
• Steam (steampowered.com) -> steam
• GOG (gog.com) -> gog
• Wikipedia/Fandom (wikipedia.org, fandom.com) -> wiki
• Anything else -> other

Ingestion flow:

• Fetch the source URL HTML.
• Extract title from og:title, then twitter:title, then meta[name="title"], then <title>.
• Extract description from og:description or meta[name="description"].
• Extract artwork URL from og:image or twitter:image.
• Download inferred artwork locally if available.
• If metadata/artwork fetch fails, manual title and manual artwork upload still work.

Features

• Add and display films, TV shows, and games.
• Track TV as one show entry with child seasons.
• Import metadata/artwork from source pages (best effort).
• Store artwork and review images locally.
• Track one or multiple watched/played dates.
• 1 to 5 star rating + freeform review text.
• Optional platform per entry (especially for games).
• Home page with featured/recent entries.
• Type-specific pages (/films, /tv, /games).
• Item detail page with review + gallery.
• Timeline grouped by year and type.
• Search across title/review/platform/source URL.
• Dark-themed UI with runtime theme switcher:
  • Red (default)
  • Blue
  • Purple
  • Amber

Getting Started

1. Install dependencies:

bun install

2. Create env file:

cp .env.example .env

3. Start dev server:

bun run dev

4. Optional Makefile shortcuts:

make dev   # docker compose --profile dev up --build --watch
make prod  # docker compose --profile prod up --build -d
make down  # docker compose down
make logs  # docker compose logs -f

Docker

Production container

docker compose --profile prod up --build -d

App URL: http://localhost:4321

To change the host port, set FLIX_PROD_HOST_PORT in your .env before starting Compose.

Dev container with Compose watch

Start the dev service with live sync/rebuild:

docker compose --profile dev up --build --watch

Compose watch behavior in this repo:

• Syncs source/config changes into the running container (src, astro.config.mjs, tsconfig.json).
• Rebuilds the image when dependencies change (package.json, bun.lock).

The SQLite DB and media files are persisted via bind mount ./storage:/app/storage.

To change the host port for dev, set FLIX_DEV_HOST_PORT in your .env.

Environment Variables

• FLIX_DB_PATH
  • SQLite file path.
  • Default: ./storage/flix.db
• FLIX_STORAGE_DIR
  • Root directory for downloaded artwork and uploaded review images.
  • Default: ./storage
• FLIX_RECENT_LIMIT
  • Number of recent items shown on home page.
  • Default: 12
• FLIX_PROD_HOST_PORT
  • Host port mapped to container port 4321 for the prod profile.
  • Default: 4321
• FLIX_DEV_HOST_PORT
  • Host port mapped to container port 4321 for the dev profile.
  • Default: 4321
• FLIX_CHECK_ORIGIN
  • Enables Astro's CSRF origin check for form/API POST requests.
  • Default: true
  • Set to false only when running behind a reverse proxy that does not forward host/proto correctly.
• FLIX_ALLOWED_DOMAINS
  • Comma-separated trusted hostnames/domains for proxy setups when FLIX_CHECK_ORIGIN=true.
  • Supports domain.tld (assumes https) or full URLs like https://domain.tld:443.
  • Example: FLIX_ALLOWED_DOMAINS=flix.balas.io

Notes

• Metadata and artwork fetching depends on remote page structure and access rules.
• Source ingestion is best-effort; manual title/artwork upload is supported as fallback.