# jmunoz1992/mp3-frame-counter architecture

> Architecture diagram of the GitHub repository jmunoz1992/mp3-frame-counter, 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/jmunoz1992/mp3-frame-counter
- Repository: https://github.com/jmunoz1992/mp3-frame-counter

## Overview

This repository provides a streaming Express API for counting supported MPEG-1 Layer III frames in uploaded MP3 files. The main flow validates a multipart upload, feeds file chunks into the counter, skips a leading ID3v2 tag, parses and counts frames (excluding a first-frame Xing index), then returns JSON. Configuration, HTTP error mapping, health checks, and 404 handling are also shown. Relationships follow the excerpts and README; no unsampled runtime wiring is inferred.

Main entry points: [`src/app.ts`](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/app.ts) (Express app), [`src/routes/fileUpload.ts`](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/routes/fileUpload.ts) (File upload), [`src/mp3/FrameCounter.ts`](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/FrameCounter.ts) (Streaming counter), [`src/server.ts`](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/server.ts) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_server["HTTP server<br/>[server.ts]"]
  node_app["Express app<br/>[app.ts]"]
  node_config["Runtime config<br/>[config.ts]"]
  node_upload["File upload<br/>[fileUpload.ts]"]
  node_health["Health check<br/>[app.ts]"]
end

subgraph group_counting["MP3 Counting"]
  node_counter["Streaming counter<br/>[FrameCounter.ts]"]
  node_id3["ID3v2 reader<br/>[id3.ts]"]
  node_header["Frame header parser<br/>[frameHeader.ts]"]
  node_constants["MPEG tables<br/>[constants.ts]"]
  node_types["Parse types<br/>[types.ts]"]
end

subgraph group_errors["Error Handling"]
  node_http_error["HTTP error<br/>[HttpError.ts]"]
  node_error_handler["Error middleware<br/>[errorHandler.ts]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_server
node_server -->|"creates app"| node_app
node_server -->|"reads port"| node_config
node_app -->|"mounts router"| node_upload
node_app -->|"registers handler"| node_error_handler
node_app -->|"creates 404 error"| node_http_error
node_client -->|"checks health"| node_health
node_upload -->|"reads upload settings"| node_config
node_upload -->|"feeds file chunks"| node_counter
node_upload -->|"creates upload errors"| node_http_error
node_counter -->|"checks tag"| node_id3
node_counter -->|"parses frames"| node_header
node_header -->|"uses tables"| node_constants
node_counter -->|"throws parse error"| node_types
node_error_handler -->|"maps status"| node_http_error
node_error_handler -->|"maps parse error"| node_types

click node_server "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/server.ts"
click node_app "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/app.ts"
click node_config "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/config.ts"
click node_upload "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/routes/fileUpload.ts"
click node_health "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/app.ts"
click node_counter "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/FrameCounter.ts"
click node_id3 "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/id3.ts"
click node_header "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/frameHeader.ts"
click node_constants "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/constants.ts"
click node_types "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/types.ts"
click node_http_error "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/errors/HttpError.ts"
click node_error_handler "https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/middleware/errorHandler.ts"

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_server,node_app,node_config,node_upload,node_health,node_client toneBlue
class node_counter,node_id3,node_header,node_constants,node_types toneAmber
class node_http_error,node_error_handler toneMint
```

## Components

### HTTP API

- [HTTP server](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/server.ts): `src/server.ts`
- [Express app](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/app.ts): `src/app.ts`
- [Runtime config](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/config.ts): `src/config.ts`
- [File upload](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/routes/fileUpload.ts): `src/routes/fileUpload.ts`
- [Health check](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/app.ts): `src/app.ts`

### MP3 Counting

- [Streaming counter](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/FrameCounter.ts): `src/mp3/FrameCounter.ts`
- [ID3v2 reader](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/id3.ts): `src/mp3/id3.ts`
- [Frame header parser](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/frameHeader.ts): `src/mp3/frameHeader.ts`
- [MPEG tables](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/constants.ts): `src/mp3/constants.ts`
- [Parse types](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/mp3/types.ts): `src/mp3/types.ts`

### Error Handling

- [HTTP error](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/errors/HttpError.ts): `src/errors/HttpError.ts`
- [Error middleware](https://github.com/jmunoz1992/mp3-frame-counter/blob/main/src/middleware/errorHandler.ts): `src/middleware/errorHandler.ts`

### Other components

- **API client**

## Connections

- API client → HTTP server: sends requests (evidence: `README.md`)
- HTTP server → Express app: creates app (evidence: `src/server.ts`)
- HTTP server → Runtime config: reads port (evidence: `src/server.ts`)
- Express app → File upload: mounts router (evidence: `src/app.ts`)
- Express app → Error middleware: registers handler (evidence: `src/app.ts`)
- Express app → HTTP error: creates 404 error (evidence: `src/app.ts`)
- API client → Health check: checks health (evidence: `README.md`)
- File upload → Runtime config: reads upload settings (evidence: `src/routes/fileUpload.ts`)
- File upload → Streaming counter: feeds file chunks (evidence: `src/routes/fileUpload.ts`)
- File upload → HTTP error: creates upload errors (evidence: `src/routes/fileUpload.ts`)
- Streaming counter → ID3v2 reader: checks tag (evidence: `src/mp3/FrameCounter.ts`)
- Streaming counter → Frame header parser: parses frames (evidence: `src/mp3/FrameCounter.ts`)
- Frame header parser → MPEG tables: uses tables (evidence: `src/mp3/frameHeader.ts`)
- Streaming counter → Parse types: throws parse error (evidence: `src/mp3/FrameCounter.ts`)
- Error middleware → HTTP error: maps status (evidence: `src/middleware/errorHandler.ts`)
- Error middleware → Parse types: maps parse error (evidence: `src/middleware/errorHandler.ts`)
