# pulkitpareek18/intellimix architecture

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

- Interactive diagram: https://gitdiagram.com/pulkitpareek18/intellimix
- Repository: https://github.com/pulkitpareek18/intellimix

## Overview

IntelliMix is an AI-first music-mixing studio. Its main workflow runs from an authenticated user’s chat request, through draft planning and revision, to timeline editing and asynchronous mix rendering; the UI then presents versions and run status. The graph also includes documented history, downloads, and media-processing tools. Relationships come from the excerpts, SOURCE INDEX references, and README; some database and storage details are documented only at the architecture level, and unsampled implementation specifics are not inferred.

Main entry points: [`backend/app.py`](https://github.com/pulkitpareek18/intellimix/blob/main/backend/app.py) (Flask API), [`backend/mix_chat_runner.py`](https://github.com/pulkitpareek18/intellimix/blob/main/backend/mix_chat_runner.py) (Run orchestrator), [`frontend/src/App.tsx`](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/App.tsx) (Web application), [`frontend/src/utils/api.ts`](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/utils/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Web application<br/>[App.tsx]"]
  node_auth["Authentication UI<br/>[AuthContext.tsx]"]
  node_chatui["Mix chat studio<br/>[AIParody.tsx]"]
  node_timeline["Timeline editor"]
  node_historyui["History screen<br/>[History.tsx]"]
  node_toolui["Audio tool screens<br/>[YouTubeTrimmer.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and runs"]
  node_flask["Flask API<br/>[app.py]"]
  node_runner["Run orchestrator<br/>[mix_chat_runner.py]"]
  node_queue["Run queue<br/>[mix_chat_queue.py]"]
  node_worker["Background worker<br/>[mix_chat_worker.py]"]
  node_database[("PostgreSQL")]
  node_redis[("Redis")]
  node_storage[("Media storage")]
end

subgraph group_planning["Mix planning"]
  node_agent["Mix agent flow<br/>[mix_agent_flow.py]"]
  node_mix_ai["Mix and audio analysis<br/>[ai_main.py]"]
  node_ai_service["Gemini service<br/>[ai.py]"]
  node_prompts["Planning prompts"]
end

subgraph group_media["Media processing"]
  node_audio_tools["Audio engineering"]
  node_merge["Audio merging<br/>[audio_merge.py]"]
  node_audio_download["Track downloads<br/>[audio_download.py]"]
  node_video_tools["Video download<br/>[download_video.py]"]
  node_download_tools["Audio download<br/>[download_audio.py]"]
  node_split["Audio splitting<br/>[audio_split.py]"]
  node_csv["CSV processing<br/>[read_csv.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"provides auth"| node_auth
node_web -->|"routes to"| node_chatui
node_web -->|"routes to"| node_historyui
node_web -->|"routes to"| node_toolui
node_chatui -->|"requests"| node_api_client
node_chatui -->|"opens editor"| node_timeline
node_timeline -->|"requests"| node_api_client
node_historyui -->|"requests"| node_api_client
node_toolui -->|"requests"| node_api_client
node_api_client -->|"REST and SSE"| node_flask
node_flask -->|"orchestrates"| node_runner
node_flask -->|"enqueues runs"| node_queue
node_worker -->|"dequeues runs"| node_queue
node_worker -->|"executes runs"| node_runner
node_runner -->|"plans mixes"| node_agent
node_runner -->|"uses analysis"| node_mix_ai
node_runner -->|"uses AI"| node_ai_service
node_runner -->|"uses prompts"| node_prompts
node_agent -->|"uses analysis"| node_mix_ai
node_agent -->|"engineers audio"| node_audio_tools
node_audio_tools -->|"analyzes tracks"| node_mix_ai
node_audio_tools -->|"downloads tracks"| node_audio_download
node_audio_tools -->|"uses merging"| node_merge
node_flask -->|"reads and writes"| node_database
node_flask -->|"serves files"| node_storage
node_queue -->|"queues runs"| node_redis
node_worker -->|"updates runs"| node_database
node_worker -->|"stores output"| node_storage
node_flask -->|"routes downloads"| node_video_tools
node_flask -->|"routes downloads"| node_download_tools
node_flask -->|"routes processing"| node_split
node_flask -->|"routes processing"| node_csv

click node_web "https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/App.tsx"
click node_auth "https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/context/AuthContext.tsx"
click node_chatui "https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/pages/AIParody.tsx"
click node_timeline "https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/components/TimelineEditorPanel.tsx"
click node_historyui "https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/pages/History.tsx"
click node_toolui "https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/pages/YouTubeTrimmer.tsx"
click node_api_client "https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/utils/api.ts"
click node_flask "https://github.com/pulkitpareek18/intellimix/blob/main/backend/app.py"
click node_runner "https://github.com/pulkitpareek18/intellimix/blob/main/backend/mix_chat_runner.py"
click node_queue "https://github.com/pulkitpareek18/intellimix/blob/main/backend/mix_chat_queue.py"
click node_worker "https://github.com/pulkitpareek18/intellimix/blob/main/backend/mix_chat_worker.py"
click node_agent "https://github.com/pulkitpareek18/intellimix/blob/main/backend/ai/mix_agent_flow.py"
click node_mix_ai "https://github.com/pulkitpareek18/intellimix/blob/main/backend/ai/ai_main.py"
click node_ai_service "https://github.com/pulkitpareek18/intellimix/blob/main/backend/ai/ai.py"
click node_prompts "https://github.com/pulkitpareek18/intellimix/blob/main/backend/ai/planning_prompts.py"
click node_audio_tools "https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/audio_engineer_tools.py"
click node_merge "https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/audio_merge.py"
click node_audio_download "https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/audio_download.py"
click node_video_tools "https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/download_video.py"
click node_download_tools "https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/download_audio.py"
click node_split "https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/audio_split.py"
click node_csv "https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/read_csv.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_web,node_auth,node_chatui,node_timeline,node_historyui,node_toolui,node_api_client,node_user toneBlue
class node_flask,node_runner,node_queue,node_worker,node_database,node_redis,node_storage toneAmber
class node_agent,node_mix_ai,node_ai_service,node_prompts toneMint
class node_audio_tools,node_merge,node_audio_download,node_video_tools,node_download_tools,node_split,node_csv toneRose
```

## Components

### Web client

- [Web application](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Authentication UI](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Mix chat studio](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/pages/AIParody.tsx): `frontend/src/pages/AIParody.tsx`
- [Timeline editor](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/components/TimelineEditorPanel.tsx): `frontend/src/components/TimelineEditorPanel.tsx`
- [History screen](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/pages/History.tsx): `frontend/src/pages/History.tsx`
- [Audio tool screens](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/pages/YouTubeTrimmer.tsx): `frontend/src/pages/YouTubeTrimmer.tsx`
- [API client](https://github.com/pulkitpareek18/intellimix/blob/main/frontend/src/utils/api.ts): `frontend/src/utils/api.ts`

### API and runs

- [Flask API](https://github.com/pulkitpareek18/intellimix/blob/main/backend/app.py): `backend/app.py`
- [Run orchestrator](https://github.com/pulkitpareek18/intellimix/blob/main/backend/mix_chat_runner.py): `backend/mix_chat_runner.py`
- [Run queue](https://github.com/pulkitpareek18/intellimix/blob/main/backend/mix_chat_queue.py): `backend/mix_chat_queue.py`
- [Background worker](https://github.com/pulkitpareek18/intellimix/blob/main/backend/mix_chat_worker.py): `backend/mix_chat_worker.py`
- **PostgreSQL**
- **Redis**
- **Media storage**

### Mix planning

- [Mix agent flow](https://github.com/pulkitpareek18/intellimix/blob/main/backend/ai/mix_agent_flow.py): `backend/ai/mix_agent_flow.py`
- [Mix and audio analysis](https://github.com/pulkitpareek18/intellimix/blob/main/backend/ai/ai_main.py): `backend/ai/ai_main.py`
- [Gemini service](https://github.com/pulkitpareek18/intellimix/blob/main/backend/ai/ai.py): `backend/ai/ai.py`
- [Planning prompts](https://github.com/pulkitpareek18/intellimix/blob/main/backend/ai/planning_prompts.py): `backend/ai/planning_prompts.py`

### Media processing

- [Audio engineering](https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/audio_engineer_tools.py): `backend/features/audio_engineer_tools.py`
- [Audio merging](https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/audio_merge.py): `backend/features/audio_merge.py`
- [Track downloads](https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/audio_download.py): `backend/features/audio_download.py`
- [Video download](https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/download_video.py): `backend/features/download_video.py`
- [Audio download](https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/download_audio.py): `backend/features/download_audio.py`
- [Audio splitting](https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/audio_split.py): `backend/features/audio_split.py`
- [CSV processing](https://github.com/pulkitpareek18/intellimix/blob/main/backend/features/read_csv.py): `backend/features/read_csv.py`

### Other components

- **User**

## Connections

- User → Web application: uses
- Web application → Authentication UI: provides auth (evidence: `frontend/src/App.tsx`)
- Web application → Mix chat studio: routes to (evidence: `frontend/src/App.tsx`)
- Web application → History screen: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Audio tool screens: routes to (evidence: `frontend/src/App.tsx`)
- Mix chat studio → API client: requests (evidence: `frontend/src/pages/AIParody.tsx`)
- Mix chat studio → Timeline editor: opens editor (evidence: `frontend/src/pages/AIParody.tsx`)
- Timeline editor → API client: requests (evidence: `frontend/src/components/TimelineEditorPanel.tsx`)
- History screen → API client: requests (evidence: `frontend/src/pages/History.tsx`)
- Audio tool screens → API client: requests (evidence: `frontend/src/pages/YouTubeTrimmer.tsx`)
- API client → Flask API: REST and SSE
- Flask API → Run orchestrator: orchestrates (evidence: `backend/app.py`)
- Flask API → Run queue: enqueues runs (evidence: `backend/app.py`)
- Background worker → Run queue: dequeues runs (evidence: `backend/mix_chat_worker.py`)
- Background worker → Run orchestrator: executes runs (evidence: `backend/mix_chat_worker.py`)
- Run orchestrator → Mix agent flow: plans mixes (evidence: `backend/mix_chat_runner.py`)
- Run orchestrator → Mix and audio analysis: uses analysis (evidence: `backend/mix_chat_runner.py`)
- Run orchestrator → Gemini service: uses AI (evidence: `backend/mix_chat_runner.py`)
- Run orchestrator → Planning prompts: uses prompts (evidence: `backend/mix_chat_runner.py`)
- Mix agent flow → Mix and audio analysis: uses analysis (evidence: `backend/ai/mix_agent_flow.py`)
- Mix agent flow → Audio engineering: engineers audio (evidence: `backend/ai/mix_agent_flow.py`)
- Audio engineering → Mix and audio analysis: analyzes tracks (evidence: `backend/features/audio_engineer_tools.py`)
- Audio engineering → Track downloads: downloads tracks (evidence: `backend/features/audio_engineer_tools.py`)
- Audio engineering → Audio merging: uses merging (evidence: `backend/features/audio_engineer_tools.py`)
- Flask API → PostgreSQL: reads and writes
- Flask API → Media storage: serves files
- Run queue → Redis: queues runs
- Background worker → PostgreSQL: updates runs
- Background worker → Media storage: stores output
- Flask API → Video download: routes downloads (evidence: `backend/app.py`)
- Flask API → Audio download: routes downloads (evidence: `backend/app.py`)
- Flask API → Audio splitting: routes processing (evidence: `backend/app.py`)
- Flask API → CSV processing: routes processing (evidence: `backend/app.py`)
