# peter-dated-projects/04-13-2025_speech-to-text-mac architecture

> Architecture diagram of the GitHub repository peter-dated-projects/04-13-2025_speech-to-text-mac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peter-dated-projects/04-13-2025_speech-to-text-mac
- Repository: https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac

## Overview

##### Project type and purpose
- This is a full-stack, real-time speech-to-text application optimized for macOS M2 using the whisper.cpp Python port.
- It comprises a Next.js/React frontend, a Flask backend exposing REST/streaming APIs, and a MongoDB database.

##### File structure
- Top-level directories:
- assets/models – pre-downloaded whisper.cpp model files
- backend/ – Flask app
◦ backend.py & main.py – entry points
◦ api/ – three modules: storage.py, streaming.py, stt.py (with accompanying .md docs)
◦ models/ – ORM-style Python models (session, recording, segment, conversation, user)
◦ mongodb.conf, setup.sh – database config & setup script
◦ static/ – static assets served by Flask
◦ logs/ – runtime logs for debugging/inference
- frontend/ – Next.js React app
◦ app/components/ – UI widgets (AudioRecorder, Conversation, Message, etc.)
◦ public/ – static files
◦ config/build: tsconfig.json, next.config.ts, eslint.config.mjs, package.json
- Root config files: .env, requirements.txt, setup.py, pyproject.toml

##### README for additional insights
- Confirms the three parts: React/Next.js frontend, Flask backend, MongoDB database
- Emphasizes real-time STT on M2 using whisper.cpp Python port

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UserBrowser["User Browser"]:::frontend
        FrontendApp["Next.js/React App"]:::frontend
        AudioRecorder["AudioRecorder Component"]:::frontend
        ConversationUI["Conversation Components"]:::frontend
        Message["Message Component"]:::frontend
        Icons["Icons Component"]:::frontend
        Styles["Styles"]:::frontend
        Config["Frontend Config & Tooling"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        subgraph "Entry Points"
            direction TB
            BackendBackend["backend.py"]:::backend
            BackendMain["main.py"]:::backend
        end
        subgraph "API Modules"
            direction TB
            StorageAPI["Storage API"]:::backend
            StreamingAPI["Streaming API"]:::backend
            STTAPI["Batch STT API"]:::backend
        end
        subgraph "Business Models"
            direction TB
            Session["Session Model"]:::backend
            Recording["Recording Model"]:::backend
            Segment["Segment Model"]:::backend
            ConversationModel["Conversation Model"]:::backend
            UserModel["User Model"]:::backend
        end
        WhisperEngine["whisper.cpp Inference Engine"]:::backend
    end

    %% Data & Assets
    subgraph "Data & Assets"
        direction TB
        MongoDB["MongoDB"]:::database
        FileStorage["File Storage"]:::storage
        StaticAssets["Static Assets"]:::storage
        Logs["Logging Service"]:::storage
        ModelAssets["Model Assets"]:::storage
        RootConfig["Root Config & Dependencies"]:::storage
    end

    %% Interactions
    UserBrowser -->|"records audio"| AudioRecorder
    AudioRecorder -->|"streams audio POST /streaming"| StreamingAPI
    StreamingAPI -->|"buffers & calls inference"| WhisperEngine
    WhisperEngine -->|"SSE/WebSocket transcripts"| FrontendApp
    FrontendApp -->|"POST /stt"| STTAPI
    STTAPI -->|"calls inference"| WhisperEngine
    STTAPI -->|"returns transcript"| FrontendApp
    FrontendApp -->|"POST /storage"| StorageAPI
    StorageAPI -->|"writes metadata"| MongoDB
    StorageAPI -->|"stores audio"| FileStorage
    FrontendApp -->|"fetch conversation"| MongoDB

    %% Click Events
    click FrontendApp "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/tree/main/frontend/"
    click AudioRecorder "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/frontend/app/components/AudioRecorder.tsx"
    click ConversationUI "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/frontend/app/components/Conversation.tsx"
    click Message "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/frontend/app/components/Message.tsx"
    click Icons "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/frontend/app/components/icons.tsx"
    click Styles "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/tree/main/frontend/app/components/styles/"
    click Config "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/frontend/next.config.ts"

    click BackendBackend "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/backend.py"
    click BackendMain "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/main.py"
    click StorageAPI "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/api/storage.py"
    click StreamingAPI "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/api/streaming.py"
    click STTAPI "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/api/stt.py"

    click Session "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/models/session.py"
    click Recording "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/models/recording.py"
    click Segment "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/models/segment.py"
    click ConversationModel "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/models/conversation.py"
    click UserModel "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/backend/models/user.py"

    click StaticAssets "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/tree/main/backend/static/"
    click Logs "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/tree/main/backend/logs/"
    click ModelAssets "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/tree/main/assets/models/"
    click RootConfig "https://github.com/peter-dated-projects/04-13-2025_speech-to-text-mac/blob/main/.env"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef database fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px
    classDef storage fill:#F5F5F5,stroke:#757575,stroke-width:1px
```
