# cabird/quickscribe architecture

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

- Interactive diagram: https://gitdiagram.com/cabird/quickscribe
- Repository: https://github.com/cabird/quickscribe

## Overview

##### Main Components

- Frontend – Represented by the “vite-frontend” directory:
- Uses Vite, TypeScript, and React (or a similar framework based on file names such as App.tsx, Router.tsx, and various UI components).
- Contains API calls (see the “api” folder) that interact with the backend.

- Backend – Represented by the “backend” directory:
- Contains the primary application code (app.py, manage.py) and routes (in the “routes” folder) that expose REST endpoints.
- Includes specialized modules such as “audiostream_api” for audio streaming operations and “azure_speech” which integrates with Microsoft Azure’s Speech services via its autogenerated Python client.
- Contains various API endpoints: audiostream, transcription routes (az_transcription_routes.py), etc.

- Database and Storage – Evidenced by:
- “db_handlers” directory which likely manages interactions with the underlying databases (Cosmos DB hints in “cosmos_schema” and file names like recording_handler.py, transcription_handler.py).
- The “chunk_storage” files in audiostream_api indicate that audio data might be split into chunks for processing or storage.

- External Services & Third-Party Integrations:
- Azure Speech Services: The “azure_speech” folder (with its Python client, swagger_client, and extensive documentation) signals integration with Microsoft Azure’s cognitive services.

- Infrastructure – Represented by the “infrastructure/terraform” directory:
- Contains scripts (e.g., create_resources.sh) for provisioning cloud resources. This suggests that your deployment may involve automated cloud resource management.

- Shared Models:

##### Relationships and Interactions

- Frontend to Backend:

- Backend Internal Modules:
- Within the backend, route handlers in “routes” delegate operations to service layers defined in “audiostream_api,” “db_handlers,” and custom utilities like “auth.py”, “llms.py”, and “util.py.”

- Integration with Azure:

- Database Operations:

- Infrastructure:
- “Terraform/Infrastructure” as a separate component that provisions or manages cloud resources, which in turn support the backend’s hosting or the database’s deployment.

##### Architectural Patterns and Design Principles

- Layered Architecture:
- Separate the presentation layer (frontend), business logic (backend routes, APIs, and service modules), and data persistence (database handlers).

- Separation of Concerns:

- RESTful Architecture:

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (Vite/React)"]:::frontend
        FE_App["App.tsx"]:::frontend
        FE_Router["Router.tsx"]:::frontend
        FE_API["API (vite-frontend/src/api)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE["Backend API (Python)"]:::backend
        BE_Routes["Routes (backend/routes)"]:::backend
        BE_API_Route["api.py"]:::backend
        BE_Audiostream_Route["audiostream.py"]:::backend
        BE_AZTranscription_Route["az_transcription_routes.py"]:::backend

        BPM["Audio Processing Module"]:::module
        BPM_AudioOps["audio_operations.py"]:::module
        BPM_Chunk["chunk_storage.py"]:::module

        BE_Azure["Azure Speech Integration"]:::module
        BE_DB["Database / Data Handlers"]:::database
        DB_Cosmos["Cosmos Schema"]:::database
    end

    %% Infrastructure & External Services Layer
    subgraph "Infrastructure & External Services"
        EX_Azure["Azure Speech Services"]:::external
        EX_Terraform["Cloud Infrastructure (Terraform)"]:::infrastructure
    end

    %% Shared Models (bridging Frontend and Backend)
    SM["Shared Models"]:::shared

    %% Relationships between Frontend and Backend
    FE_API -->|"calls"| BE
    FE_API -->|"shares data via"| SM
    SM -->|"used by"| BE

    %% Backend internal delegation
    BE -->|"delegates to"| BE_Routes
    BE_Routes -->|"handles"| BE_API_Route
    BE_Routes -->|"handles"| BE_Audiostream_Route
    BE_Routes -->|"handles"| BE_AZTranscription_Route
    BE_Routes -->|"delegates to"| BPM
    BE_Routes -->|"delegates to"| BE_Azure
    BE_Routes -->|"delegates to"| BE_DB

    BE -->|"processes via"| BPM
    BPM --> BPM_AudioOps
    BPM --> BPM_Chunk

    BE -->|"integrates with"| BE_Azure
    BE -->|"performs CRUD with"| BE_DB
    BE_DB --> DB_Cosmos

    %% External integrations and infrastructure
    BE_Azure -->|"calls"| EX_Azure
    EX_Terraform -->|"provisions"| BE
    EX_Terraform -->|"provisions"| BE_DB

    %% Click Events for Frontend
    click FE "https://github.com/cabird/quickscribe/tree/main/vite-frontend"
    click FE_App "https://github.com/cabird/quickscribe/blob/main/vite-frontend/src/App.tsx"
    click FE_Router "https://github.com/cabird/quickscribe/blob/main/vite-frontend/src/Router.tsx"
    click FE_API "https://github.com/cabird/quickscribe/tree/main/vite-frontend/src/api"

    %% Click Events for Backend API and Routes
    click BE "https://github.com/cabird/quickscribe/tree/main/backend"
    click BE_Routes "https://github.com/cabird/quickscribe/tree/main/backend/routes"
    click BE_API_Route "https://github.com/cabird/quickscribe/blob/main/backend/routes/api.py"
    click BE_Audiostream_Route "https://github.com/cabird/quickscribe/blob/main/backend/routes/audiostream.py"
    click BE_AZTranscription_Route "https://github.com/cabird/quickscribe/blob/main/backend/routes/az_transcription_routes.py"

    %% Click Events for Audio Processing Module
    click BPM "https://github.com/cabird/quickscribe/tree/main/backend/audiostream_api"
    click BPM_AudioOps "https://github.com/cabird/quickscribe/blob/main/backend/audiostream_api/audio_operations.py"
    click BPM_Chunk "https://github.com/cabird/quickscribe/blob/main/backend/audiostream_api/chunk_storage.py"

    %% Click Event for Azure Speech Integration
    click BE_Azure "https://github.com/cabird/quickscribe/tree/main/backend/azure_speech"

    %% Click Events for Database Handlers
    click BE_DB "https://github.com/cabird/quickscribe/tree/main/backend/db_handlers"
    click DB_Cosmos "https://github.com/cabird/quickscribe/tree/main/backend/cosmos_schema"

    %% Click Event for Cloud Infrastructure
    click EX_Terraform "https://github.com/cabird/quickscribe/tree/main/infrastructure/terraform"

    %% Click Event for Shared Models
    click SM "https://github.com/cabird/quickscribe/blob/main/shared/Models.ts"

    %% Styles
    classDef frontend fill:#bde0fe,stroke:#5390d9,stroke-width:2px;
    classDef backend fill:#ffdab9,stroke:#e85d04,stroke-width:2px;
    classDef module fill:#caffbf,stroke:#77dd77,stroke-width:2px;
    classDef database fill:#d3f8e2,stroke:#1b4332,stroke-width:2px;
    classDef external fill:#ffc9de,stroke:#ff6f91,stroke-width:2px;
    classDef infrastructure fill:#fef9c7,stroke:#f7e600,stroke-width:2px;
    classDef shared fill:#e0bbf4,stroke:#9b5de5,stroke-width:2px;
```
