# jkcamarador/pitch-it-perfect-api architecture

> Architecture diagram of the GitHub repository jkcamarador/pitch-it-perfect-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jkcamarador/pitch-it-perfect-api
- Repository: https://github.com/jkcamarador/pitch-it-perfect-api

## Overview

Pitch It Perfect is a Flask API that classifies recorder audio as either a sequence of notes or a single note. Clients upload audio to separate endpoints; each endpoint saves the upload, invokes its matching inference workflow, and returns a JSON prediction. The song workflow detects onsets, splits and normalizes note segments, extracts features, and classifies them; the single-note workflow preprocesses one recording and classifies it. Both use the loaded ResNet model and label encoder. Internal relationships are based on the excerpted main.py; the README documents the mobile-client use and /main API.

Main entry points: [`main.py`](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py) (Song inference), [`resnet-best-loss.h5`](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/resnet-best-loss.h5) (ResNet classifier), [`labelEncoder.joblib`](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/labelEncoder.joblib) (Label encoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_song_endpoint["Song endpoint<br/>[main.py]"]
  node_note_endpoint["Single-note endpoint<br/>[main.py]"]
  node_song_result["Song predictions<br/>[main.py]"]
  node_note_result["Note prediction<br/>[main.py]"]
end

subgraph group_audio["Audio processing"]
  node_audio_input["Load and detect onsets<br/>[main.py]"]
  node_partition["Note segmentation<br/>[main.py]"]
  node_rescale["Duration normalization<br/>[main.py]"]
  node_features["Mel features<br/>[main.py]"]
end

subgraph group_inference["Inference"]
  node_song_inference["Song inference<br/>[main.py]"]
  node_note_inference["Note inference<br/>[main.py]"]
  node_resnet["ResNet classifier"]
  node_encoder["Label encoder"]
end

node_client(("Audio client"))

node_client -->|"uploads song"| node_song_endpoint
node_client -->|"uploads note"| node_note_endpoint
node_song_endpoint -->|"calls"| node_song_inference
node_note_endpoint -->|"calls"| node_note_inference
node_song_inference -->|"detects onsets"| node_audio_input
node_song_inference -->|"splits audio"| node_partition
node_song_inference -->|"normalizes segments"| node_rescale
node_song_inference -->|"extracts features"| node_features
node_note_inference -->|"normalizes audio"| node_rescale
node_note_inference -->|"extracts features"| node_features
node_song_inference -->|"classifies segments"| node_resnet
node_note_inference -->|"classifies audio"| node_resnet
node_song_inference -->|"decodes labels"| node_encoder
node_note_inference -->|"decodes label"| node_encoder
node_song_endpoint -->|"returns JSON"| node_song_result
node_note_endpoint -->|"returns JSON"| node_note_result
node_song_inference -->|"returns predictions"| node_song_result
node_note_inference -->|"returns prediction"| node_note_result

click node_song_endpoint "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_note_endpoint "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_song_inference "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_note_inference "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_audio_input "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_partition "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_rescale "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_features "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_resnet "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/resnet-best-loss.h5"
click node_encoder "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/labelEncoder.joblib"
click node_song_result "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py"
click node_note_result "https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/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_song_endpoint,node_note_endpoint,node_song_result,node_note_result,node_client toneBlue
class node_audio_input,node_partition,node_rescale,node_features toneAmber
class node_song_inference,node_note_inference,node_resnet,node_encoder toneMint
```

## Components

### API

- [Song endpoint](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`
- [Single-note endpoint](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`
- [Song predictions](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`
- [Note prediction](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`

### Audio processing

- [Load and detect onsets](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`
- [Note segmentation](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`
- [Duration normalization](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`
- [Mel features](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`

### Inference

- [Song inference](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`
- [Note inference](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/main.py): `main.py`
- [ResNet classifier](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/resnet-best-loss.h5): `resnet-best-loss.h5`
- [Label encoder](https://github.com/jkcamarador/pitch-it-perfect-api/blob/master/labelEncoder.joblib): `labelEncoder.joblib`

### Other components

- **Audio client**

## Connections

- Audio client → Song endpoint: uploads song (evidence: `README.md`)
- Audio client → Single-note endpoint: uploads note (evidence: `main.py`)
- Song endpoint → Song inference: calls (evidence: `main.py`)
- Single-note endpoint → Note inference: calls (evidence: `main.py`)
- Song inference → Load and detect onsets: detects onsets (evidence: `main.py`)
- Song inference → Note segmentation: splits audio (evidence: `main.py`)
- Song inference → Duration normalization: normalizes segments (evidence: `main.py`)
- Song inference → Mel features: extracts features (evidence: `main.py`)
- Note inference → Duration normalization: normalizes audio (evidence: `main.py`)
- Note inference → Mel features: extracts features (evidence: `main.py`)
- Song inference → ResNet classifier: classifies segments (evidence: `main.py`)
- Note inference → ResNet classifier: classifies audio (evidence: `main.py`)
- Song inference → Label encoder: decodes labels (evidence: `main.py`)
- Note inference → Label encoder: decodes label (evidence: `main.py`)
- Song endpoint → Song predictions: returns JSON (evidence: `main.py`)
- Single-note endpoint → Note prediction: returns JSON (evidence: `main.py`)
- Song inference → Song predictions: returns predictions (evidence: `main.py`)
- Note inference → Note prediction: returns prediction (evidence: `main.py`)