# saddysk/audiogram architecture

> Architecture diagram of the GitHub repository saddysk/audiogram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saddysk/audiogram
- Repository: https://github.com/saddysk/audiogram

## Overview

##### Project Type and Purpose
- This is a full-stack, Next.js (T3-stack) web application with two principal modes of operation:
– A client-rendered audiogram-editor UI served by Next.js’s pages and API routes.
– A standalone “bundler” tool that packages the audiogram into a static HTML+JS bundle and deploys it to AWS Lambda.
- Core functionality: take an audio file + transcript, generate interactive audiogram visualizations (waves, bars, hills, subtitles), and optionally produce a static embeddable bundle.

##### File Structure
Top-level directories and files:
- src/pages – Next.js pages:
– index.tsx, Audio.tsx: entrypoints for the UI
– api/render.ts: serverless endpoint that can render audiogram server-side
- src/components – reusable React components for audio I/O and UI
- src/audiogram – core audiogram library (visualization components, schema, audio utilities)
- public & bundled/public – static assets (audio.mp3, subtitles.srt, transcript.txt)
- bundled – output of the bundling process (bundle.js, index.html, public assets)
- createBundle.mjs – Node script using esbuild to produce the “bundled” folder
- deployProjectInLambda.mjs – Node script to upload the bundled output to AWS Lambda
- next.config.mjs, postcss.config.cjs, tailwind.config.ts, etc. – build/config files for Next.js and Tailwind

##### README
- Confirms use of the T3 stack (Next.js, NextAuth.js, Prisma, Tailwind CSS, tRPC), though Prisma/tRPC aren’t currently present in the file tree.
- Deployment targets include Vercel, Netlify, Docker—but here we see a custom AWS Lambda deployment script.

##### Main System Components
a. Developer Tooling (Local):
– createBundle.mjs (esbuild)
– deployProjectInLambda.mjs (AWS Lambda deployer)
b. Next.js Application:
– Frontend (Browser): pages under src/pages, React components in src/components & src/audiogram, styled by Tailwind CSS
– Serverless API (Next.js API Routes): /api/render.ts
c. Core Library:
– src/audiogram visualizations (WaveVisualization, BarsVisualization, HillsVisualization, subtitles)
– audioUtils, Schema.ts
d. Static/Public Assets:
– public/audiogram (audio.mp3, subtitles.srt, transcript.txt)
– bundled/public (same assets, packaged)
e. Deployment Target:
– AWS Lambda (serving the static index.html + bundle.js)
f. External Services (potential/optional):
– Authentication (NextAuth.js)
– Database (Prisma) – if added in future
– tRPC endpoints – if added

##### Relationships and Data Flows
- User (Browser) → Next.js Frontend → (reads public assets or calls API)
- Next.js Frontend ↔ Next.js API (/api/render) → potentially renders frames server-side
- Core Library (in browser or serverless) processes audio + transcript, produces visualization DOM or canvas
- Developer CLI (createBundle) uses core library to emit a static build → bundled/index.html + bundle.js
- deployProjectInLambda pushes bundled/* to AWS Lambda → serves static site under a custom domain

##### Architectural Patterns
- “Monorepo-like” structure combining:
– Full-stack React/Next.js app (SSR + SPA)
– CLI tooling for static bundling
– Serverless deployment pipeline
- Separation of concerns:
– src/pages for routing, src/components for UI primitives, src/audiogram for domain logic
– public vs. bundled for development vs. production assets

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Developer Environment"
        CB["createBundle.mjs"]:::tooling
        DL["deployProjectInLambda.mjs"]:::tooling
    end

    subgraph "Local Next.js Server"
        App["_app.tsx"]:::frontend
        Home["index.tsx"]:::frontend
        AudioPage["Audio.tsx"]:::frontend
        API["/api/render"]:::backend
        App --> Home
        App --> AudioPage
        Home -->|"calls API"| API
    end

    subgraph "Core Audiogram Library"
        Entry["index.ts"]:::core
        Main["Audiogram.tsx"]:::core
        Comp["Composition.tsx"]:::core
        Player["Player.tsx"]:::core
        Wave["WaveVisualization.tsx"]:::core
        Bars["BarsVisualization.tsx"]:::core
        Hills["HillsVisualization.tsx"]:::core
        DefBar["DefaultBarVisualization.tsx"]:::core
        Subs["Subtitles.tsx"]:::core
        Utils["audioUtils.ts"]:::core
        Schema["Schema.ts"]:::core
        Entry --> Main --> Comp --> Player
        Main --> Wave
        Main --> Bars --> DefBar
        Main --> Hills
        Main --> Subs
        Player --> Utils
        Comp --> Schema
    end

    subgraph "UI Primitives"
        IA["InputAudio.tsx"]:::frontend
        Trans["transcription.ts"]:::frontend
        Dur["Duration.tsx"]:::frontend
        IF["InputFile.tsx"]:::frontend
        IT["InputText.tsx"]:::frontend
        IW["InputWrapper.tsx"]:::frontend
    end

    App --> IA
    App --> Trans
    App --> Dur
    App --> IF
    App --> IT
    App --> IW

    subgraph "Static Assets (Dev)"
        ADev1["audio.mp3"]:::assets
        ADev2["subtitles.srt"]:::assets
        ADev3["transcript.txt"]:::assets
    end

    subgraph "Bundled Output"
        BHTML["index.html"]:::assets
        BJS["bundle.js"]:::assets
        BDev1["audio.mp3"]:::assets
        BDev2["subtitles.srt"]:::assets
        BDev3["transcript.txt"]:::assets
    end

    CB -->|"esbuild bundle"| BHTML
    CB --> BJS
    CB --> BDev1
    CB --> BDev2
    CB --> BDev3

    DL -->|"deploy to Lambda"| Lambda

    subgraph "AWS Lambda"
        Lambda["Static Host"]:::lambda
    end

    User["User (Browser)"]:::frontend

    User --> Lambda
    User --> Home
    Lambda --> BHTML
    Lambda --> BJS

    Home --> Entry
    AudioPage --> Entry
    Home --> ADev1
    Home --> ADev2
    Home --> ADev3
    API --> Entry

    click CB "https://github.com/saddysk/audiogram/blob/main/createBundle.mjs"
    click DL "https://github.com/saddysk/audiogram/blob/main/deployProjectInLambda.mjs"
    click App "https://github.com/saddysk/audiogram/blob/main/src/pages/_app.tsx"
    click Home "https://github.com/saddysk/audiogram/blob/main/src/pages/index.tsx"
    click AudioPage "https://github.com/saddysk/audiogram/blob/main/src/pages/Audio.tsx"
    click API "https://github.com/saddysk/audiogram/blob/main/src/pages/api/render.ts"
    click IA "https://github.com/saddysk/audiogram/blob/main/src/components/audio/InputAudio.tsx"
    click Trans "https://github.com/saddysk/audiogram/blob/main/src/components/audio/transcription.ts"
    click Dur "https://github.com/saddysk/audiogram/blob/main/src/components/audio/Duration.tsx"
    click IF "https://github.com/saddysk/audiogram/blob/main/src/components/ui/InputFile.tsx"
    click IT "https://github.com/saddysk/audiogram/blob/main/src/components/ui/InputText.tsx"
    click IW "https://github.com/saddysk/audiogram/blob/main/src/components/ui/InputWrapper.tsx"
    click Entry "https://github.com/saddysk/audiogram/blob/main/src/audiogram/index.ts"
    click Main "https://github.com/saddysk/audiogram/blob/main/src/audiogram/Audiogram.tsx"
    click Comp "https://github.com/saddysk/audiogram/blob/main/src/audiogram/Composition.tsx"
    click Player "https://github.com/saddysk/audiogram/blob/main/src/audiogram/Player.tsx"
    click Wave "https://github.com/saddysk/audiogram/blob/main/src/audiogram/visualizations/WaveVisualization.tsx"
    click Bars "https://github.com/saddysk/audiogram/blob/main/src/audiogram/visualizations/BarsVisualization.tsx"
    click Hills "https://github.com/saddysk/audiogram/blob/main/src/audiogram/visualizations/HillsVisualization.tsx"
    click DefBar "https://github.com/saddysk/audiogram/blob/main/src/audiogram/visualizations/DefaultBarVisualization.tsx"
    click Subs "https://github.com/saddysk/audiogram/blob/main/src/audiogram/Subtitles.tsx"
    click Utils "https://github.com/saddysk/audiogram/blob/main/src/audiogram/visualizations/audioUtils.ts"
    click Schema "https://github.com/saddysk/audiogram/blob/main/src/audiogram/Schema.ts"
    click ADev1 "https://github.com/saddysk/audiogram/blob/main/public/audiogram/audio.mp3"
    click ADev2 "https://github.com/saddysk/audiogram/blob/main/public/audiogram/subtitles.srt"
    click ADev3 "https://github.com/saddysk/audiogram/blob/main/public/audiogram/transcript.txt"
    click BDev1 "https://github.com/saddysk/audiogram/blob/main/bundled/public/audiogram/audio.mp3"
    click BDev2 "https://github.com/saddysk/audiogram/blob/main/bundled/public/audiogram/subtitles.srt"
    click BDev3 "https://github.com/saddysk/audiogram/blob/main/bundled/public/audiogram/transcript.txt"
    click BHTML "https://github.com/saddysk/audiogram/blob/main/bundled/index.html"
    click BJS "https://github.com/saddysk/audiogram/blob/main/bundled/bundle.js"

    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef tooling fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef assets fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef core fill:#f5c6cb,stroke:#333,stroke-width:1px
    classDef lambda fill:#d1ecf1,stroke:#333,stroke-width:1px
```
