# murtaza-nasir/speakr architecture

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

- Interactive diagram: https://gitdiagram.com/murtaza-nasir/speakr
- Repository: https://github.com/murtaza-nasir/speakr

## Overview

##### Project Type and Purpose
- Speakr is a self-hosted, full-stack web application for AI transcription and note-taking.
- Backend: Python/Flask REST and web server with SQLAlchemy ORM.
- Frontend: Vue.js 3 single-page application (SPA) with Tailwind CSS, PWA support (service worker, offline.html).
- AI/ML layer: Integrates with Whisper-based ASR (either local container or OpenAI/Whisper API) and conversational AI (OpenAI, OpenRouter, Ollama).
- Data store: SQLite (default) or PostgreSQL.

##### Top-Level Components (based on file tree)
- Docker & Deployment
- Dockerfile, .dockerignore, docker-publish CI workflow
- config/docker-compose.example.yml for multi-container orchestration
- deployment/setup.sh, scripts/docker-entrypoint.sh
- Backend Service (Flask)
- src/app.py defines HTTP routes, API endpoints, template serving
- src/audio_chunking.py, src/file_monitor.py handle background processing
- scripts/… for DB migration, admin user creation, version updates
- Frontend Assets
- static/js (app.js, shared-components.js, i18n.js), static/css/styles.css
- PWA files: sw.js, offline.html, manifest.json, static/locales/*.json
- templates/*.html as server-side entry points for the SPA
- Database
- SQLite file or PostgreSQL instance configured via .env
- AI/ML Services
- Optional ASR container (onerahmet/openai-whisper-asr-webservice) for speaker diarization
- External APIs: OpenAI Whisper, OpenRouter, Ollama
- Documentation (MkDocs) – docs/ and mkdocs.yml (outside runtime)

##### Relationships & Data Flows
- 1) User (browser) → static SPA assets (served by Flask)
- 2) SPA → Flask REST endpoints (record, upload audio, transcripts, inquire mode)
- 3) Flask enqueues or directly calls audio processing modules (audio_chunking, file_monitor)
- 4) Audio modules → ASR container or external Whisper API → transcript data
- 5) Flask persists transcripts, metadata, tags, users to DB
- 6) SPA polling or WebSocket (if configured) for transcription progress and results
- 7) SPA → External conversational AI APIs for interactive chat and semantic search
- 8) Admin scripts and cron jobs (scripts/reset_db.py, migrate_…​) manage data lifecycle
- 9) Docker Compose ties together: speakr-app, db, asr-service (optional)

##### Architectural Patterns & Principles
- MVC-style separation:
- Models: SQLAlchemy ORM in src/ and migrations via scripts/
- Views: Vue.js components + Jinja2 templates as SPA entrypoint
- Controllers: Flask route handlers in src/app.py
- Modular background processing: audio_chunking and file_monitor as reusable modules
- Configuration via environment (.env) and Docker Compose for portability
- PWA best practices: service worker, offline fallback, manifest.json
- Internationalization: static/locales JSON files and i18n.js

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser & SPA)" 
        direction TB
        Browser["User Browser"]:::frontend
        SPA["Vue.js SPA (app.js, shared-components.js, i18n.js, csrf-refresh.js)"]:::frontend
        SW["Service Worker (sw.js)"]:::frontend
        Offline["Offline Page (offline.html)"]:::frontend
        Manifest["Manifest (manifest.json)"]:::frontend
        CSS["Stylesheet (styles.css)"]:::frontend
        Locales["Locales JSON"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Flask API & Workers)"
        direction TB
        FlaskApp["Flask API (src/app.py)"]:::backend
        AudioChunk["Audio Chunking (src/audio_chunking.py)"]:::backend
        FileMonitor["File Monitor (src/file_monitor.py)"]:::backend
        AdminScripts["Admin & Migrations"]:::backend
        MigrDocker["migrate_docker.sh"]:::backend
        MigrRecord["migrate_existing_recordings.py"]:::backend
        ResetDB["reset_db.py"]:::backend
        CreateAdmin["create_admin.py & docker_create_admin.py"]:::backend
        ParseASR["parse_asr_json.py"]:::backend
    end

    %% Database
    subgraph "Database"
        direction TB
        DB["SQLite/PostgreSQL"]:::database
    end

    %% AI/ML Services
    subgraph "AI/ML Services"
        direction TB
        LocalASR["Local ASR Container (port 8000)"]:::external
        WhisperAPI["OpenAI Whisper API"]:::external
        ConversationalAI["External Chat APIs"]:::external
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        direction TB
        DockerfileNode["Dockerfile"]:::deploy
        Dockerignore[".dockerignore"]:::deploy
        Compose["docker-compose.example.yml"]:::deploy
        EnvASR["env.asr.example"]:::deploy
        EnvWhisper["env.whisper.example"]:::deploy
        SetupSh["setup.sh"]:::deploy
        Entrypoint["docker-entrypoint.sh"]:::deploy
        PublishCI["docker-publish.yml"]:::deploy
        DocsCI["docs.yml & docs1.yml"]:::deploy
        MkdocsCfg["mkdocs.yml"]:::deploy
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        DocsSrc["docs/"]:::docs
        CreateDocs["create_docs.py"]:::docs
    end

    %% Connections
    Browser -->|"loads SPA assets"| SPA
    SPA -->|"API calls"| FlaskApp
    SW -->|"intercepts requests"| SPA
    SPA -->|"offline fallback"| Offline
    SPA -->|"reads"| CSS
    SPA -->|"reads"| Locales
    SPA -->|"uses"| Manifest

    FlaskApp -->|"enqueue"| AudioChunk
    FlaskApp -->|"enqueue"| FileMonitor
    AudioChunk -->|"HTTP to"| LocalASR
    FileMonitor -->|"calls"| WhisperAPI
    LocalASR -->|"transcript data"| FlaskApp
    WhisperAPI -->|"transcript data"| FlaskApp
    FlaskApp -->|"read/write"| DB
    FlaskApp -->|"calls"| ConversationalAI
    ConversationalAI -->|"AI response"| FlaskApp

    AdminScripts --> FlaskApp
    MigrDocker --> AdminScripts
    MigrRecord --> AdminScripts
    ResetDB --> AdminScripts
    CreateAdmin --> AdminScripts
    ParseASR --> AdminScripts

    DockerfileNode --> Compose
    Dockerignore --> DockerfileNode
    Compose -->|".env configs"| EnvASR
    Compose -->|".env configs"| EnvWhisper
    Compose --> FlaskApp
    Compose --> DB
    Compose --> LocalASR
    SetupSh --> DockerfileNode
    Entrypoint --> FlaskApp
    PublishCI --> DockerfileNode

    DocsCI --> MkdocsCfg
    MkdocsCfg --> DocsSrc
    CreateDocs --> DocsSrc

    %% Click Events
    click DockerfileNode "https://github.com/murtaza-nasir/speakr/tree/master/Dockerfile"
    click Dockerignore "https://github.com/murtaza-nasir/speakr/blob/master/.dockerignore"
    click PublishCI "https://github.com/murtaza-nasir/speakr/blob/master/.github/workflows/docker-publish.yml"
    click Compose "https://github.com/murtaza-nasir/speakr/blob/master/config/docker-compose.example.yml"
    click EnvASR "https://github.com/murtaza-nasir/speakr/blob/master/config/env.asr.example"
    click EnvWhisper "https://github.com/murtaza-nasir/speakr/blob/master/config/env.whisper.example"
    click SetupSh "https://github.com/murtaza-nasir/speakr/blob/master/deployment/setup.sh"
    click Entrypoint "https://github.com/murtaza-nasir/speakr/blob/master/scripts/docker-entrypoint.sh"
    click FlaskApp "https://github.com/murtaza-nasir/speakr/blob/master/src/app.py"
    click AudioChunk "https://github.com/murtaza-nasir/speakr/blob/master/src/audio_chunking.py"
    click FileMonitor "https://github.com/murtaza-nasir/speakr/blob/master/src/file_monitor.py"
    click MigrDocker "https://github.com/murtaza-nasir/speakr/blob/master/scripts/migrate_docker.sh"
    click MigrRecord "https://github.com/murtaza-nasir/speakr/blob/master/scripts/migrate_existing_recordings.py"
    click ResetDB "https://github.com/murtaza-nasir/speakr/blob/master/scripts/reset_db.py"
    click CreateAdmin "https://github.com/murtaza-nasir/speakr/blob/master/scripts/create_admin.py"
    click ParseASR "https://github.com/murtaza-nasir/speakr/blob/master/scripts/parse_asr_json.py"
    click SPA "https://github.com/murtaza-nasir/speakr/blob/master/static/js/app.js"
    click CSS "https://github.com/murtaza-nasir/speakr/blob/master/static/css/styles.css"
    click SW "https://github.com/murtaza-nasir/speakr/blob/master/static/sw.js"
    click Offline "https://github.com/murtaza-nasir/speakr/blob/master/static/offline.html"
    click Manifest "https://github.com/murtaza-nasir/speakr/blob/master/static/manifest.json"
    click Locales "https://github.com/murtaza-nasir/speakr/blob/master/static/locales/de.json"
    click DocsSrc "https://github.com/murtaza-nasir/speakr/tree/master/docs/"
    click MkdocsCfg "https://github.com/murtaza-nasir/speakr/blob/master/mkdocs.yml"
    click CreateDocs "https://github.com/murtaza-nasir/speakr/blob/master/docs/create_docs.py"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px
    classDef backend fill:#D5F5E3,stroke:#1D8348,stroke-width:2px
    classDef database fill:#FCF3CF,stroke:#B7950B,stroke-width:2px
    classDef external fill:#FADBD8,stroke:#943126,stroke-width:2px
    classDef deploy fill:#E8DAEF,stroke:#6C3483,stroke-width:2px
    classDef docs fill:#FDEDEC,stroke:#78281F,stroke-width:2px
```
