# rlarson20/voicevault architecture

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

- Interactive diagram: https://gitdiagram.com/rlarson20/voicevault
- Repository: https://github.com/rlarson20/voicevault

## Overview

##### Project type and purpose
- Full-stack web application:
- Frontend: static HTML/JS (templates/index.html, static/recorder.js)
- Backend/API: FastAPI app (server.py + api/ directory)
- Services: audio file management and speech-to-text engine (services/)
- Clients: browser UI and optional Python client (client.py)

##### File structure for key architectural components
- Top-level server entrypoint: server.py
- API layer: api/routes.py (endpoints), api/schemas.py (Pydantic models), api/dependencies.py
- Frontend assets:
- templates/index.html (webpage)
- static/recorder.js (JS logic to capture audio and POST to server)
- Services layer:
- services/file_manager.py (save, retrieve audio files)
- services/STT_Engine.py (invoke speech-to-text logic)
- Supporting scripts: client.py (programmatic API consumer), whis_test.py / sr_example.py (experimentations), MVP/main.py (prototype)

##### Extract architectural insights
- FastAPI application composed of a routing layer that:
a. Accepts multipart file uploads (audio)
b. Delegates to FileManager for persistence
c. Passes file path to STT_Engine for transcription
d. Returns transcript JSON to caller
- Frontend captures audio in browser and invokes the above API endpoints
- No database is present; file system is used for storage
- Prototyping notebooks (Untitled.ipynb) live outside the production path

1) Web Browser (UI):
– index.html + recorder.js
2) FastAPI Server:
– server.py
– api/routes.py
– api/schemas.py
– api/dependencies.py
3) FileManager Service (services/file_manager.py)
4) STT Engine Service (services/STT_Engine.py)
5) Optional Python Client (client.py)
1) Browser → HTTP POST /upload-audio → FastAPI Server
2) Server → FileManager.save(file) → local filesystem
3) Server → STT_Engine.transcribe(filepath) → transcript text
4) Server → HTTP Response (JSON transcript) → Browser
5) (Optional) External Python Client → HTTP API → Server → same flow
c. Architectural patterns & principles:
– Layered architecture: Presentation (UI) → API layer → Services
– Single responsibility: File I/O separated from STT logic
– Dependency injection: FastAPI dependencies.py for service wiring
d. Key technologies & frameworks:
– FastAPI (backend web framework)
– Pydantic schemas for request/response models
– JavaScript Web Audio API (recorder.js)
– Python-based STT engine (could be Whisper, VOSK, etc.)

– [ ] Browser UI (index.html + recorder.js)
– [ ] HTTP endpoint definitions (e.g., POST /transcribe)
– [ ] FileManager service (services/file_manager.py)
– [ ] STT Engine service (services/STT_Engine.py)
– [ ] Optional Python Client (client.py)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Presentation Layer"
        direction TB
        Index["templates/index.html"]:::presentation
        Recorder["static/recorder.js"]:::presentation
    end

    %% Client
    PythonClient[/client.py/]:::client

    %% Backend
    subgraph "Backend Layer"
        direction TB
        Server["FastAPI Server\n(server.py)"]:::backend
        subgraph "API Layer"
            direction TB
            Routes["api/routes.py"]:::backend
            Schemas["api/schemas.py"]:::backend
            Deps["api/dependencies.py"]:::backend
        end
    end

    %% Services
    subgraph "Services Layer"
        direction TB
        FileMgr["FileManager\n(services/file_manager.py)"]:::service
        STTEngine["STT Engine\n(services/STT_Engine.py)"]:::service
    end

    %% Storage
    FileSystem[(File System)]:::storage

    %% Flows
    Index -->|"POST /upload-audio"| Server
    Recorder -->|"POST /upload-audio"| Server
    PythonClient -->|"HTTP API"| Server

    Server -->|"hosts endpoints in"| Routes
    Routes -->|"dependency injection"| Deps
    Routes -->|"validate/request models"| Schemas
    Routes -->|"calls"| FileMgr
    Routes -->|"calls"| STTEngine

    FileMgr -->|"writes audio"| FileSystem
    STTEngine -->|"transcribes audio"| FileSystem
    STTEngine -.->|"returns transcript"| Routes

    Routes -->|"HTTP response (JSON)"| Index
    Routes -->|"HTTP response (JSON)"| PythonClient

    %% Click Events
    click Index "https://github.com/rlarson20/voicevault/blob/main/templates/index.html"
    click Recorder "https://github.com/rlarson20/voicevault/blob/main/static/recorder.js"
    click Server "https://github.com/rlarson20/voicevault/blob/main/server.py"
    click Routes "https://github.com/rlarson20/voicevault/blob/main/api/routes.py"
    click Schemas "https://github.com/rlarson20/voicevault/blob/main/api/schemas.py"
    click Deps "https://github.com/rlarson20/voicevault/blob/main/api/dependencies.py"
    click FileMgr "https://github.com/rlarson20/voicevault/blob/main/services/file_manager.py"
    click FileMgr "https://github.com/rlarson20/voicevault/blob/main/file_manager.py"
    click STTEngine "https://github.com/rlarson20/voicevault/blob/main/services/STT_Engine.py"
    click PythonClient "https://github.com/rlarson20/voicevault/blob/main/client.py"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef service fill:#FFA500,stroke:#000,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef client fill:#D3D3D3,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    class Index,Recorder presentation
    class Server,Routes,Schemas,Deps backend
    class FileMgr,STTEngine service
    class FileSystem storage
    class PythonClient client
```
