{
  "markdown": "# MovieCollectionManager (MCM)\n\n> Browse and manage your movie collections from the web or your phone — with an AI assistant that can add, organize, import, and export movies for you.\n\nMCM is a multi-user, full-stack application for cataloging physical and digital movie collections. Each user owns one or more collections and can record media formats, movie metadata, and links to IMDB/TMDB; search and filter their library; and maintain a wishlist of titles to buy or upgrade. A built-in conversational assistant (LangGraph multi-agent) handles natural-language tasks like adding movies, retrieving TMDB metadata, and spreadsheet import/export.\n\nThe repository is also a working example of **spec-driven, AI-assisted development**: every feature flows through GitHub Spec Kit artifacts (spec → plan → tasks) governed by a repository [constitution](.specify/memory/constitution.md), with mandatory TDD and a fully self-hosted CI/CD pipeline.\n\n## Features\n\n- **Collections & movies** — create and manage multiple collections per user; add movies with media formats, metadata, and external database links; case-insensitive duplicate protection\n- **Search & filter** — full-text movie search, filterable browsing, cursor-paginated lists, per-user column visibility\n- **Wishlist** — track movies you want to add or upgrade\n- **AI assistant** — chat-driven add/organize/query/navigate, TMDB metadata retrieval, spreadsheet import/export, per-user model configuration (bring-your-own-Ollama or Claude)\n- **Multi-user security** — Keycloak OAuth 2.0 + PKCE via a BFF (clients never see tokens), RBAC, collection-level ACLs, audit logging\n- **Universal client** — one React Native/Expo codebase for web and Android\n\n## Architecture\n\n```mermaid\ngraph LR\n    C[React Native / Expo app<br/>web + Android] -->|HttpOnly session cookie| B[BFF<br/>Expo Router API routes / Node]\n    B --> K[Keycloak<br/>OAuth2 + PKCE, RBAC]\n    B --> R[(Redis<br/>sessions)]\n    B --> S[mc-service<br/>Rust / Axum, Clean Architecture]\n    B --> G[Agent Gateway<br/>LangGraph + AG-UI]\n    S --> M[(MongoDB)]\n    K --> P[(PostgreSQL)]\n    G --> MCP[MCP servers<br/>movie / web-api / spreadsheet]\n    MCP --> S\n    MCP --> T[TMDB]\n```\n\n- **BFF pattern** — the client authenticates only with an opaque, `HttpOnly SameSite=Strict` session cookie; the BFF holds and refreshes all tokens and proxies every backend call.\n- **mc-service** — Rust/Axum microservice in strict 4-layer Clean Architecture (Domain / Application / Adapters / API) with CQRS via `medi-rs` and MongoDB persistence.\n- **Agent layer** — a LangGraph supervisor served over AG-UI (reachable only through the BFF) drives three scoped MCP tool servers; models are environment-scoped (Ollama for dev/test, Claude for production).\n\nSee [docs/MCM-Architecture.md](docs/MCM-Architecture.md) for the full description and C4 diagrams.\n\n## Tech Stack\n\n| Area | Technology |\n|---|---|\n| Frontend | React Native 0.85, Expo SDK 56, Expo Router, Tamagui (`@mcm/design-system`), TypeScript |\n| BFF | Expo Router API routes (Node 24 container), Redis sessions, Axios |\n| Backend | Rust, Axum, Tokio, `medi-rs` (CQRS), MongoDB |\n| AI agents | Python 3.13, LangGraph, FastAPI + AG-UI, MCP, Langfuse/OpenTelemetry |\n| Identity & secrets | Keycloak, HashiCorp Vault |\n| Monorepo & build | pnpm workspaces + Nx (JS/TS, Rust, and Python orchestrated through one task runner) |\n| Testing | Jest, Playwright (web E2E), Maestro (mobile E2E), cargo test, pytest |\n| CI/CD & security | Forgejo Actions (self-hosted), Renovate, Semgrep (SAST), OWASP ZAP (DAST), Trivy (image CVEs), secret-scanning gates |\n\n## Repository Structure\n\n```text\n├── frontend/mcm-app/          # Universal Expo app + BFF (src/app, src/bff-server)\n├── backend/mc-service/        # Rust movie-collection service (Clean Architecture)\n├── agents/movie-assistant/    # LangGraph supervisor + AG-UI gateway\n├── mcp-servers/               # movie-mcp, web-api-mcp, spreadsheet-mcp\n├── packages/design-system/    # Shared Tamagui component library and tokens\n├── api-specs/                 # OpenAPI 3.0.3 contracts (API-first)\n├── infrastructure-as-code/    # Docker Compose stacks, Keycloak, Vault, observability, Komodo\n├── specs/                     # Spec Kit feature folders (spec/plan/tasks per feature)\n├── docs/                      # Architecture, PRDs, runbooks, decisions, templates (human-owned)\n├── openwiki/                  # Generated OKF knowledge wiki for coding agents (summaries + gotchas + links)\n├── scripts/                   # CI gates and dev utilities\n├── security/                  # SAST, DAST, and image-scan configuration\n└── .forgejo/workflows/        # CI/CD pipelines\n```\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 24 (LTS), pnpm (via Corepack), Nx\n- Rust (stable toolchain)\n- Python 3.13 + uv (agent layer)\n- Docker Desktop\n- Android Studio + JDK 17 (mobile development only)\n\n### Setup\n\n```bash\ngit clone <repo-url> && cd MovieCollectionManager\npnpm install\n\n# One-time per machine: shared Docker networks, named volumes, and dev secrets.\n# (Full list — including the agents/audit/observability profiles — in the local-dev runbook.)\ndocker network create backend-network\ndocker network create keycloak-network\ndocker network create movie-assistant-mcp-network\n\ndocker volume create keycloak-store-postgres-data\ndocker volume create mc-service-store-mongo-data\ndocker volume create mcm-bff-cache-redis-data\ndocker volume create mcm-bff-store-mongo-data\n\nnode scripts/gen-dev-secrets.mjs\n```\n\n### Run locally\n\n```bash\n# 1. Bring up auth (Keycloak + Postgres) — required first\npnpm nx up-auth infrastructure-as-code\n\n# 2. Optionally bring up the backend stack (mc-service + MongoDB + Redis)\npnpm nx up-mcm infrastructure-as-code\n\n# 3. Start the app (press w for web, a for Android)\ncd frontend/mcm-app && pnpm start\n```\n\nFull environment details, profiles, and endpoints: [docs/runbooks/local-dev.md](docs/runbooks/local-dev.md).\n\n## Run in Dev Containers\n\nThe repo ships a [Dev Containers](https://containers.dev/) definition (`.devcontainer/`, features 037/038/060) that runs the entire workshop — including the AI coding assistant — inside a disposable, isolated Linux container. **As of feature 060 that container is hosted on a Docker Sandbox microVM** rather than Docker-in-Docker:\n\n- **Isolation first** — the assistant runs as a non-root user with no path to the host filesystem, SSH keys, or credential stores. Containers and test stacks build on the **microVM's own engine as siblings** (`docker-outside-of-docker`), behind a **deny-by-default egress policy enforced outside the VM** — which is what makes it cover sibling containers too, closing the gap the in-container firewall never could.\n- **Faster, measurably** — the same five-stage bring-up takes **0.43×** the Docker-in-Docker wall-clock; `docker-build` alone went **1024 s → 293 s**, because a nesting level and the Windows filesystem are both out of the path.\n- **One-step entry** — `.\\scripts\\open-sandbox.ps1` (Windows PowerShell 5.1; `pwsh` not required) starts the sandbox if it is idle-stopped and opens VS Code directly inside the dev container.\n- **Full toolchain, pre-provisioned** — Rust + cargo tooling, Python via `uv`, Specify CLI, Node 24/pnpm/Nx, and `gh` are baked into a prebuilt `mcm-devcontainer` image (pulled from the forge registry by digest, or built locally via `node scripts/build-devcontainer-image.mjs`), so nothing is reinstalled per session.\n- **Fast** — budgets: cold first build < 5 min, warm recreate < 90 s, stop→start < 15 s; `cargo`/`pnpm`/`uv` caches persist across recreates on named volumes.\n- **Personal AI layer (optional)** — point the Dev Containers `dotfiles.repository` setting at your personal dotfiles repo to restore your Claude Code plugins/skills, RTK (built once from source in-container), and service logins; these persist on a personal-config volume, and the container is fully team-capable without them.\n\n**Interactive (daily driver — sandbox path):**\n\n```powershell\n.\\scripts\\open-sandbox.ps1     # Windows PowerShell 5.1; pwsh is NOT required\n```\n\nStarts the microVM if it has idle-stopped (it stops ~30 s after the last session) and opens VS Code **directly inside the dev container** — replacing the four-step *Remote-SSH → Open Folder → Attach* route. First-time setup of the sandbox itself: [docs/runbooks/devcontainer-sandbox.md](docs/runbooks/devcontainer-sandbox.md).\n\n**Headless (run inside the VM, where the engine and the workspace clone live):**\n\n```bash\nssh mcm.sbx\ndevcontainer up --workspace-folder /workspaces/mcm --config .devcontainer/sandbox/devcontainer.json\n```\n\n**Retained Docker Desktop path** (needed only for the Android emulator): VS Code → Command Palette → *Dev Containers: Clone Repository in Named Container Volume* → this repo's URL, using `.devcontainer/devcontainer.json`.\n\n### Expo/Metro limitation — native mobile stays on the host\n\nThe dev container covers backend/API development, compose-based test stacks, the **web target**, and the **Metro bundler** (watchman-backed, hot-reload at native speed). It never runs the **iOS Simulator** (macOS-only), and whether it can run the **Android emulator** depends on the path:\n\n| Path | Android emulator |\n|---|---|\n| **Docker Sandbox microVM** (default) | ❌ **never** — no nested virtualization, so `/dev/kvm` cannot exist |\n| Docker Desktop / DinD (retained) | ✅ headless with hardware accel, via the host's `/dev/kvm` |\n| CI | ✅ and the **recommended** route for agent flows |\n\nHow to develop the Expo app from inside the container:\n\n- **Web** — run `pnpm start` in-container and open the forwarded `localhost:8081` in a host browser (ports `8081` Metro/web/dev-BFF, `8082` containerized BFF, and `8099` Keycloak are forwarded; the legacy Expo `19000/19001/19006` ports are unused by SDK 56).\n- **Physical device** — point Expo Go / a dev build at the in-container Metro server over LAN; if LAN routing to the container isn't available, use the documented **Expo tunnel fallback** (`pnpm start --tunnel`).\n- **Emulator / native builds** — switch to the host for `expo run:android`, APK builds, and `pnpm nx e2e:mobile`; mobile agent E2E flows run in CI regardless (see [docs/runbooks/android-emulator.md](docs/runbooks/android-emulator.md)).\n\nThe **Android emulator is the one documented exception** and the sole reason the Docker Desktop path is retained: the microVM offers no nested virtualization, so `/dev/kvm` cannot appear there however the container is configured. `scripts/devcontainer-android.sh` refuses legibly and names both remaining routes (CI, or the retained Docker Desktop container) rather than failing as if broken.\n\nVerification scripts under `.devcontainer/verify/` prove host isolation, the engine seam, cache persistence, and toolchain completeness. Full procedure: **[docs/runbooks/devcontainer-sandbox.md](docs/runbooks/devcontainer-sandbox.md)** (the sandbox path) and [docs/runbooks/devcontainer.md](docs/runbooks/devcontainer.md) (the retained Docker Desktop path).\n\n## Development\n\nAll tasks run through Nx from the repo root — never npm/yarn, and never the underlying tools directly:\n\n```bash\npnpm nx test mcm-app                   # frontend unit tests\npnpm nx test mc-service                # Rust unit tests\npnpm nx lint mcm-app                   # ESLint\npnpm nx lint mc-service                # clippy\npnpm nx e2e mcm-app                    # web E2E (Playwright)\npnpm nx e2e:mobile mcm-app             # mobile E2E (Maestro, emulator required)\npnpm nx run-many --targets=test,lint   # everything cacheable\n```\n\nContributions follow spec-driven development: a feature starts as a `specs/NNN-name/` spec and plan, tests are written and verified failing before implementation (TDD is non-negotiable), and all work must comply with the [constitution](.specify/memory/constitution.md).\n\n## Developer Tools\n\nThe AI-assisted workflow relies on a standard set of tooling (all pre-provisioned in the dev container; install natively per the steps below if working on the host). Full step-by-step host setup: [docs/runbooks/dev-environment-setup.md](docs/runbooks/dev-environment-setup.md).\n\n### Core\n\n- **Claude Code** + the [Claude Code for VS Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) extension — the AI coding assistant this project is built with\n- **Specify CLI** (GitHub Spec Kit) — drives the spec → plan → tasks workflow: `uv tool install specify-cli --from git+https://github.com/github/spec-kit.git`\n- **RTK (Rust Token Killer)** — mandatory transparent CLI proxy that compresses command output before it reaches the assistant's context (~89% token savings): `cargo install --git https://github.com/rtk-ai/rtk && rtk init -g`; verify with `rtk gain` (> 80% required)\n- **gh** (GitHub CLI) and **EAS CLI** (`pnpm add -g eas-cli`) for forge/mirror and Expo builds\n\n### VS Code extensions\n\n- [rust-analyzer](https://code.visualstudio.com/docs/languages/rust) — Rust language support\n- [Nx Console](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console) — Nx target discovery and running\n- [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) — containerized development (see above)\n\n### Claude Code plugins & skills\n\n| Area | Plugin / skill |\n|---|---|\n| Rust | `rust-analyzer-lsp` (claude-plugins-official), `rust-skills` (actionbook/rust-skills) |\n| React Native / Expo | `react-native-best-practices`, `upgrading-react-native` (callstackincubator/agent-skills), `expo/skills` |\n| Nx | `nx-ai-agents-config` skill (`pnpm dlx skills add nrwl/nx-ai-agents-config`) |\n| Python / AI | `pyright-lsp`, `ai` (Pydantic AI, claude-plugins-official), `langsmith-tracing` (langchain-ai), `langchain-community` (Codeblockz) |\n| General dev | Frontend Design, Superpowers, Context7, Code Review, Security Guidance |\n\n### Cargo utilities\n\nSupply-chain and code-quality helpers used across the workflow: `cargo-audit`, `cargo-deny`, `cargo-outdated`, `cargo-machete`, `cargo-semver-checks`, `cargo-geiger`, `cargo-expand`, `cargo-bloat`, `cargo-mutants` (plus `cargo-tarpaulin` as a dev dependency for coverage).\n\n## Testing & Quality\n\n- ≥70% line coverage enforced on new code (Jest / tarpaulin)\n- Unit, integration (real dependencies — no mocks), and E2E suites repeated across web and mobile clients\n- CI gates on every push/PR: secret scan, naming conventions, SAST + dependency SCA, DAST, and weekly third-party image CVE scans\n\n## Security\n\nHighlights: BFF token custody (no tokens in the client), deny-by-default centralized authorization, structured logging with PII redaction and append-only audit streams, externalized secrets (no credentials in git — CI-enforced), and RFC 9457 error responses. See the constitution's Security section for the complete policy.\n\n## Roadmap\n\n- Web search for where to buy wishlist movies\n- NFO file creation and updates\n- Media-format scraping from digital movie files (ffprobe/ffmpeg)\n\n## License\n\nSee [LICENSE](LICENSE).\n",
  "bytes": 15017,
  "sha": "8c66563116826c5f084040c9d82c3596f5d6ce86852ee1336cea40f665b5fe6b",
  "repo_slug": "jumbleknot/moviecollectionmanager",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_jumbleknot_moviecollectionmanager_openwi_0db04f52/readme"
}