gupi-osint-board/docs/TODO.md

GUPI OSINT Board roadmap

This is the ordered implementation roadmap following the accepted exhibit model. Work generally proceeds from top to bottom. It is not a substitute for migrations or implementation issues.

Working agreement

• Spend roughly 60% of development time on features and model work, 25% on tests and bug fixing, and 15% on repository and deployment hygiene.
• Stop feature work for interaction-breaking, data-loss, migration, or deployment bugs. Batch cosmetic defects separately.
• A new exhibit behavior is complete only when its PostgreSQL representation, API behavior, frontend widget, persistence, and focused tests agree.
• Mystery content must be authored as template data through supported application operations, never hard-coded into React components.

Milestone 0: trustworthy baseline

• Track .gitignore, .dockerignore, and .env.example; confirm that secrets and generated artifacts cannot enter Git accidentally.
• Commit the current working POC and tag the checkpoint poc-pre-exhibit-model.
• Confirm main is pushed to the Ramanujan-hosted origin repository.
• Keep npm run build green and make npm test run real tests rather than an empty suite.

Milestone 1: focused safety net

• Test screen/board coordinate conversion across pan and zoom levels.
• Test timeline date-to-pixel projection and recomputation after viewport resizing.
• Test the interaction boundary between exhibit dragging, hand-tool panning, and board-only pinch zoom.
• Test folder open/close behavior, retained file positions, and containment-band state.
• Test document upload, metadata persistence, board save/reload, and reset.
• Run migrations and API integration tests against disposable PostgreSQL, not SQLite or mocked persistence.
• Add one browser smoke test: open an isolated level, drag an exhibit, pan, board-zoom, open a folder, move a file, reload, and verify persistence.

Milestone 2: exhibit-schema cutover

• Add boards, exhibits, exhibit types, subtype tables, immutable template versions, and mutable levels.
• Cut over the explicitly disposable POC database directly; no transitional data existed to backfill or compare.
• Implement template instantiation, version selection, reset, and “save level as template” as transactional clone operations.
• Introduce a server-side repository/service boundary so SQL and cloning transactions do not live in Express route handlers.
• Move exhibit and document rendering to a typed frontend widget registry backed by the normalized API.
• Remove transitional widgets, widget_relations, and playthrough_* tables in the canonical cutover migration.

Milestone 3: events and parties

Events and narrative

• Implement Event exhibits with occurrence time and investigator-authored narrative text.
• Implement normalized Event-to-Evidence links and their board visualization.
• Present chronologically ordered events as the emerging investigation story.

Party exhibits

• Add a Party exhibit supertype representing an investigation participant.
• Add a Person subtype with display name, normalized aliases, and extensible structured identity fields.
• Add an Organization subtype covering businesses, public bodies, associations, and informal groups.
• Add normalized many-to-many Party-to-Evidence associations with an optional explanatory note.
• Add typed Party-to-Party relationships such as employment, ownership, membership, control, and representation.
• Build distinct Person and Organization widgets that can open as dossiers and reveal associated evidence without using folder ownership semantics.
• Include parties, aliases, evidence associations, and party relationships in template/level cloning.

Milestone 4: first playable mystery

• Design a small mystery that exercises documents, folders, notes, events, people, organizations, connections, and the timeline.
• Create it as an immutable level-template version using the same supported operations available to an author.
• Instantiate and solve a cloned level without modifying the template or relying on hard-coded case behavior.
• Turn the successful solve path into an end-to-end acceptance test.
• Perform a manual playability and visual-polish pass before production deployment.