# yonko-sid/indelible architecture

> Architecture diagram of the GitHub repository yonko-sid/indelible, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yonko-sid/indelible
- Repository: https://github.com/yonko-sid/indelible

## Overview

#### Purpose and Entry Points
INDELIBLE is a cross-platform digital-rights forensics system: it watermark-protects creator media, verifies suspected copies, monitors for piracy, and drafts enforcement material. The user-facing client starts at `lib/main.dart` and composes the Flutter application in `lib/src/app.dart`. The service boundary is the FastAPI application in `backend/main.py`, deployed as a Dockerized Python service via `backend/Dockerfile`.

#### Client Application
Flutter targets Android, iOS, desktop, and web. Authentication and API access are isolated behind `lib/src/services/auth_service.dart` and `lib/src/services/api_service.dart`; Firebase configuration is generated in `lib/firebase_options.dart`. App screens expose the core workflows—protect, verify, archive/activity, dashboard, and settings—through `lib/src/screens/protect_screen.dart`, `lib/src/screens/verify_screen.dart`, and `lib/src/screens/dashboard_screen.dart`.

#### HTTP Workflow Boundary
`backend/main.py` owns multipart upload handling, user-scoped alert retrieval, suspect-URL scanning, and protected-file download endpoints. The Flutter client submits files and form data to this API rather than performing DSP locally. Processed media is retained and served from `backend/outputs`; metadata/registries are file-backed, including `backend/creator_registry.json` and `backend/blockchain_registry.json`.

#### Protection and Proof Pipeline
Protection orchestrates signed payload construction, robust watermark embedding, creator registration, and chain-of-custody recording. `backend/core/payload.py` creates creator-fingerprint/timestamp/HMAC payloads with Reed-Solomon recovery encoding. `backend/core/watermark.py` applies/extracts the image watermark through Y-channel Haar DWT, LL-band redundant QIM, and robust verification search. `backend/core/core_engine.py` is the likely coordination layer between media processing, registries, and verification results.

#### Media and Video Processing
The image watermark engine is the central forensic primitive in `backend/core/watermark.py`. Video support is separated in `backend/core/video_processor.py`, using FFmpeg to extract and reassemble frames, keeping video transport/encoding concerns outside the DSP algorithm. Output artifacts and `.meta` sidecars represent the protected-media delivery boundary under `backend/outputs`.

#### Detection, Monitoring, and Enforcement
Known protected works are indexed with perceptual hashes in a BK-tree (`backend/core/bktree_index.py`) to cheaply filter candidate matches before cryptographic extraction. The background watchdog in `backend/core/monitoring_daemon.py` invokes web acquisition in `backend/core/scraper.py`, then applies similarity and watermark proof stages. `backend/core/ai_engine.py` integrates Google Gemini 2.5 Flash for piracy analysis and DMCA draft generation; this requires a Gemini API key external to source control.

#### Identity, Storage, and Infrastructure
Firebase Auth supplies client identity; Firebase storage integration is represented by `backend/storage/firebase.py`, while `backend/storage/file_manager.py` handles local file operations. Creator fingerprints deterministically map Firebase UIDs to registry records. Blockchain anchoring is abstracted in `backend/core/blockchain.py` and persisted in `backend/blockchain_registry.json`; README identifies Polygon as the intended immutable anchor. Runtime dependencies include Python 3.10+, FastAPI/Uvicorn, OpenCV/PyWavelets/NumPy, FFmpeg, and Docker/Railway-compatible deployment.

Main entry points: [`backend/core/core_engine.py`](https://github.com/yonko-sid/indelible/blob/main/backend/core/core_engine.py) (Forensic coordinator), [`backend/main.py`](https://github.com/yonko-sid/indelible/blob/main/backend/main.py) (FastAPI application), [`backend/core/monitoring_daemon.py`](https://github.com/yonko-sid/indelible/blob/main/backend/core/monitoring_daemon.py) (Monitoring daemon), [`lib/src/screens/protect_screen.dart`](https://github.com/yonko-sid/indelible/blob/main/lib/src/screens/protect_screen.dart) (Core workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter Client"]
  node_flutter_entry["Flutter entry<br/>Flutter bootstrap<br/>[main.dart]"]
  node_flutter_app["App composition<br/>Flutter app<br/>[app.dart]"]
  node_screens["Core workflows<br/>protect, verify, dashboard screens"]
  node_auth_service["Auth service<br/>Firebase auth client<br/>[auth_service.dart]"]
  node_api_service["API service<br/>HTTP client<br/>[api_service.dart]"]
  node_firebase_config["Firebase config<br/>generated client config"]
end

subgraph group_api["Backend Service"]
  node_backend_api["FastAPI application<br/>HTTP boundary<br/>[main.py]"]
end

subgraph group_forensics["Forensics Pipeline"]
  node_core_engine["Forensic coordinator<br/>pipeline orchestration<br/>[core_engine.py]"]
  node_payload["Signed payload<br/>HMAC and Reed-Solomon<br/>[payload.py]"]
  node_watermark{{"Image watermark engine<br/>DWT/QIM forensic DSP<br/>[watermark.py]"}}
  node_video_processor["Video processor<br/>FFmpeg frame pipeline<br/>[video_processor.py]"]
  node_monitoring["Monitoring daemon<br/>background piracy monitor"]
  node_scraper["Web acquisition<br/>suspect-content scraper<br/>[scraper.py]"]
  node_match_index["Similarity index<br/>perceptual hash BK-tree<br/>[bktree_index.py]"]
  node_ai_engine["Piracy analysis &amp; DMCA<br/>Gemini integration<br/>[ai_engine.py]"]
end

subgraph group_data["Storage &amp; Registries"]
  node_outputs[("Protected artifacts<br/>media and .meta sidecars")]
  node_registries[("Creator &amp; blockchain registries<br/>file-backed proof records")]
  node_blockchain{{"Blockchain anchor<br/>immutable proof abstraction<br/>[blockchain.py]"}}
  node_firebase_storage["Firebase storage adapter<br/>remote storage integration<br/>[firebase.py]"]
  node_file_manager["Local file manager<br/>local storage operations<br/>[file_manager.py]"]
end

node_firebase_auth(("Firebase Auth<br/>external identity provider"))
node_gemini(("Gemini 2.5 Flash<br/>external AI service"))

node_flutter_entry -->|"starts"| node_flutter_app
node_flutter_app -->|"renders"| node_screens
node_screens -->|"authenticates through"| node_auth_service
node_screens -->|"submits workflows"| node_api_service
node_auth_service -->|"uses"| node_firebase_config
node_auth_service -->|"authenticates with"| node_firebase_auth
node_api_service -->|"multipart and API requests"| node_backend_api
node_backend_api -->|"protects and verifies"| node_core_engine
node_core_engine -->|"constructs proof payload"| node_payload
node_core_engine -->|"embeds or extracts"| node_watermark
node_core_engine -->|"processes video"| node_video_processor
node_video_processor -->|"watermarks frames"| node_watermark
node_core_engine -->|"writes protected artifacts"| node_outputs
node_core_engine -->|"records creators and custody"| node_registries
node_core_engine -->|"anchors proof"| node_blockchain
node_blockchain -->|"persists anchor records"| node_registries
node_backend_api -->|"accepts suspect scans"| node_monitoring
node_monitoring -->|"acquires web media"| node_scraper
node_monitoring -->|"filters candidates"| node_match_index
node_match_index -->|"candidate proof extraction"| node_watermark
node_monitoring -->|"sends piracy evidence"| node_ai_engine
node_ai_engine -->|"analyzes and drafts"| node_gemini
node_backend_api -.->|"uses remote storage"| node_firebase_storage
node_backend_api -->|"manages local files"| node_file_manager

click node_flutter_entry "https://github.com/yonko-sid/indelible/blob/main/lib/main.dart"
click node_flutter_app "https://github.com/yonko-sid/indelible/blob/main/lib/src/app.dart"
click node_screens "https://github.com/yonko-sid/indelible/blob/main/lib/src/screens/protect_screen.dart"
click node_auth_service "https://github.com/yonko-sid/indelible/blob/main/lib/src/services/auth_service.dart"
click node_api_service "https://github.com/yonko-sid/indelible/blob/main/lib/src/services/api_service.dart"
click node_firebase_config "https://github.com/yonko-sid/indelible/blob/main/lib/firebase_options.dart"
click node_backend_api "https://github.com/yonko-sid/indelible/blob/main/backend/main.py"
click node_core_engine "https://github.com/yonko-sid/indelible/blob/main/backend/core/core_engine.py"
click node_payload "https://github.com/yonko-sid/indelible/blob/main/backend/core/payload.py"
click node_watermark "https://github.com/yonko-sid/indelible/blob/main/backend/core/watermark.py"
click node_video_processor "https://github.com/yonko-sid/indelible/blob/main/backend/core/video_processor.py"
click node_monitoring "https://github.com/yonko-sid/indelible/blob/main/backend/core/monitoring_daemon.py"
click node_scraper "https://github.com/yonko-sid/indelible/blob/main/backend/core/scraper.py"
click node_match_index "https://github.com/yonko-sid/indelible/blob/main/backend/core/bktree_index.py"
click node_ai_engine "https://github.com/yonko-sid/indelible/blob/main/backend/core/ai_engine.py"
click node_outputs "https://github.com/yonko-sid/indelible/tree/main/backend/outputs"
click node_registries "https://github.com/yonko-sid/indelible/blob/main/backend/creator_registry.json"
click node_blockchain "https://github.com/yonko-sid/indelible/blob/main/backend/core/blockchain.py"
click node_firebase_storage "https://github.com/yonko-sid/indelible/blob/main/backend/storage/firebase.py"
click node_file_manager "https://github.com/yonko-sid/indelible/blob/main/backend/storage/file_manager.py"

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_flutter_entry,node_flutter_app,node_screens,node_auth_service,node_api_service,node_firebase_config toneBlue
class node_backend_api toneAmber
class node_core_engine,node_payload,node_watermark,node_video_processor,node_monitoring,node_scraper,node_match_index,node_ai_engine toneMint
class node_outputs,node_registries,node_blockchain,node_firebase_storage,node_file_manager toneRose
class node_firebase_auth,node_gemini toneNeutral
```

## Components

### Flutter Client

- [Flutter entry](https://github.com/yonko-sid/indelible/blob/main/lib/main.dart): Flutter bootstrap · `lib/main.dart`
- [App composition](https://github.com/yonko-sid/indelible/blob/main/lib/src/app.dart): Flutter app · `lib/src/app.dart`
- [Core workflows](https://github.com/yonko-sid/indelible/blob/main/lib/src/screens/protect_screen.dart): protect, verify, dashboard screens · Protect, verification, activity, and dashboard user flows. · `lib/src/screens/protect_screen.dart`
- [Auth service](https://github.com/yonko-sid/indelible/blob/main/lib/src/services/auth_service.dart): Firebase auth client · `lib/src/services/auth_service.dart`
- [API service](https://github.com/yonko-sid/indelible/blob/main/lib/src/services/api_service.dart): HTTP client · `lib/src/services/api_service.dart`
- [Firebase config](https://github.com/yonko-sid/indelible/blob/main/lib/firebase_options.dart): generated client config · `lib/firebase_options.dart`

### Backend Service

- [FastAPI application](https://github.com/yonko-sid/indelible/blob/main/backend/main.py): HTTP boundary · Handles uploads, alerts, suspect URLs, and protected downloads. · `backend/main.py`

### Forensics Pipeline

- [Forensic coordinator](https://github.com/yonko-sid/indelible/blob/main/backend/core/core_engine.py): pipeline orchestration · `backend/core/core_engine.py`
- [Signed payload](https://github.com/yonko-sid/indelible/blob/main/backend/core/payload.py): HMAC and Reed-Solomon · Builds recoverable creator, timestamp, and signature payloads. · `backend/core/payload.py`
- [Image watermark engine](https://github.com/yonko-sid/indelible/blob/main/backend/core/watermark.py): DWT/QIM forensic DSP · Embeds, extracts, and robustly verifies image watermarks. · `backend/core/watermark.py`
- [Video processor](https://github.com/yonko-sid/indelible/blob/main/backend/core/video_processor.py): FFmpeg frame pipeline · `backend/core/video_processor.py`
- [Monitoring daemon](https://github.com/yonko-sid/indelible/blob/main/backend/core/monitoring_daemon.py): background piracy monitor · `backend/core/monitoring_daemon.py`
- [Web acquisition](https://github.com/yonko-sid/indelible/blob/main/backend/core/scraper.py): suspect-content scraper · `backend/core/scraper.py`
- [Similarity index](https://github.com/yonko-sid/indelible/blob/main/backend/core/bktree_index.py): perceptual hash BK-tree · Filters candidate works before cryptographic proof. · `backend/core/bktree_index.py`
- [Piracy analysis & DMCA](https://github.com/yonko-sid/indelible/blob/main/backend/core/ai_engine.py): Gemini integration · Analyzes piracy candidates and drafts enforcement material. · `backend/core/ai_engine.py`

### Storage & Registries

- [Protected artifacts](https://github.com/yonko-sid/indelible/tree/main/backend/outputs): media and .meta sidecars · Delivery boundary for processed media and metadata. · `backend/outputs`
- [Creator & blockchain registries](https://github.com/yonko-sid/indelible/blob/main/backend/creator_registry.json): file-backed proof records · `backend/creator_registry.json`
- [Blockchain anchor](https://github.com/yonko-sid/indelible/blob/main/backend/core/blockchain.py): immutable proof abstraction · Intended to anchor proof records on Polygon. · `backend/core/blockchain.py`
- [Firebase storage adapter](https://github.com/yonko-sid/indelible/blob/main/backend/storage/firebase.py): remote storage integration · `backend/storage/firebase.py`
- [Local file manager](https://github.com/yonko-sid/indelible/blob/main/backend/storage/file_manager.py): local storage operations · `backend/storage/file_manager.py`

### Other components

- **Firebase Auth**: external identity provider
- **Gemini 2.5 Flash**: external AI service · Requires an externally supplied Gemini API key.

## Connections

- Flutter entry → App composition: starts
- App composition → Core workflows: renders
- Core workflows → Auth service: authenticates through
- Core workflows → API service: submits workflows
- Auth service → Firebase config: uses
- Auth service → Firebase Auth: authenticates with
- API service → FastAPI application: multipart and API requests
- FastAPI application → Forensic coordinator: protects and verifies
- Forensic coordinator → Signed payload: constructs proof payload
- Forensic coordinator → Image watermark engine: embeds or extracts
- Forensic coordinator → Video processor: processes video
- Video processor → Image watermark engine: watermarks frames
- Forensic coordinator → Protected artifacts: writes protected artifacts
- Forensic coordinator → Creator & blockchain registries: records creators and custody
- Forensic coordinator → Blockchain anchor: anchors proof
- Blockchain anchor → Creator & blockchain registries: persists anchor records
- FastAPI application → Monitoring daemon: accepts suspect scans
- Monitoring daemon → Web acquisition: acquires web media
- Monitoring daemon → Similarity index: filters candidates
- Similarity index → Image watermark engine: candidate proof extraction
- Monitoring daemon → Piracy analysis & DMCA: sends piracy evidence
- Piracy analysis & DMCA → Gemini 2.5 Flash: analyzes and drafts
- FastAPI application → Firebase storage adapter: uses remote storage
- FastAPI application → Local file manager: manages local files