# johncalvinroberts/pprmnt architecture

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

- Interactive diagram: https://gitdiagram.com/johncalvinroberts/pprmnt
- Repository: https://github.com/johncalvinroberts/pprmnt

## Overview

##### Project Type & Purpose
- pprmnt is a client-side, secure MP3 conversion tool aimed at enabling musicians to encode audio locally in the browser.
- It uses WebAssembly (compiled from C using Emscripten and Docker) to run the libmp3lame encoder, and a React frontend (with web workers) to provide a responsive PWA interface.
- The overall goal is security (local conversion without sending audio to remote servers) and offline capability.

##### Main Components
a. Build/Compilation Environment:
- Docker & Makefile: Represent the Docker container that supplies the C build environment.
- modules/peppermint.c & modules/build.sh: Indicate the C source and build scripts.
- Emscripten: Part of the build toolchain used to compile C code into the WebAssembly binary (.wasm and accompanying JavaScript wrapper in modules/artifacts).

b. Frontend Application:
- React Application (located in the src folder): This includes the various React components (App.js, Header.js, Footer.js, etc.) that form the user interface.
- Assets & Service Worker: Mark components like index.html, manifest.webmanifest, and service-worker.js which make the app a PWA and handle offline functionality.
- Build Tools: Parcel Bundler (as per the README) along with ESLint, Babel, Prettier and related configuration files are part of the development & build setup.

c. WebAssembly & Worker Integration:
- WebAssembly Module: Represent the compiled peppermint.wasm (and peppermint.js wrapper) that provides the MP3 encoding functionality.
- Interaction Flow: Show how the React components invoke the worker, which then interacts with the WebAssembly module for MP3 encoding.

##### Relationships and Interactions
- That the web worker loads and calls functions in the WebAssembly module for actual MP3 encoding.
- That the frontend build process (using Parcel and yarn commands) assembles the final PWA bundle that integrates all assets.

##### Architectural Patterns & Technologies
- Separation of concerns:
- Build-time artifact generation (using Docker, Makefile, and shell scripts) is separate from frontend business logic.
- Use of Web Workers encapsulates compute-heavy tasks to avoid UI thread blockage.
- Technologies:
- libmp3lame as the audio encoding library.
- Emscripten for compiling native code to WASM.
- React for frontend UI development.
- Progressive Web App characteristics (service worker, manifest, offline capability).
- Design principles like modularity, safe local processing, and performance optimization through offloading tasks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Environment Subgraph
    subgraph "Build Environment"
        DockerBld["Docker Build Environment"]
        CsrcBuild["C Source & Build Scripts"]
        WASM_Artifacts["WASM Artifacts"]
    end

    %% Runtime Environment Subgraph
    subgraph "Runtime Environment"
        subgraph "Frontend UI Layer"
            ReactApp["React Frontend Application"]
            PWAAssets["PWA Assets"]
        end
        subgraph "Processing Layer"
            WebWorker["Web Worker"]
            WASM_Module["WASM Module"]
        end
    end

    %% Build Process Flow
    DockerBld -->|"providesEnvironment"| CsrcBuild
    CsrcBuild -->|"compiledViaEmscripten"| WASM_Artifacts
    WASM_Artifacts -->|"buildOutputUsed"| WASM_Module

    %% Runtime Process Flow
    ReactApp -->|"encodeRequest"| WebWorker
    WebWorker -->|"encodingTask"| WASM_Module
    WASM_Module -->|"encodingResult"| WebWorker
    WebWorker -->|"resultDelivery"| ReactApp
    PWAAssets -->|"assetsLoaded"| ReactApp

    %% Click Events for Component Mapping
    click DockerBld "https://github.com/johncalvinroberts/pprmnt/tree/main/Dockerfile"
    click CsrcBuild "https://github.com/johncalvinroberts/pprmnt/blob/main/modules/peppermint.c"
    click WASM_Artifacts "https://github.com/johncalvinroberts/pprmnt/blob/main/modules/artifacts/peppermint.wasm"
    click ReactApp "https://github.com/johncalvinroberts/pprmnt/tree/main/src/"
    click PWAAssets "https://github.com/johncalvinroberts/pprmnt/blob/main/src/manifest.webmanifest"
    click WebWorker "https://github.com/johncalvinroberts/pprmnt/blob/main/src/peppermint.worker.js"

    %% Styling
    classDef build fill:#f9d6ac,stroke:#f27c58,stroke-width:2px;
    classDef runtimeUI fill:#acdaf9,stroke:#4064ac,stroke-width:2px;
    classDef processing fill:#d6f9ac,stroke:#58a745,stroke-width:2px;

    class DockerBld,CsrcBuild,WASM_Artifacts build;
    class ReactApp,PWAAssets runtimeUI;
    class WebWorker,WASM_Module processing;
```
