# rockeyyabraham/15_rrr_acmnexus26 architecture

> Architecture diagram of the GitHub repository rockeyyabraham/15_rrr_acmnexus26, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rockeyyabraham/15_rrr_acmnexus26
- Repository: https://github.com/rockeyyabraham/15_rrr_acmnexus26

## Overview

1. **What this repo is**
   - Sentinel is a two-part system: a Python backend that fingerprints and compares media for piracy detection, and a React/TypeScript frontend that presents ingestion, detection, evidence, and legal workflows.
   - The architecture is organized around a single enforcement pipeline: ingest protected content, generate fingerprints, scan or compare candidates, score matches, and generate DMCA/legal artifacts.

2. **Backend as the core engine layer**
   - `backend/api/main.py` is the main service entrypoint and likely exposes the HTTP API and real-time update channel described in the README.
   - The backend is where the actual detection logic lives; the frontend is mostly a control and visualization surface.

3. **Detection subsystem boundaries**
   - `backend/engines/hash_engine.py` handles video fingerprinting.
   - `backend/engines/audio_engine.py` handles audio signatures.
   - `backend/engines/dual_engine.py` combines video and audio results into a single decision score.
   - `backend/engines/matcher.py` appears to compare candidate media against stored fingerprints and produce match confidence.
   - This separation is important: video, audio, and fusion logic are independent modules, which supports parallelism and isolated testing.

4. **Discovery and acquisition path**
   - `backend/engines/video_downloader.py` and `backend/engines/web_scanner.py` indicate the system can acquire candidate content from URLs or web sources before analysis.
   - `backend/engines/discovery_engine.py` and `backend/demo_discovery.py` suggest a higher-level orchestration layer for finding and collecting piracy candidates.
   - The discovery path is distinct from the ingestion path: one protects known assets, the other searches for suspected violations.

5. **AI and legal generation layer**
   - `backend/engines/ai_engine.py` is the intelligence layer mentioned in the README, likely used for narrative summaries, risk scoring, or recommendation text.
   - `backend/generators/dmca_generator.py` turns detection evidence into formal enforcement output, including the PDF notices stored in `backend/notices/`.
   - This forms the “legal response” boundary: technical detection outputs are transformed into human-usable documents.

6. **Persistence and state**
   - `sentinel.db` is the local SQLite store for the core system state.
   - `backend/utils/redis_utils.py` indicates Redis is used for caching or async coordination, consistent with the README’s performance claims.
   - The architecture therefore has two persistence roles: durable records in SQLite and transient/high-speed state in Redis.

7. **Frontend dashboard structure**
   - `frontend/src/pages/DetectionPage.tsx`, `IngestPage.tsx`, `EvidencePage.tsx`, and `LegalPage.tsx` mirror the backend workflow stages.
   - Shared UI is organized into `components/` such as `DetectionFeed`, `ChartPanel`, `Sidebar`, `Topbar`, `StatCard`, and `UploadBox`.
   - `frontend/src/services/api.ts` is the boundary layer that calls backend endpoints; the frontend does not implement detection itself.

8. **User-facing workflow**
   - The UI supports a progression from upload/ingest to detection monitoring, evidence review, and legal notice creation.
   - `frontend/src/constants/thresholds.ts` suggests detection thresholds are surfaced in the UI, making confidence/scoring a first-class concept in the product.
   - `usePersistedState.ts` implies some dashboard state survives reloads, which matters for demo continuity and operator workflow.

9. **Runtime and toolchain**
   - Backend is Python-based, with Flask as the API framework and OpenCV as the media processing dependency per the README/requirements.
   - Frontend uses React + TypeScript + Vite + TailwindCSS.
   - This split means compute-heavy media analysis stays in Python, while the browser handles live visualization and operator controls.

10. **Demo and execution scripts**
   - `backend/run_full_pipeline.py`, `backend/run_discovery_demo.py`, and `backend/api/main.py` suggest separate execution modes for full system demo, discovery-only demo, and service runtime.
   - `start.bat` / `start.ps1` are top-level launchers for the integrated local demo.
   - `backend/test_imports.py` and `backend/demo_discovery.py` look like smoke/demo utilities rather than production logic.

11. **Testing and validation boundaries**
   - Backend tests are concentrated in `backend/tests/`, especially `test_candidate_flow.py`, `test_policy_async_unit.py`, and `test_sentinel.py`.
   - There is also a top-level `tests/test_bias_tuning.py`, indicating some cross-cutting validation outside the backend package.
   - `backend/utils/piracy_benchmark.py` and `generate_test_data.py` support performance and variant-generation validation, which is central to the repo’s claim of benchmarked detection accuracy.

12. **Supporting artifacts and operational evidence**
   - `backend/logs/` and `backend/error.log` capture runtime failures.
   - `progress/` stores hackathon progress evidence, while `docs/` contains design, validation, and workflow documentation.
   - `assets/videos/` provides sample media inputs for testing and demos, making the repo self-contained for showcase runs.

13. **Overall data flow**
   - Protected media is ingested through the backend, fingerprinted by media-specific engines, and stored in local persistence.
   - Candidate streams/URLs are discovered or downloaded, then matched against stored fingerprints.
   - Results are scored and surfaced to the frontend, where operators inspect evidence and trigger DMCA generation.
   - The system is therefore a pipeline with clear stages: acquisition, analysis, matching, decision, and enforcement.

14. **Key architectural boundary to diagram**
   - Draw a hard line between the **browser UI** and the **Python detection backend**.
   - Inside the backend, show three major subsystems: **media analysis engines**, **candidate discovery/acquisition**, and **legal/document generation**.
   - Connect those to **SQLite/Redis** and to the **frontend API service**; the frontend should only consume results and actions, not perform core detection.

Main entry points: [`backend/api/main.py`](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/api/main.py) (API Service), [`backend/engines/discovery_engine.py`](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/discovery_engine.py) (Discovery), [`backend/engines/matcher.py`](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/matcher.py) (Matcher), [`backend/engines/dual_engine.py`](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/dual_engine.py) (Decision Fusion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["UI App<br/>React+TS shell<br/>[App.tsx]"]
  node_frontend_pages["Workflow Pages<br/>dashboard pages"]
  node_frontend_components["Shared UI<br/>components"]
  node_frontend_api["API Client<br/>service layer<br/>[api.ts]"]
  node_frontend_state(("UI State<br/>persisted state"))
end

subgraph group_backend["Backend"]
  node_backend_api["API Service<br/>Flask entrypoint<br/>[main.py]"]
  node_discovery{{"Discovery<br/>candidate acquisition"}}
  node_scanner["Web Scan<br/>source scanner<br/>[web_scanner.py]"]
  node_downloader["Downloader<br/>media fetch"]
  node_fingerprint_video{{"Video Hashing<br/>video fingerprints<br/>[hash_engine.py]"}}
  node_fingerprint_audio{{"Audio Signatures<br/>audio fingerprints<br/>[audio_engine.py]"}}
  node_matcher{{"Matcher<br/>comparison engine<br/>[matcher.py]"}}
  node_fusion{{"Decision Fusion<br/>scoring engine<br/>[dual_engine.py]"}}
  node_ai["AI Layer<br/>narrative intelligence<br/>[ai_engine.py]"]
  node_dmca["DMCA Generator<br/>legal document gen<br/>[dmca_generator.py]"]
end

subgraph group_data["Data/Artifacts"]
  node_sqlite[("SQLite DB<br/>persistent store<br/>[sentinel.db]")]
  node_redis[("Redis Cache<br/>transient state<br/>[redis_utils.py]")]
  node_notices["Notices<br/>generated PDFs"]
end

node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"composes"| node_frontend_components
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_api -->|"HTTP"| node_backend_api
node_frontend_pages -->|"persists"| node_frontend_state
node_backend_api -->|"orchestrates"| node_discovery
node_backend_api -->|"uses"| node_fingerprint_video
node_backend_api -->|"uses"| node_fingerprint_audio
node_backend_api -->|"uses"| node_matcher
node_backend_api -->|"scores"| node_fusion
node_backend_api -.->|"annotates"| node_ai
node_backend_api -->|"generates"| node_dmca
node_discovery -->|"scans"| node_scanner
node_discovery -->|"fetches"| node_downloader
node_fingerprint_video -->|"stores"| node_sqlite
node_fingerprint_audio -->|"stores"| node_sqlite
node_matcher -->|"reads"| node_sqlite
node_fusion -.->|"caches"| node_redis
node_dmca -->|"writes"| node_notices
node_backend_api -.->|"coordinates"| node_redis
node_backend_api -->|"persists"| node_sqlite
node_discovery -->|"feeds"| node_matcher
node_matcher -->|"outputs"| node_fusion
node_fusion -->|"returns"| node_frontend_api
node_dmca -.->|"exposes"| node_frontend_api

click node_frontend_app "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/frontend/src/App.tsx"
click node_frontend_pages "https://github.com/rockeyyabraham/15_rrr_acmnexus26/tree/main/frontend/src/pages"
click node_frontend_components "https://github.com/rockeyyabraham/15_rrr_acmnexus26/tree/main/frontend/src/components"
click node_frontend_api "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/frontend/src/services/api.ts"
click node_frontend_state "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/frontend/src/hooks/usePersistedState.ts"
click node_backend_api "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/api/main.py"
click node_discovery "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/discovery_engine.py"
click node_scanner "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/web_scanner.py"
click node_downloader "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/video_downloader.py"
click node_fingerprint_video "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/hash_engine.py"
click node_fingerprint_audio "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/audio_engine.py"
click node_matcher "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/matcher.py"
click node_fusion "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/dual_engine.py"
click node_ai "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/ai_engine.py"
click node_dmca "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/generators/dmca_generator.py"
click node_sqlite "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/sentinel.db"
click node_redis "https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/utils/redis_utils.py"
click node_notices "https://github.com/rockeyyabraham/15_rrr_acmnexus26/tree/main/backend/notices"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_pages,node_frontend_components,node_frontend_api,node_frontend_state toneBlue
class node_backend_api,node_discovery,node_scanner,node_downloader,node_fingerprint_video,node_fingerprint_audio,node_matcher,node_fusion,node_ai,node_dmca toneAmber
class node_sqlite,node_redis,node_notices toneMint
```

## Components

### Frontend

React dashboard and operator workflows.

- [UI App](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/frontend/src/App.tsx): React+TS shell · Browser dashboard entry and routing. · `frontend/src/App.tsx`
- [Workflow Pages](https://github.com/rockeyyabraham/15_rrr_acmnexus26/tree/main/frontend/src/pages): dashboard pages · Ingest, detection, evidence, and legal screens. · `frontend/src/pages`
- [Shared UI](https://github.com/rockeyyabraham/15_rrr_acmnexus26/tree/main/frontend/src/components): components · Common panels, feeds, layout, and upload controls. · `frontend/src/components`
- [API Client](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/frontend/src/services/api.ts): service layer · Browser boundary for backend calls. · `frontend/src/services/api.ts`
- [UI State](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/frontend/src/hooks/usePersistedState.ts): persisted state · Saved dashboard state and thresholds. · `frontend/src/hooks/usePersistedState.ts`

### Backend

Python detection, discovery, and legal-response engine.

- [API Service](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/api/main.py): Flask entrypoint · Main HTTP service and realtime control plane. · `backend/api/main.py`
- [Discovery](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/discovery_engine.py): candidate acquisition · Finds and downloads suspected content from sources. · `backend/engines/discovery_engine.py`
- [Web Scan](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/web_scanner.py): source scanner · Crawls web sources for candidate media. · `backend/engines/web_scanner.py`
- [Downloader](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/video_downloader.py): media fetch · Retrieves candidate video assets for analysis. · `backend/engines/video_downloader.py`
- [Video Hashing](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/hash_engine.py): video fingerprints · Generates visual fingerprints for protected media. · `backend/engines/hash_engine.py`
- [Audio Signatures](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/audio_engine.py): audio fingerprints · Builds audio-based signatures for matching. · `backend/engines/audio_engine.py`
- [Matcher](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/matcher.py): comparison engine · Compares candidates against stored fingerprints. · `backend/engines/matcher.py`
- [Decision Fusion](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/dual_engine.py): scoring engine · Combines video and audio results into confidence. · `backend/engines/dual_engine.py`
- [AI Layer](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/engines/ai_engine.py): narrative intelligence · Produces summaries, reasoning, or recommendations. · `backend/engines/ai_engine.py`
- [DMCA Generator](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/generators/dmca_generator.py): legal document gen · Turns evidence into formal notices and artifacts. · `backend/generators/dmca_generator.py`

### Data/Artifacts

Persistent store and generated evidence artifacts.

- [SQLite DB](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/sentinel.db): persistent store · Local durable repository state. · `sentinel.db`
- [Redis Cache](https://github.com/rockeyyabraham/15_rrr_acmnexus26/blob/main/backend/utils/redis_utils.py): transient state · Fast cache and async coordination layer. · `backend/utils/redis_utils.py`
- [Notices](https://github.com/rockeyyabraham/15_rrr_acmnexus26/tree/main/backend/notices): generated PDFs · Stored DMCA notice outputs. · `backend/notices`

## Connections

- UI App → Workflow Pages: renders · App routes operators through workflow screens.
- UI App → Shared UI: composes · Pages are built from shared dashboard components.
- Workflow Pages → API Client: calls · Pages request backend data and actions.
- API Client → API Service: HTTP · Client talks to the Flask service.
- Workflow Pages → UI State: persists · UI remembers operator state and thresholds.
- API Service → Discovery: orchestrates · Service coordinates candidate acquisition workflows.
- API Service → Video Hashing: uses · API triggers media fingerprinting.
- API Service → Audio Signatures: uses · API triggers audio signature generation.
- API Service → Matcher: uses · API requests candidate-to-fingerprint comparisons.
- API Service → Decision Fusion: scores · API exposes combined confidence decisions.
- API Service → AI Layer: annotates · AI layer supports summaries and reasoning.
- API Service → DMCA Generator: generates · Backend produces enforcement documents.
- Discovery → Web Scan: scans · Discovery searches sources for candidates.
- Discovery → Downloader: fetches · Discovery retrieves media for analysis.
- Video Hashing → SQLite DB: stores · Video fingerprints are persisted with system state.
- Audio Signatures → SQLite DB: stores · Audio signatures are persisted with system state.
- Matcher → SQLite DB: reads · Matcher compares against stored fingerprints.
- Decision Fusion → Redis Cache: caches · Scoring can use fast shared state.
- DMCA Generator → Notices: writes · Generated notices are saved as PDFs.
- API Service → Redis Cache: coordinates · Service uses Redis for transient coordination.
- API Service → SQLite DB: persists · Service stores durable detections and workflow state.
- Discovery → Matcher: feeds · Candidate acquisition feeds comparison pipeline.
- Matcher → Decision Fusion: outputs · Match results are combined into final confidence.
- Decision Fusion → API Client: returns · Scored results surface back to the dashboard.
- DMCA Generator → API Client: exposes · Generated legal artifacts are surfaced to users.
