stripstream-librarian/PLAN.md

Stripstream Librarian - Plan de Suivi MVP

Objectif

Construire un serveur ultra performant pour indexer et servir des bibliotheques de livres/comics/BD (cbz, cbr, pdf) avec:

• API REST (librairies, livres, metadonnees, recherche, streaming pages),
• indexation incrementale,
• recherche full-text,
• backoffice web (Next.js) pour gerer librairies/jobs/tokens,
• deploiement Docker Compose homelab.

Decisions figees

• Backend/API: Rust (axum)
• Indexation: service Rust dedie (indexer)
• DB: PostgreSQL
• Recherche: PostgreSQL full-text (ILIKE + pg_trgm)
• Deploiement: Docker Compose
• Auth: token bootstrap env + tokens admin en DB (creables/revocables)
• Expiration tokens admin: aucune par defaut (revocation manuelle)
• Rendu PDF: a la volee
• CBR: extraction temporaire disque (unrar-free, commande unrar) + cleanup
• Formats pages: webp, jpeg, png
• Backoffice UI: Next.js (remplace Rust SSR)

---

Backlog executable (ordre recommande)

T1 - Bootstrap monorepo Rust

• Creer workspace Cargo
• Creer crates/apps: apps/api, apps/indexer, apps/admin-ui, crates/core, crates/parsers
• Config env centralisee + logging de base

DoD: Build des crates OK.

T2 - Infra Docker Compose

• Definir services postgres, api, indexer
• Volumes persistants
• Healthchecks

DoD: docker compose up demarre tout, services healthy.

T3 - Schema DB + migrations

• Tables: libraries, books, book_files, index_jobs, api_tokens
• Index/contraintes (uniques, FK)
• Scripts de migration

DoD: Migrations appliquees sans erreur, schema stable.

T4 - Auth hybride

• Middleware Authorization: Bearer <token>
• Verif API_BOOTSTRAP_TOKEN
• Verif tokens DB (hash Argon2id, non revoques/non expires)
• MAJ last_used_at

DoD: Acces protege fonctionnel, tokens revoques refuses.

T5 - API admin tokens

• POST /admin/tokens (affichage secret une seule fois)
• GET /admin/tokens (sans secret)
• DELETE /admin/tokens/:id (revoke)

DoD: Flux creation/liste/revocation valide.

T6 - CRUD librairies

• GET /libraries
• POST /libraries
• DELETE /libraries/:id
• Validation stricte des chemins (anti traversal)

DoD: Gestion librairies robuste et securisee.

T7 - Jobs d'indexation

• Orchestration scan/rebuild
• POST /index/rebuild
• GET /index/status
• Persist statuts/erreurs dans index_jobs

DoD: Jobs tracables et relancables.

T8 - Scan incremental

• Decouverte fichiers supportes
• Fingerprint (size, mtime, hash partiel)
• Upsert book_files
• Detection suppressions/renommages

DoD: Rescan = traitement des deltas uniquement.

T9 - Parsing CBZ

• Lecture zip + ordre pages naturel
• Metadonnees de base + cover
• Gestion erreurs archive

DoD: Livres CBZ indexes correctement.

T10 - Parsing CBR (temp disk)

• Extraction temp via unrar
• Ordonnancement pages
• Cleanup garanti (meme en erreur)

DoD: Pas de fuite temp, parsing stable.

T11 - Parsing PDF

• Metadonnees (titre/auteur/pages)
• Preparation rendu page a la volee
• Gestion fichiers corrompus

DoD: PDF indexes et lisibles.

T12 - API livres

• GET /books (filtres + curseur)
• GET /books/:id
• Contrat JSON propre et stable

DoD: Pagination/filtres fonctionnels.

T13 - Recherche

• Recherche full-text PostgreSQL
• GET /search?q=...&library_id=...&type=...
• Fuzzy + filtres

DoD: Recherche rapide et pertinente.

T14 - Streaming pages multi-format

• GET /books/:id/pages/:n
• Query: format=webp|jpeg|png, quality=1..100, width
• Headers cache (ETag, Cache-Control)
• Validation stricte params

DoD: Pages servies correctement dans les 3 formats.

T15 - Perf guards

• Cache LRU en memoire (cle: book:page:format:quality:width)
• Limite concurrence rendu PDF
• Timeouts et bornes (width max)

DoD: Service stable sous charge homelab.

T16 - Backoffice Next.js

• Bootstrap app Next.js (apps/backoffice)
• Vue Libraries (folder selector, add/delete)
• Vue Jobs (rebuild per library, cancel job)
• Vue API Tokens (create/list/revoke)
• Auth backoffice via token API
• Theme switcher Light/Dark
• Style aligne avec site officiel

DoD: Backoffice Next.js utilisable pour l'administration complete.

T17 - Observabilite et hardening

• Logs structures tracing
• Metriques Prometheus
• Health/readiness endpoints
• Rate limiting leger

DoD: Diagnostics et exploitation simples.

T18 - Validation MVP

• Tests d'integration API
• Smoke tests compose
• Bench p95/p99 basiques

DoD: Checklist MVP validee de bout en bout.

T19 - Progression temps reel des jobs (Option 2 - stockage minimal) - [COMPLETE]

• Table index_job_errors pour stocker les erreurs (job_id, file_path, error_message, created_at)
• Endpoint polling GET /index/jobs/:id (remplace SSE pour compatibilite) avec progression temps reel
• Indexer: stockage progression en DB (current_file, progress_percent, processed_files, total_files)
• Backoffice: composant JobProgress avec barre de progression et pourcentage
• Affichage du fichier en cours de traitement et compteur (traite/total)
• Stats globales utilisees depuis index_jobs.stats_json

DoD: ✅ Barre de progression temps reel + erreurs stockees pour debug post-job.

T20 - Header avec indicateur jobs - [COMPLETE]

• Endpoint GET /index/jobs/active pour recuperer les jobs pending/running
• Composant JobsIndicator dans le header avec badge compteur dynamique
• Dropdown au clic affichant la liste des jobs actifs avec progression
• Polling toutes les 5s pour mise a jour temps reel
• Lien rapide vers la page jobs detaillee

DoD: ✅ Icone cliquable dans le header montrant les jobs en cours avec badge rouge.

T21 - Bouton indexation sur libraries - [COMPLETE]

• Boutons "Index" (incremental) et "Index Full" (rebuild complet) sur chaque ligne
• Endpoint POST /libraries/:id/scan pour lancer le job
• Support parametre full: true pour rebuild complet
• Feedback visuel via revalidation Next.js
• Type de job full_rebuild distinct du rebuild normal

DoD: ✅ Lancement d'indexation direct depuis la page libraries avec support full rebuild.

T22 - Details enrichis des jobs - [COMPLETE]

• Endpoint GET /index/jobs/:id avec statistiques completes
• Endpoint GET /index/jobs/:id/errors avec liste des erreurs
• Page detaillee /jobs/[id]/page.tsx avec:
  • Timeline visuelle (Created → Started → Finished)
  • Barre de progression avec pourcentage
  • Stats: scanned, indexed, removed, errors
  • Vitesse de traitement (fichiers/sec)
  • Liste des erreurs detaillees
  • Navigation retour vers la liste
• Bouton "View" sur chaque ligne de job
• Lien cliquable sur l'ID du job

DoD: ✅ Page job detaillee avec timeline, stats completes et navigation.

T23 - Surveillance automatique des libraries - [PARTIEL]

• Migration 0004_library_monitoring.sql: colonnes monitor_enabled, scan_mode, last_scan_at, next_scan_at
• Enum scan_mode: 'manual', 'hourly', 'daily', 'weekly' avec contrainte CHECK
• Checkbox "Enable monitoring" et select "Scan frequency" dans formulaire library
• Scheduler dans l'indexer (toutes les minutes) verifiant les libraries a scanner
• Endpoint POST /libraries/:id/scan pour scan manuel declenche par API
• Badge "Auto" (vert) ou "Manual" (gris) dans la liste des libraries
• Prochain scan estime affiche dans les details de la library

DoD: ⚠️ Schema DB et endpoint API OK, UI et scheduler a implementer.

---

Contrat API minimum (v1)

• GET /libraries
• POST /libraries
• DELETE /libraries/:id
• POST /libraries/:id/scan (T23)
• GET /books
• GET /books/:id
• GET /search
• GET /books/:id/pages/:n
• POST /index/rebuild
• GET /index/status
• GET /index/jobs/active (T20)
• GET /index/jobs/:id/details (T22)
• GET /index/jobs/:id/files (T22)
• GET /index/jobs/:id/stream (T19)
• POST /admin/tokens
• GET /admin/tokens
• DELETE /admin/tokens/:id

---

Cibles perf MVP (homelab)

• GET /books/:id < 30 ms p95 (cache chaud)
• GET /search < 80 ms p95
• 1ere reponse /pages/:n < 200 ms p95 (hors PDF froid lourd)

---

Risques connus et mitigation

• CBR heterogene -> isolation erreurs + logs detailles + retries limites
• PDF lourds CPU -> pool borne + timeout + cache
• Drift DB/Search -> indexation idempotente + job rebuild complet

---

Suivi d'avancement

• Lot 1: Fondations (T1 -> T6)
• Lot 2: Ingestion + Search (T7 -> T13)
• Lot 3: Lecture + UI + Hardening (T14 -> T18)
• Lot 4: Ameliorations Indexation (T19 -> T22) [COMPLETE PARTIELLEMENT]
• Lot 5: Optimisations et Polishing (T23 + ameliorations)

Notes

• Scope token v1: admin, read
• Bootstrap token = break-glass (peut etre desactive plus tard)

Journal

• 2026-03-05: docker compose up -d --build valide, stack complete en healthy (postgres, api, indexer, admin-ui).
• 2026-03-05: ajustements infra appliques pour demarrage stable (unrar -> unrar-free, image rust:1-bookworm, healthchecks 127.0.0.1).
• 2026-03-05: ajout d'un service migrate dans Compose pour executer automatiquement infra/migrations/0001_init.sql au demarrage.
• 2026-03-05: Lot 2 termine (jobs, scan incremental, parsers cbz/cbr/pdf, API livres, recherche PostgreSQL).
• 2026-03-05: verification de bout en bout OK sur une librairie de test (/libraries/demo) avec indexation, listing /books et recherche /search (1 CBZ detecte).
• 2026-03-05: Lot 3 avancee: endpoint pages (/books/:id/pages/:n) actif avec cache LRU, ETag/Cache-Control, limite concurrence rendu et timeouts.
• 2026-03-05: hardening API: readiness expose sans auth via route_layer, metriques simples /metrics, rate limiting lecture (120 req/s).
• 2026-03-05: smoke + bench scripts corriges et verifies (infra/smoke.sh, infra/bench.sh).
• 2026-03-05: pivot backoffice valide: remplacement de l'admin UI Rust SSR par une app Next.js.
• 2026-03-05: backoffice Next.js implemente (apps/backoffice) avec branding neon base sur le logo, actions libraries/jobs/tokens, et integration Docker Compose.
• 2026-03-06: planification Lot 4 - ajout des taches T19-T23 pour ameliorations indexing (progression temps reel, indicateur header, bouton indexation, details jobs, surveillance auto libraries)