# aishwarya0903/beatmap architecture

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

- Interactive diagram: https://gitdiagram.com/aishwarya0903/beatmap
- Repository: https://github.com/aishwarya0903/beatmap

## Overview

BeatMap turns a creator’s song link or recording and edit-type preset into timestamped music-editing guidance. The main path runs from the frontend analysis dashboard through the API routes into the analyzer, which resolves source metadata, obtains AI analysis, shapes the result, and persists it; the frontend presents cuts, shot plans, and other insights. Separate branches provide multilingual trending tracks, track comparison, and saved-analysis history. The README documents these capabilities; relationships involving unsampled frontend wiring are shown only where documented.

Main entry points: [`frontend/src/components/bm-analyze.tsx`](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/bm-analyze.tsx) (Analysis dashboard), [`backend/app/api/routes.py`](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/api/routes.py) (API routes), [`backend/app/services/orchestration/analyzer.py`](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/orchestration/analyzer.py) (Link and audio analyzer), [`backend/app/main.py`](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Creator interface"]
  node_dashboard["Analysis dashboard<br/>[bm-analyze.tsx]"]
  node_recorder["Audio recorder<br/>[recorder.tsx]"]
  node_result["Analysis results"]
  node_cuts["Cut windows"]
  node_shotplan["Shot plan"]
  node_compareui["Comparison panel<br/>[compare-tracks.tsx]"]
  node_historyui["Recent analyses"]
  node_trendingui["Trending tracks<br/>[bm-trending.tsx]"]
end

subgraph group_api["API and contracts"]
  node_api["FastAPI app<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_schemas["Request and result models<br/>[schemas.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_analysis["Analysis pipeline"]
  node_analyzer["Link and audio analyzer<br/>[analyzer.py]"]
  node_metadata["Platform metadata"]
  node_ai["AI analysis<br/>[client.py]"]
  node_audio["Audio processing<br/>[processor.py]"]
  node_comparison["Track comparison<br/>[compare.py]"]
end

subgraph group_discovery["Music discovery"]
  node_trending["Trending provider<br/>[youtube.py]"]
end

subgraph group_storage["Analysis history"]
  node_db[("SQLite analyses<br/>[db.py]")]
end

node_creator(("Creator"))

node_creator -->|"submits analysis"| node_dashboard
node_dashboard -->|"uses recording"| node_recorder
node_dashboard -->|"opens comparison"| node_compareui
node_dashboard -->|"shows history"| node_historyui
node_dashboard -->|"renders result"| node_result
node_result -->|"renders cuts"| node_cuts
node_result -->|"renders plan"| node_shotplan
node_dashboard -->|"sends requests"| node_api
node_trendingui -->|"requests tracks"| node_api
node_api -->|"registers routes"| node_routes
node_routes -->|"validates requests"| node_schemas
node_routes -->|"dispatches link and audio"| node_analyzer
node_routes -->|"dispatches comparison"| node_comparison
node_routes -->|"fetches tracks"| node_trending
node_routes -->|"reads and deletes history"| node_db
node_analyzer -->|"fetches platform data"| node_metadata
node_analyzer -->|"requests analysis"| node_ai
node_analyzer -->|"processes uploads"| node_audio
node_analyzer -->|"saves results"| node_db
node_comparison -->|"analyzes each link"| node_analyzer
node_api -->|"initializes store"| node_db
node_ai -->|"reads provider keys"| node_settings
node_metadata -->|"reads API config"| node_settings
node_trending -->|"reads API config"| node_settings
node_db -->|"reads database path"| node_settings

click node_dashboard "https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/bm-analyze.tsx"
click node_recorder "https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/recorder.tsx"
click node_result "https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/analysis-result.tsx"
click node_cuts "https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/best-cuts-section.tsx"
click node_shotplan "https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/shot-plan-section.tsx"
click node_compareui "https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/compare-tracks.tsx"
click node_historyui "https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/recent-analyses-section.tsx"
click node_trendingui "https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/bm-trending.tsx"
click node_api "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/main.py"
click node_routes "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/api/routes.py"
click node_schemas "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/api/schemas.py"
click node_analyzer "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/orchestration/analyzer.py"
click node_metadata "https://github.com/aishwarya0903/beatmap/tree/main/backend/app/services/metadata"
click node_ai "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/gemini/client.py"
click node_audio "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/audio/processor.py"
click node_comparison "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/comparison/compare.py"
click node_trending "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/trending/youtube.py"
click node_db "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/persistence/db.py"
click node_settings "https://github.com/aishwarya0903/beatmap/blob/main/backend/app/settings.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_dashboard,node_recorder,node_result,node_cuts,node_shotplan,node_compareui,node_historyui,node_trendingui toneBlue
class node_api,node_routes,node_schemas,node_settings toneAmber
class node_analyzer,node_metadata,node_ai,node_audio,node_comparison toneMint
class node_trending toneRose
class node_db,node_creator toneIndigo
```

## Components

### Creator interface

- [Analysis dashboard](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/bm-analyze.tsx): `frontend/src/components/bm-analyze.tsx`
- [Audio recorder](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/recorder.tsx): `frontend/src/components/recorder.tsx`
- [Analysis results](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/analysis-result.tsx): `frontend/src/components/analysis-result.tsx`
- [Cut windows](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/best-cuts-section.tsx): `frontend/src/components/best-cuts-section.tsx`
- [Shot plan](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/shot-plan-section.tsx): `frontend/src/components/shot-plan-section.tsx`
- [Comparison panel](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/compare-tracks.tsx): `frontend/src/components/compare-tracks.tsx`
- [Recent analyses](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/recent-analyses-section.tsx): `frontend/src/components/recent-analyses-section.tsx`
- [Trending tracks](https://github.com/aishwarya0903/beatmap/blob/main/frontend/src/components/bm-trending.tsx): `frontend/src/components/bm-trending.tsx`

### API and contracts

- [FastAPI app](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Request and result models](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/api/schemas.py): `backend/app/api/schemas.py`
- [Runtime settings](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/settings.py): `backend/app/settings.py`

### Analysis pipeline

- [Link and audio analyzer](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/orchestration/analyzer.py): `backend/app/services/orchestration/analyzer.py`
- [Platform metadata](https://github.com/aishwarya0903/beatmap/tree/main/backend/app/services/metadata): `backend/app/services/metadata`
- [AI analysis](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/gemini/client.py): `backend/app/services/gemini/client.py`
- [Audio processing](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/audio/processor.py): `backend/app/services/audio/processor.py`
- [Track comparison](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/comparison/compare.py): `backend/app/services/comparison/compare.py`

### Music discovery

- [Trending provider](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/trending/youtube.py): `backend/app/services/trending/youtube.py`

### Analysis history

- [SQLite analyses](https://github.com/aishwarya0903/beatmap/blob/main/backend/app/services/persistence/db.py): `backend/app/services/persistence/db.py`

### Other components

- **Creator**

## Connections

- Creator → Analysis dashboard: submits analysis (evidence: `README.md`)
- Analysis dashboard → Audio recorder: uses recording (evidence: `frontend/src/components/bm-analyze.tsx`)
- Analysis dashboard → Comparison panel: opens comparison (evidence: `frontend/src/components/bm-analyze.tsx`)
- Analysis dashboard → Recent analyses: shows history (evidence: `frontend/src/components/bm-analyze.tsx`)
- Analysis dashboard → Analysis results: renders result (evidence: `frontend/src/components/bm-analyze.tsx`)
- Analysis results → Cut windows: renders cuts (evidence: `frontend/src/components/analysis-result.tsx`)
- Analysis results → Shot plan: renders plan (evidence: `frontend/src/components/analysis-result.tsx`)
- Analysis dashboard → FastAPI app: sends requests (evidence: `README.md`)
- Trending tracks → FastAPI app: requests tracks (evidence: `README.md`)
- FastAPI app → API routes: registers routes (evidence: `backend/app/main.py`)
- API routes → Request and result models: validates requests (evidence: `backend/app/api/routes.py`)
- API routes → Link and audio analyzer: dispatches link and audio (evidence: `backend/app/api/routes.py`)
- API routes → Track comparison: dispatches comparison (evidence: `backend/app/api/routes.py`)
- API routes → Trending provider: fetches tracks (evidence: `backend/app/api/routes.py`)
- API routes → SQLite analyses: reads and deletes history (evidence: `backend/app/api/routes.py`)
- Link and audio analyzer → Platform metadata: fetches platform data (evidence: `backend/app/services/orchestration/analyzer.py`)
- Link and audio analyzer → AI analysis: requests analysis (evidence: `backend/app/services/orchestration/analyzer.py`)
- Link and audio analyzer → Audio processing: processes uploads (evidence: `backend/app/services/orchestration/analyzer.py`)
- Link and audio analyzer → SQLite analyses: saves results (evidence: `backend/app/services/orchestration/analyzer.py`)
- Track comparison → Link and audio analyzer: analyzes each link (evidence: `backend/app/services/comparison/compare.py`)
- FastAPI app → SQLite analyses: initializes store (evidence: `backend/app/main.py`)
- AI analysis → Runtime settings: reads provider keys (evidence: `backend/app/services/gemini/client.py`)
- Platform metadata → Runtime settings: reads API config (evidence: `backend/app/services/metadata/youtube.py`)
- Trending provider → Runtime settings: reads API config (evidence: `backend/app/services/trending/youtube.py`)
- SQLite analyses → Runtime settings: reads database path (evidence: `backend/app/services/persistence/db.py`)
