# tearcake/audio-classifier architecture

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

- Interactive diagram: https://gitdiagram.com/tearcake/audio-classifier
- Repository: https://github.com/tearcake/audio-classifier

## Overview

This repository combines a browser audio-classification workflow with a separate PyTorch training path. Users select audio, the Next.js page trims/encodes it, and its upload route forwards it to FastAPI; inference preprocesses audio, runs the checkpoint-backed AudioCNN, and returns predictions and visualizations for the UI. Training builds the same model and saves its best checkpoint. The main inference, route, page, model, training, and feature-map relationships are supported by excerpts; other UI rendering capabilities are documented or visible in the page excerpt, while their implementation details were not sampled.

Main entry points: [`audio-visualization/src/app/page.tsx`](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/app/page.tsx) (Upload page), [`main.py`](https://github.com/tearcake/audio-classifier/blob/main/main.py) (Inference API), [`train.py`](https://github.com/tearcake/audio-classifier/blob/main/train.py) (Training pipeline), [`audio-visualization/src/app/api/upload/route.ts`](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/app/api/upload/route.ts) (Upload proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser application"]
  node_page["Upload page<br/>[page.tsx]"]
  node_audio["Audio preparation<br/>[audio.ts]"]
  node_upload["Upload proxy<br/>[route.ts]"]
end

subgraph group_service["Inference service"]
  node_inference["Inference API<br/>[main.py]"]
  node_preprocess["Audio preprocessing<br/>[main.py]"]
  node_classifier["Audio classifier<br/>[main.py]"]
end

subgraph group_modeling["Model lifecycle"]
  node_network["AudioCNN<br/>[model.py]"]
  node_checkpoint[("Best checkpoint<br/>[best_model.pth]")]
  node_training["Training pipeline<br/>[train.py]"]
end

subgraph group_visuals["Result visualizations"]
  node_featuremap["Feature-map view<br/>[FeatureMap.tsx]"]
  node_colors["Feature colors<br/>[colors.ts]"]
  node_waveform["Waveform view<br/>[Waveform.tsx]"]
  node_colorscale["Color scale<br/>[ColorScale.tsx]"]
end

node_user(("Audio uploader"))

node_user -->|"selects audio"| node_page
node_page -->|"prepares audio"| node_audio
node_page -->|"posts payload"| node_upload
node_upload -->|"forwards request"| node_inference
node_inference -->|"decodes and transforms"| node_preprocess
node_inference -->|"runs inference"| node_classifier
node_classifier -->|"loads weights"| node_checkpoint
node_classifier -->|"invokes model"| node_network
node_training -->|"trains model"| node_network
node_training -->|"saves best weights"| node_checkpoint
node_page -->|"renders maps"| node_featuremap
node_featuremap -->|"gets colors"| node_colors
node_page -->|"renders waveform"| node_waveform
node_page -->|"renders scale"| node_colorscale

click node_page "https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/app/page.tsx"
click node_audio "https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/lib/audio.ts"
click node_upload "https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/app/api/upload/route.ts"
click node_inference "https://github.com/tearcake/audio-classifier/blob/main/main.py"
click node_preprocess "https://github.com/tearcake/audio-classifier/blob/main/main.py"
click node_classifier "https://github.com/tearcake/audio-classifier/blob/main/main.py"
click node_network "https://github.com/tearcake/audio-classifier/blob/main/model.py"
click node_checkpoint "https://github.com/tearcake/audio-classifier/blob/main/models/checkpoints/best_model.pth"
click node_training "https://github.com/tearcake/audio-classifier/blob/main/train.py"
click node_featuremap "https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/components/FeatureMap.tsx"
click node_colors "https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/lib/colors.ts"
click node_waveform "https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/components/Waveform.tsx"
click node_colorscale "https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/components/ColorScale.tsx"

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_page,node_audio,node_upload toneBlue
class node_inference,node_preprocess,node_classifier toneAmber
class node_network,node_checkpoint,node_training toneMint
class node_featuremap,node_colors,node_waveform,node_colorscale toneRose
class node_user toneIndigo
```

## Components

### Browser application

- [Upload page](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/app/page.tsx): `audio-visualization/src/app/page.tsx`
- [Audio preparation](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/lib/audio.ts): `audio-visualization/src/lib/audio.ts`
- [Upload proxy](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/app/api/upload/route.ts): `audio-visualization/src/app/api/upload/route.ts`

### Inference service

- [Inference API](https://github.com/tearcake/audio-classifier/blob/main/main.py): `main.py`
- [Audio preprocessing](https://github.com/tearcake/audio-classifier/blob/main/main.py): `main.py`
- [Audio classifier](https://github.com/tearcake/audio-classifier/blob/main/main.py): `main.py`

### Model lifecycle

- [AudioCNN](https://github.com/tearcake/audio-classifier/blob/main/model.py): `model.py`
- [Best checkpoint](https://github.com/tearcake/audio-classifier/blob/main/models/checkpoints/best_model.pth): `models/checkpoints/best_model.pth`
- [Training pipeline](https://github.com/tearcake/audio-classifier/blob/main/train.py): `train.py`

### Result visualizations

- [Feature-map view](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/components/FeatureMap.tsx): `audio-visualization/src/components/FeatureMap.tsx`
- [Feature colors](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/lib/colors.ts): `audio-visualization/src/lib/colors.ts`
- [Waveform view](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/components/Waveform.tsx): `audio-visualization/src/components/Waveform.tsx`
- [Color scale](https://github.com/tearcake/audio-classifier/blob/main/audio-visualization/src/components/ColorScale.tsx): `audio-visualization/src/components/ColorScale.tsx`

### Other components

- **Audio uploader**

## Connections

- Audio uploader → Upload page: selects audio (evidence: `README.md`)
- Upload page → Audio preparation: prepares audio (evidence: `audio-visualization/src/app/page.tsx`)
- Upload page → Upload proxy: posts payload (evidence: `audio-visualization/src/app/page.tsx`)
- Upload proxy → Inference API: forwards request (evidence: `audio-visualization/src/app/api/upload/route.ts`)
- Inference API → Audio preprocessing: decodes and transforms (evidence: `main.py`)
- Inference API → Audio classifier: runs inference (evidence: `main.py`)
- Audio classifier → Best checkpoint: loads weights (evidence: `main.py`)
- Audio classifier → AudioCNN: invokes model (evidence: `main.py`)
- Training pipeline → AudioCNN: trains model (evidence: `train.py`)
- Training pipeline → Best checkpoint: saves best weights (evidence: `train.py`)
- Upload page → Feature-map view: renders maps (evidence: `audio-visualization/src/app/page.tsx`)
- Feature-map view → Feature colors: gets colors (evidence: `audio-visualization/src/components/FeatureMap.tsx`)
- Upload page → Waveform view: renders waveform (evidence: `audio-visualization/src/app/page.tsx`)
- Upload page → Color scale: renders scale (evidence: `audio-visualization/src/app/page.tsx`)
