1. The Investigation Canvas & Dynamic Threads

PrimeTrace's primary canvas creates a moody, high-contrast dark environment where forensic elements stand out crisply. Threads connect nodes with mathematical curvature calculations and tactile physical styling.

Figure 1: Active investigation board demonstrating multi-node interconnectivity, anchor pins, and floating control dock.

• Header Command Bar: Displays current case name (Case Board I), continuous zoom percentage readout, Zoom Out / In buttons, Reset View, multi-level Undo / Redo, View mode toggles, and Theme switcher.
• Floating Quick-Tool Dock: Bottom pinned toolbar providing one-click insertion of primary cards (Add Thread, Note, Photo, Doc, Checklist, Project Brief, Lesson Plan, etc.) with expanding chevron.
• Node Pin Points: Every card features 4 metallic anchor pins (Top, Right, Bottom, Left) allowing intuitive drag-to-connect thread linking.

2. Multimedia Evidence & Case Dossiers

Investigations are rarely text-only. PrimeTrace integrates rich media playback directly onto the infinite surface.

Figure 2: Real-world case session ("Phot Audio Test") exhibiting active audio streaming with synced lyric transcript, polaroid suspect card, aged evidence paper, and video node.

Figure 3: Audio evidence player with loop control, transcript log, and Thread Hub hypothesis radar.

Figure 4: Suspect dossier card with alias tracking, surveillance mode, and risk level slider.

• Audio Evidence Node: Features local/URL audio ingestion, integrated playback scrubber, loop toggle, and dedicated forensic transcript / analyst notes textarea.
• Thread Hub Node: Acts as the investigative nexus—houses the central working theory, active thread radar counter, and checklist of open leads.
• Suspect Profile Node: Tracks suspect mugshot, known aliases, surveillance status (Surveillance, Detained, Cleared), interactive 0–100% Risk Level slider, and "Potentially Armed" indicator.

3. High-Precision Node Inspection & Typography

PrimeTrace pays obsessive attention to visual design, material textures, and typography.

Figure 5: Polaroid frame with translucent frosted tape and dynamic border palette swatch.

Figure 6: Video Evidence Node with media upload, start-muted toggle, and scene notes.

Figure 7: Sticky note linked via sawtooth zigzag thread to an investigative timeline event.

Figure 8: Distressed evidence parchment with typewriter typography and dashed cyan cable.

Figure 9: Sub-pixel rendering at 103% zoom showing crisp vector typography and subtle node drop shadows.

• Polaroid Photo Cards: Realistically textured white photo border with frosted tape holding it to the board, integrated file upload, and custom border tinting.
• Aged Evidence Documents: Classic cream paper with typewriter typography (Courier / monospace), confidential document badge, and dot grid texture.
• Sticky Notes: Curved paper peel corner, pushpin visual at top center, and handwritten font styling.

4. The 46-Tool Multi-Disciplinary Catalog

PrimeTrace includes an expandable, searchable catalog of 46 distinct forensic and productivity cards categorized across 11 professional fields.

Figure 10: The comprehensive tool library with search bar, profession chips, and right-click dock pinning.

• Instant Search: Filter all tools dynamically by keyword, label, or industry (e.g., police, software, medical, student, diagram).
• Right-Click Pinning: Customize your floating bottom dock by right-clicking any tool chip in the library to pin or unpin it.
• Visual Glyphs: Every tool features a dedicated 2-letter glyph code (e.g., NT for Note, PH for Photo, SE for Software Spec, VM for Vitals Monitor).

5. Canvas Operations & Multi-Format Export Center

The right slide-out panel gives investigators full control over canvas styling, board maintenance, and lossless exports.

Figure 11: Canvas settings drawer with grid controls, background customization, and multi-format exports.

• Canvas Background Modes:
  • Grid: Forensic coordinate grid with major and minor lines.
  • Plane: Seamless dark studio plane without distracting lines.
  • Custom Background: Upload custom floorplans, satellite imagery, or corkboard textures with fine-tuned opacity and brightness sliders.
• Export Formats:
  • Export PNG: High-resolution snapshot with transparent/solid background options.
  • Export SVG: Fully scalable vector graphic preserving vector threads and text elements.
  • Export WEBP: Compressed modern web image format.
  • Export PDF: Print-ready formatted document with case headers and timestamps.
  • Export Backup / Import Backup: JSON snapshot of the entire board state.
  • Export .ptcase: Proprietary binary file container with Gzip compression and CRC32 verification.
• Board Management: Auto Arrange layout engine, Duplicate Last, Remove Last, and Clear Board.

6. Cinematic Sequence Playback Engine

PrimeTrace is not just a static board—it is a presentation engine. Sequence Playback allows you to guide audiences step-by-step through a case.

Figure 12: Sequence playback mode showing highlighted card #2, camera tracking along thread paths, and playback dock.

• Dynamic Camera Director: The camera smoothly glides across the infinite canvas from card to card, following the connecting thread path with ease-in-out interpolation.
• Floating Playback Dock:
  • Transport: Play / Pause, Previous Step, Next Step.
  • Loop & Shuffle Modes: Continuous cyclic replay or randomized hypothesis review.
  • Speed Multiplier: Instant switching between 0.5x, 1.0x, 1.5x, and 2.0x.
  • Timing Engine: Configurable travel duration (time spent moving between nodes) and dwell duration (time spent observing each node).
  • Exit Playback: Return immediately to free-roam editing with one click.

7. Macro Constellation & Orthogonal Routing

Zoom out to grasp the macro-topology of your investigation or preview the full sequential progression across all evidence.

Figure 13: 19% macro zoom showing full network topology and global thread paths.

Figure 14: Sequence preview mode displaying numeric step badges (1–15) and yellow thread channels.

Architectural Topology

graph TD
    subgraph Client Runtime [Electron 35 / Web Browser]
        A[index.html] --> B[main.tsx - Bootstrapper]
        B --> C[RuntimeErrorBoundary]
        B --> G[Ghost Signature Engine]
        C --> D[App.tsx]
        D --> E[DetectiveBoardPreset.tsx]
    end

    subgraph Infinite Canvas Layer
        E --> F[DetectiveBoardCanvas.tsx]
        F --> H[useInfiniteCamera Hook]
        H --> I[Matrix2D Math Engine]
        F --> J[Infinite Background Layer]
    end

    subgraph Visual Nodes & Connectors Layer
        E --> K[BoardConnectionsProvider]
        K --> L[BoardConnectionsLayer - SVG Renderer]
        K --> M[DraggableNode Wrapper]
        M --> N[46 Core & Profession Card Nodes]
    end

    subgraph Cinematic Storytelling
        E --> O[sequencePlayback.ts]
        O --> P[SequencePlaybackControls.tsx]
        O --> Q[SequencePlaybackOverlay.tsx]
    end

    subgraph Persistent Storage & Export
        E --> R[boardStorage.ts]
        R --> S[(IndexedDB - Media Blobs)]
        R --> T[(LocalStorage - Scoped Keys)]
        E --> U[ptcaseFormat.ts - Binary Encoder/Decoder]
        E --> V[boardExport.ts - PNG/SVG/PDF/WEBP]
    end
            

Coordinate System & 2D Affine Matrix

The canvas operates on an arbitrary 2D coordinate space powered by a 6-element affine transformation matrix:

• State Representation: Stored in Matrix2D = [a, b, c, d, tx, ty] where a and d represent scale, and tx and ty represent world translation.
• Screen to World Mapping:
  $$\vec{P}_{world} = M^{-1} \cdot \vec{P}_{screen}$$
  Calculated by computing the scalar determinant $\det = a \cdot d - b \cdot c$ and applying the adjugate matrix.
• World to Screen Mapping:
  $$\vec{P}_{screen} = M \cdot \vec{P}_{world}$$
• Zoom Anchoring: Zooms preserve cursor-centric focus so the point directly beneath the pointer remains stationary in world space.

The Thread Engine & Mathematical Physics

Connections between nodes are rendered dynamically within an SVG layer positioned behind the interactive cards (zIndex: 0).

graph LR
    SourcePin[Source Pin] -->|Start Coord| ThreadEngine[Thread Path Generator]
    TargetPin[Target Pin] -->|End Coord| ThreadEngine
    Style{Style Selector} --> ThreadEngine
    ThreadEngine -->|curve| Bezier[Cubic Bezier Path]
    ThreadEngine -->|straight| Linear[Direct Line Path]
    ThreadEngine -->|arc| QuadArc[Quadratic Droop Arc]
    ThreadEngine -->|zigzag| Jagged[Sawtooth Normal Offset]
    ThreadEngine -->|handmade| Organic[Harmonic Wool Wave]
            

1. Cubic Bezier (curve): Evaluates departure normal vectors based on the origin pin anchor (top, bottom, left, right) and computes smooth tangent control points.
2. Quadratic Arc (arc): Simulates physical gravity on loose twine:
   $$C_x = \frac{x_1 + x_2}{2}, \quad C_y = \frac{y_1 + y_2}{2} - \min\left(120, \|\Delta\vec{P}\| \cdot 0.28\right)$$
3. Sawtooth Zigzag (zigzag): Calculates normal unit vector $\hat{n} = (-\sin\theta, \cos\theta)$ perpendicular to the chord and alternates positive and negative offsets across evenly spaced intervals.
4. Handmade Fiber (handmade): Adds high-frequency sinusoidal harmonic variation to evoke realistic twisted wool yarn:
   $$\text{offset}(t) = \sin(4\pi t) \cdot 7 + \cos(6\pi t) \cdot 3$$

Node Anatomy & Interactive Layer

Every item on the canvas is wrapped by DraggableNode.tsx, granting it universal forensic properties:

┌─────────────────────────────────────────────────────────────┐
│                       [Top Pin]                             │
│                     ┌───────────┐                           │
│                     │ Rotate ⟲  │                           │
│                     └───────────┘                           │
│  [Left Pin]     ┌───────────────────┐        [Right Pin]    │
│                 │                   │                       │
│                 │   Specific Node   │                       │
│                 │     Component     │                       │
│                 │  (Audio, Photo,   │                       │
│                 │   Suspect, etc.)  │                       │
│                 │                   │                       │
│                 └───────────────────┘                       │
│                       [Bottom Pin]              [Resize ↘]  │
└─────────────────────────────────────────────────────────────┘Copy

• Selective Event Propagation: Textareas, inputs, sliders, and audio players retain full interactive pointer events via [data-node-interactive='true'], while dragging outside interactive controls moves the entire card.
• Sub-Pixel Precision: Coordinates are stored as floating-point world numbers, decoupling node positions from client viewport pixel densities.
• Dynamic Transforms:
  • Rotation: Free $360^\circ$ circular rotation handle.
  • Scale: $40\%$ to $220\%$ uniform zoom scaling.
  • Opacity: $20\%$ to $100\%$ ghost transparency.
  • Brightness: $40\%$ to $180\%$ forensic light filter.
  • Proportional Resizing: Diagonal resize handles with minimum size boundaries.

Core Detective Tools (14)

Professional & Domain-Specific Tools (32)

PrimeTrace adapts beyond crime scenes to 11 distinct professional domains:

Storage Subsystem Architecture

PrimeTrace implements a dual-tier storage strategy to ensure fast initialization and zero data loss:

graph TD
    BoardState[Board State Change] --> Splitter{Data Type Classifier}
    Splitter -->|Lightweight Meta & Layout| LS[Scoped LocalStorage Engine]
    Splitter -->|Heavy Media Blobs| IDB[IndexedDB Blob Vault]
    LS --> OriginPrefix["Key: detective-board:node:{id}@origin-{hash}"]
    IDB --> BlobStore["ObjectStore: 'blobs' in 'detective-board' DB"]
            

1. Origin Scoping: All storage keys are partitioned using an origin token (e.g., @origin-localhost-5173 or @origin-desktop), completely preventing namespace collisions between projects or environments.
2. Media Blob Vault: Large images, audio clips, and video files are cached in IndexedDB as raw binary Blob instances, keeping localStorage lightweight and fast.
3. Image Compression Pipeline: Uploaded photos are automatically compressed via HTML5 Canvas using progressive JPEG/WebP compression to prevent memory exhaustion.

The .ptcase Binary Specification

PrimeTrace defines its own proprietary, single-file binary container format (.ptcase):

+---------------------------------------------------------------------------------+
| Offset (Bytes) | Field Name            | Data Type     | Value / Description    |
+----------------+-----------------------+---------------+------------------------+
| 0 .. 5         | Magic ASCII Header    | 6 bytes       | "PTCASE" (0x50..0x45)  |
| 6              | Format Version        | uint8         | 0x01                   |
| 7              | Flags                 | uint8         | 0x00 (Reserved)        |
| 8 .. 15        | Timestamp             | uint64 (BE)   | Milliseconds since epoch|
| 16 .. 19       | Compressed Payload Len| uint32 (BE)   | Length of Gzip stream  |
| 20 .. (N-4)    | Payload Data          | Binary (var)  | Gzip-compressed JSON   |
| (N-3) .. N     | Checksum              | uint32 (BE)   | CRC-32 (ISO 3309)      |
+----------------+-----------------------+---------------+------------------------+Copy

• Integrity Verification: Decoders validate the PTCASE magic bytes and calculate a CRC-32 checksum across the payload. If corrupted, import fails with an explicit integrity warning.
• Streaming Compression: Uses the native Web Stream APIs (CompressionStream("gzip") and DecompressionStream("gzip")) for compression speed without external dependencies.
• Windows File Association: Registered in Windows through NSIS installer configuration (electron-builder.yml), giving .ptcase files dedicated system icons and double-click opening capability.

Prerequisites

• Node.js: Version >= 20.19.0 required.
• NPM: Version >= 10.0.0.
• Operating System: Windows 10/11 (for desktop installer generation), macOS or Linux (for web development).

Web Development

To run the web version locally in your browser with hot module replacement:

# 1. Navigate to the application directory
cd e:/PrimeBoard-main/Main_App

# 2. Install all dependencies
npm install

# 3. Start the Vite development server
npm run devCopy

Open your browser and navigate to: http://localhost:5173.

Desktop App (Electron)

To run the full native desktop version with Electron IPC bridges and desktop window management:

cd e:/PrimeBoard-main/Main_App

# Launches Vite in background and opens the Electron native window
npm run electron:devCopy

Production Packaging (Windows NSIS x64)

To build a standalone, distributable Windows .exe installer complete with desktop shortcuts, Start Menu integration, and .ptcase file associations:

cd e:/PrimeBoard-main/Main_App

# Generates production bundle and creates the NSIS installer
npm run electron:buildCopy

The compiled installer will be saved to:
e:/PrimeBoard-main/Main_App/release/PrimeTrace Setup 1.0.0.exe

Cloudflare Pages Deployment

PrimeTrace is edge-ready and includes a configured wrangler.toml:

cd e:/PrimeBoard-main/Main_App

# 1. Build the production web bundle
npm run build

# 2. Deploy to Cloudflare Pages
npx wrangler pages deploy dist --project-name=primetraceCopy