Project Structure

Project Structure

status-portal/
  CLAUDE.md                # notes for future AI coding sessions on this repo
  docs/HISTORY.md          # archived post-mortems + what's been verified on real hardware
  VERSION                  # the single source of truth for the running version
  app.py                  # Flask routes (public + admin)
  scheduler.py            # generic recurring-task framework (registry + runner)
  jellyfin_auth.py        # Jellyfin as an identity source: user sync + sign-in
  templates/account.html  # a signed-in visitor's own page (their reports + settings)
  serve_waitress.py       # run this in production (instead of app.py)
  update.py                # standalone updater CLI - works without the web UI
  updater.py               # the shared update logic (used by update.py AND the admin button)
  config.py               # all configuration, read from env vars / .env
  db.py                    # the entire SQLite layer
  monitoring.py            # CPU/RAM/disk/GPU/VM snapshot + host/VM power controls
  integrations.py          # read-only Jellyfin/*Arr/Jellyseerr/Bazarr/Tdarr/Byparr/qBittorrent/Games Portal status checks
  notifications.py         # optional Discord/ntfy/email push notifications (admin alerts)
  user_notify.py           # per-user notifications + the external notification API's delivery
  discord_bot.py           # optional Discord bot (presence, self-editing status message, /snapshot)
  twofactor.py             # optional TOTP two-factor authentication
  logging_setup.py         # crash/error logging to instance/logs/app.log
  requirements.txt, requirements-dev.txt
  Dockerfile, docker-compose.yml, .dockerignore, .env.example
  instance/portal.db      # created automatically on first launch
  instance/secret_key     # created automatically if PORTAL_SECRET_KEY isn't set
  instance/logs/app.log   # created automatically once the app is actually run
  templates/               # HTML pages (Jinja2)
  templates/sections/      # the public page's reorderable content blocks, one file each
  static/css/style.css     # all of the styling (dark + light theme)
  static/js/               # public page auto-refresh, local-time conversion, admin link-row editor, theme toggle, CSRF token injection, "load more" pagination
  static/uploads/          # the uploaded custom logo, if any - created automatically, not tracked in git
  tests/                   # pytest suite (see Testing)