How rockeyyabraham/15_rrr_acmnexus26 works
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: main.py API Service · discovery_engine.py Discovery · matcher.py Matcher · dual_engine.py Decision Fusion
Components 18
Frontend
React dashboard and operator workflows.
- UI App · Browser dashboard entry and routing.
frontend/src/App.tsx - Workflow Pages · Ingest, detection, evidence, and legal screens.
frontend/src/pages - Shared UI · Common panels, feeds, layout, and upload controls.
frontend/src/components - API Client · Browser boundary for backend calls.
frontend/src/services/api.ts - UI State · Saved dashboard state and thresholds.
frontend/src/hooks/usePersistedState.ts
Backend
Python detection, discovery, and legal-response engine.
- API Service · Main HTTP service and realtime control plane.
backend/api/main.py - Discovery · Finds and downloads suspected content from sources.
backend/engines/discovery_engine.py - Web Scan · Crawls web sources for candidate media.
backend/engines/web_scanner.py - Downloader · Retrieves candidate video assets for analysis.
backend/engines/video_downloader.py - Video Hashing · Generates visual fingerprints for protected media.
backend/engines/hash_engine.py - Audio Signatures · Builds audio-based signatures for matching.
backend/engines/audio_engine.py - Matcher · Compares candidates against stored fingerprints.
backend/engines/matcher.py - Decision Fusion · Combines video and audio results into confidence.
backend/engines/dual_engine.py - AI Layer · Produces summaries, reasoning, or recommendations.
backend/engines/ai_engine.py - DMCA Generator · Turns evidence into formal notices and artifacts.
backend/generators/dmca_generator.py
Data/Artifacts
Persistent store and generated evidence artifacts.
- SQLite DB · Local durable repository state.
sentinel.db - Redis Cache · Fast cache and async coordination layer.
backend/utils/redis_utils.py - Notices · Stored DMCA notice outputs.
backend/notices
Connections 25
- 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.