# sbogh/digital-stethoscope architecture

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

- Interactive diagram: https://gitdiagram.com/sbogh/digital-stethoscope
- Repository: https://github.com/sbogh/digital-stethoscope

## Overview

##### Project Type and Purpose
- This is a full-stack IoT system (“ScopeFace: Digital Stethoscope”) comprising three main deliverables:
a. Hardware firmware for a XIAO ESP32-S3 (audio capture + Firebase upload)
b. A cloud backend (FastAPI + Firestore) for user management and auxiliary routes
c. A native iOS app (SwiftUI + Firebase Auth/Firestore/Storage) for end-user interaction and playback

##### File Structure Analysis
- Top level:
- backend/ (Python FastAPI service)
- digital-stethoscope/ (Swift Xcode project for the iOS app)
- hardware/ (Arduino .ino firmware + modular drivers)
- Patterns:
- iOS follows MVVM (Views, Controllers, Models)
- Backend uses REST routes (main.py → user_routes.py) and auth_utils.py for JWT or token logic
- Hardware is modularized into individual .ino modules (WiFi, Firebase upload, audio buffer, etc.)
- Cloud/native config:
- Firebase SDK integration in iOS (Auth, Firestore, Storage)
- Firestore used both by hardware (via REST or Firebase C++ SDK) and by FastAPI via a Python wrapper
- No local database—Firebase is the central datastore.

##### Key README Insights
- Frontend: SwiftUI + Firebase packages installed via SPM; uses Info.plist and GoogleService-Info.plist
- Backend: FastAPI with uvicorn, exposes REST endpoints for “main” app
- Hardware: Arduino IDE + PSRAM, connects to WiFi and Firebase using device libraries

## Diagram (Mermaid)

```mermaid
graph TB
    %% Hardware Device
    subgraph "Hardware Device (XIAO ESP32-S3)"
        HW["Hardware Firmware (hardware.ino)"]:::hardware
        subgraph Modules
            PSRAM["PSRAMBuffer_Module.ino"]:::hardware
            WiFi["WiFi_Module.ino"]:::hardware
            Button["Button_Mic_Module.ino"]:::hardware
            Upload["Firebase_SendAudio_Module.ino"]:::hardware
        end
    end

    %% Firebase Cloud Services
    subgraph "Firebase Cloud Services"
        Auth["Firebase Auth"]:::cloud
        Firestore["Firestore (NoSQL DB)"]:::cloud
        Storage["Storage (Audio Blobs)"]:::cloud
    end

    %% FastAPI Backend
    subgraph "FastAPI Backend"
        API["FastAPI Service (main.py)"]:::backend
        UR["user_routes.py"]:::backend
        AuthU["auth_utils.py"]:::backend
        FSWrapper["firestore.py"]:::cloud
    end

    %% iOS App
    subgraph "iOS App (SwiftUI, MVVM)"
        V["Views"]:::mobile
        C["Controllers"]:::mobile
        M["Models"]:::mobile
        APIConfig["APIConfig.swift"]:::mobile
        Info["Info.plist"]:::mobile
        AppEntry["digital_stethoscopeApp.swift"]:::mobile
        GSInfo["GoogleService-Info.plist"]:::mobile
    end

    %% Connections
    HW -->|HTTPS REST upload| Storage
    HW -->|HTTPS REST metadata| Firestore
    Upload -->|SDK call| Storage
    PSRAM -->|buffer| Upload
    Button -->|trigger record| PSRAM
    HW -->|WiFi| Auth
    V -->|SDK Auth| Auth
    V -->|SDK Firestore| Firestore
    V -->|SDK Storage| Storage
    V -->|HTTPS REST| API
    API -->|Python SDK| FSWrapper
    UR -->|defines /users, /auth| API
    AuthU -->|JWT logic| API
    API -->|CRUD| Firestore

    %% Click Events
    click HW "https://github.com/sbogh/digital-stethoscope/blob/main/hardware/hardware.ino"
    click PSRAM "https://github.com/sbogh/digital-stethoscope/tree/main/hardware/modules/"
    click WiFi "https://github.com/sbogh/digital-stethoscope/tree/main/hardware/modules/"
    click Button "https://github.com/sbogh/digital-stethoscope/tree/main/hardware/modules/"
    click Upload "https://github.com/sbogh/digital-stethoscope/blob/main/hardware/modules/Firebase_SendAudio_Module.ino"
    click GSInfo "https://github.com/sbogh/digital-stethoscope/blob/main/digital-stethoscope/digital-stethoscope/GoogleService-Info.plist"
    click FSWrapper "https://github.com/sbogh/digital-stethoscope/blob/main/backend/firestore.py"
    click API "https://github.com/sbogh/digital-stethoscope/blob/main/backend/main.py"
    click UR "https://github.com/sbogh/digital-stethoscope/blob/main/backend/user_routes.py"
    click AuthU "https://github.com/sbogh/digital-stethoscope/blob/main/backend/auth_utils.py"
    click V "https://github.com/sbogh/digital-stethoscope/tree/main/digital-stethoscope/digital-stethoscope/Views"
    click C "https://github.com/sbogh/digital-stethoscope/tree/main/digital-stethoscope/digital-stethoscope/Controllers"
    click M "https://github.com/sbogh/digital-stethoscope/tree/main/digital-stethoscope/digital-stethoscope/Models"
    click APIConfig "https://github.com/sbogh/digital-stethoscope/blob/main/digital-stethoscope/digital-stethoscope/Config/APIConfig.swift"
    click Info "https://github.com/sbogh/digital-stethoscope/blob/main/digital-stethoscope/digital-stethoscope/Info.plist"
    click AppEntry "https://github.com/sbogh/digital-stethoscope/blob/main/digital-stethoscope/digital-stethoscope/digital_stethoscopeApp.swift"

    %% Styles
    classDef hardware fill:#e0ffe0,stroke:#2E8B57;
    classDef cloud fill:#e0f0ff,stroke:#1E90FF;
    classDef backend fill:#ffe0b3,stroke:#FF8C00;
    classDef mobile fill:#f0e6ff,stroke:#800080;
```
