# varungandhi29/mediagrab_ai architecture

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

- Interactive diagram: https://gitdiagram.com/varungandhi29/mediagrab_ai
- Repository: https://github.com/varungandhi29/mediagrab_ai

## Overview

MediaGrab AI accepts a media URL, streams extraction progress and metadata, lets the user choose an available format, then prepares a playable/downloadable file and reports job progress. The README documents four extraction tiers, audio conversion, security controls, AI recommendations, and session history; sampled source confirms the metadata, preparation, storage, and UI paths. Resilience, system feedback, and some API wiring are represented at the documented subsystem level because their implementation was not fully sampled.

Main entry points: [`backend/app/api/routes_stream.py`](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_stream.py) (Media stream routes), [`frontend/src/services/api.js`](https://github.com/varungandhi29/mediagrab_ai/blob/main/frontend/src/services/api.js) (API client), [`frontend/src/App.jsx`](https://github.com/varungandhi29/mediagrab_ai/blob/main/frontend/src/App.jsx) (Download interface), [`backend/app/api/routes_metadata.py`](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_metadata.py) (Metadata routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web Client"]
  node_app["Download interface<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_history[("Session history<br/>[storage.js]")]
end

subgraph group_api["API Surface"]
  node_metadata_api["Metadata routes<br/>[routes_metadata.py]"]
  node_stream_api["Media stream routes<br/>[routes_stream.py]"]
  node_ai_api["AI routes<br/>[routes_ai.py]"]
  node_system_api["System routes<br/>[routes_system.py]"]
  node_server["Application server<br/>[main.py]"]
end

subgraph group_media["Media Processing"]
  node_extractor["Tiered extractor<br/>[extractor.py]"]
  node_browser["Headless browser"]
  node_pipeline["Media preparation<br/>[media_pipeline.py]"]
  node_normalizer["Media normalizer"]
  node_storage[("Ephemeral media store<br/>[storage_manager.py]")]
  node_ai["AI assistant<br/>[ai_assistant.py]"]
end

subgraph group_security["Security Controls"]
  node_ssrf["SSRF validation<br/>[ssrf_validator.py]"]
  node_sandbox["Subprocess sandbox<br/>[sandbox.py]"]
  node_rate_limit["Rate limiting<br/>[rate_limiter.py]"]
end

subgraph group_operations["Operations &amp; Resilience"]
  node_feedback[("Feedback analytics")]
  node_link_check["Link pre-check<br/>[link_checker.py]"]
  node_resilience["Resilience services"]
  node_alerts["Operator alerts<br/>[alert_manager.py]"]
end

node_user(("Media user"))
node_gemini{{"Gemini service"}}
node_webhook{{"Alert webhook"}}

node_user -->|"submits URL"| node_app
node_app -->|"requests metadata"| node_api_client
node_api_client -->|"calls metadata API"| node_metadata_api
node_metadata_api -->|"extracts metadata"| node_extractor
node_extractor -->|"renders tier four"| node_browser
node_metadata_api -->|"records attempts"| node_feedback
node_app -->|"requests recommendation"| node_api_client
node_api_client -->|"calls AI API"| node_ai_api
node_ai_api -->|"requests guidance"| node_ai
node_ai -.->|"uses when configured"| node_gemini
node_app -->|"starts preparation"| node_api_client
node_api_client -->|"calls prepare route"| node_stream_api
node_stream_api -->|"creates preparation job"| node_pipeline
node_pipeline -->|"runs isolated extractor"| node_sandbox
node_pipeline -->|"normalizes media"| node_normalizer
node_pipeline -->|"registers finished file"| node_storage
node_stream_api -->|"reads SSE progress"| node_pipeline
node_stream_api -->|"reads download token"| node_storage
node_app -->|"saves completed item"| node_history
node_metadata_api -->|"validates submitted URL"| node_ssrf
node_stream_api -->|"validates proxied URL"| node_ssrf
node_metadata_api -->|"checks request limit"| node_rate_limit
node_stream_api -->|"checks download limit"| node_rate_limit
node_system_api -->|"checks pasted link"| node_link_check
node_system_api -->|"reads metrics and stores reports"| node_feedback
node_server -->|"starts background monitors"| node_resilience
node_resilience -->|"evaluates failures"| node_alerts
node_alerts -.->|"dispatches alert"| node_webhook

click node_app "https://github.com/varungandhi29/mediagrab_ai/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/varungandhi29/mediagrab_ai/blob/main/frontend/src/services/api.js"
click node_history "https://github.com/varungandhi29/mediagrab_ai/blob/main/frontend/src/utils/storage.js"
click node_metadata_api "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_metadata.py"
click node_stream_api "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_stream.py"
click node_ai_api "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_ai.py"
click node_system_api "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_system.py"
click node_extractor "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/extractor.py"
click node_browser "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/headless_browser.py"
click node_pipeline "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/media_pipeline.py"
click node_normalizer "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/media_normalizer.py"
click node_storage "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/storage_manager.py"
click node_ai "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/ai_assistant.py"
click node_ssrf "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/security/ssrf_validator.py"
click node_sandbox "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/security/sandbox.py"
click node_rate_limit "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/security/rate_limiter.py"
click node_feedback "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/feedback_manager.py"
click node_link_check "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/link_checker.py"
click node_resilience "https://github.com/varungandhi29/mediagrab_ai/tree/main/backend/app/resilience"
click node_alerts "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/resilience/alert_manager.py"
click node_server "https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/main.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_app,node_api_client,node_history,node_user toneBlue
class node_metadata_api,node_stream_api,node_ai_api,node_system_api,node_server toneAmber
class node_extractor,node_browser,node_pipeline,node_normalizer,node_storage,node_ai,node_webhook toneMint
class node_ssrf,node_sandbox,node_rate_limit toneRose
class node_feedback,node_link_check,node_resilience,node_alerts,node_gemini toneIndigo
```

## Components

### Web Client

- [Download interface](https://github.com/varungandhi29/mediagrab_ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/varungandhi29/mediagrab_ai/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Session history](https://github.com/varungandhi29/mediagrab_ai/blob/main/frontend/src/utils/storage.js): `frontend/src/utils/storage.js`

### API Surface

- [Metadata routes](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_metadata.py): `backend/app/api/routes_metadata.py`
- [Media stream routes](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_stream.py): `backend/app/api/routes_stream.py`
- [AI routes](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_ai.py): `backend/app/api/routes_ai.py`
- [System routes](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/api/routes_system.py): `backend/app/api/routes_system.py`
- [Application server](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/main.py): `backend/app/main.py`

### Media Processing

- [Tiered extractor](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/extractor.py): `backend/app/services/extractor.py`
- [Headless browser](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/headless_browser.py): `backend/app/services/headless_browser.py`
- [Media preparation](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/media_pipeline.py): `backend/app/services/media_pipeline.py`
- [Media normalizer](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/media_normalizer.py): `backend/app/services/media_normalizer.py`
- [Ephemeral media store](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/storage_manager.py): `backend/app/services/storage_manager.py`
- [AI assistant](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/ai_assistant.py): `backend/app/services/ai_assistant.py`

### Security Controls

- [SSRF validation](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/security/ssrf_validator.py): `backend/app/security/ssrf_validator.py`
- [Subprocess sandbox](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/security/sandbox.py): `backend/app/security/sandbox.py`
- [Rate limiting](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/security/rate_limiter.py): `backend/app/security/rate_limiter.py`

### Operations & Resilience

- [Feedback analytics](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/feedback_manager.py): `backend/app/services/feedback_manager.py`
- [Link pre-check](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/services/link_checker.py): `backend/app/services/link_checker.py`
- [Resilience services](https://github.com/varungandhi29/mediagrab_ai/tree/main/backend/app/resilience): `backend/app/resilience`
- [Operator alerts](https://github.com/varungandhi29/mediagrab_ai/blob/main/backend/app/resilience/alert_manager.py): `backend/app/resilience/alert_manager.py`

### Other components

- **Media user**
- **Gemini service**
- **Alert webhook**

## Connections

- Media user → Download interface: submits URL
- Download interface → API client: requests metadata
- API client → Metadata routes: calls metadata API
- Metadata routes → Tiered extractor: extracts metadata
- Tiered extractor → Headless browser: renders tier four
- Metadata routes → Feedback analytics: records attempts
- Download interface → API client: requests recommendation
- API client → AI routes: calls AI API
- AI routes → AI assistant: requests guidance
- AI assistant → Gemini service: uses when configured
- Download interface → API client: starts preparation
- API client → Media stream routes: calls prepare route
- Media stream routes → Media preparation: creates preparation job
- Media preparation → Subprocess sandbox: runs isolated extractor
- Media preparation → Media normalizer: normalizes media
- Media preparation → Ephemeral media store: registers finished file
- Media stream routes → Media preparation: reads SSE progress
- Media stream routes → Ephemeral media store: reads download token
- Download interface → Session history: saves completed item
- Metadata routes → SSRF validation: validates submitted URL
- Media stream routes → SSRF validation: validates proxied URL
- Metadata routes → Rate limiting: checks request limit
- Media stream routes → Rate limiting: checks download limit
- System routes → Link pre-check: checks pasted link
- System routes → Feedback analytics: reads metrics and stores reports
- Application server → Resilience services: starts background monitors
- Resilience services → Operator alerts: evaluates failures
- Operator alerts → Alert webhook: dispatches alert