# ReelSpace implementation plan

## Product boundary

Version 0.1 is a read-only storage intelligence service for Unraid 7.2+. It indexes
only explicitly configured container paths, stores state in `/config`, and exposes a
single FastAPI/React application on port 8080. It never deletes, moves, renames,
transcodes, or modifies indexed files.

## Architecture

- **API and application services:** FastAPI with typed Pydantic request/response
  models and SQLAlchemy 2.
- **Persistence:** SQLite in WAL mode, managed by Alembic. Large file tables use
  indexed integer byte counts and batched writes.
- **Scanner:** one cancellable background job per root. Traversal is streaming,
  symlinks are not followed, errors are isolated, and aggregates are materialized
  after each completed scan.
- **Media:** bounded `ffprobe` subprocesses, cached by size and modification time.
- **Duplicates:** size grouping, partial SHA-256, optional full SHA-256. Inode/device
  groups are classified as hardlinks and excluded from reclaimable estimates.
- **History:** compact root/category/extension snapshots plus per-scan change events,
  rather than a full copy of every indexed file.
- **Integrations:** Plex and notifications are adapters behind narrow service
  interfaces. Filesystem scanning has no dependency on either.
- **Web UI:** React, TypeScript, Vite, responsive CSS, Recharts, and browser-native
  accessible controls.
- **Deployment:** one non-root multi-stage container, persistent `/config`, bundled
  frontend, `ffprobe`, healthcheck, and safe read-only sample mounts.

## Core data model

- `scan_roots`: alias, container path, category, scan and analysis policy.
- `scan_runs`: lifecycle, progress, mode, errors, timing, and byte/file counts.
- `file_records`: current file index, apparent/allocated sizes, identity, hashes,
  media cache, and first/last-seen scan.
- `directory_records`: cached direct and recursive aggregates.
- `change_events`: additions, removals, and modifications for completed scans.
- `snapshots`: aggregate history dimensions and values.
- `duplicate_ignores`: application-only ignored duplicate fingerprints.
- `settings`: validated application, Plex, notification, security, and appearance
  values; secrets are encrypted at rest when an installation key is available.
- `users` and `sessions`: optional local authentication with expiring sessions.

## Milestones

1. Repository, schema, migrations, health API, and settings.
2. Streaming scanner, aggregates, changes, media probing, duplicates, and tests.
3. Dashboard, explorer, reports, scan controls, integrations, and exports.
4. Responsive frontend with all required primary screens.
5. Docker image, Unraid template, icon, CI/release workflows, and documentation.
6. Migration/test/build/container smoke validation and release checklist.

## Technical risks and mitigations

- **Million-file libraries:** stream traversal, batch transactions, indexed queries,
  cached aggregates, pagination, and conservative worker defaults.
- **Double counting:** overlap validation plus physical-byte estimates based on
  `(device_id, inode)` identity.
- **Unstable network mounts:** isolate stat/probe failures, persist scan errors, and
  do not purge stale records unless a scan completes successfully.
- **SQLite contention:** WAL, busy timeout, short transactions, and one writer per
  scan root.
- **Filesystem permissions:** read-only operation, configurable PUID/PGID, actionable
  warnings, and no fatal failure for individual paths.
- **Media probe cost:** file-attribute cache, timeout, file-size ceiling, and bounded
  concurrency.
- **Unraid host variability:** optional read-only mounts behind adapters; manual
  usable-capacity configuration remains authoritative.
- **Secrets:** response redaction, structured-log filtering, no tokens in URLs or
  notifications, and restrictive `/config` permissions.

## Real-Unraid validation gates

Before Community Applications submission, validate UID/GID access, FUSE share inode
behavior, very large shares, template installation, anonymous GHCR pulls, upgrades,
and optional host-metric mounts on a clean Unraid 7.2.x system.