# isfopo/soniscribe architecture

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

- Interactive diagram: https://gitdiagram.com/isfopo/soniscribe
- Repository: https://github.com/isfopo/soniscribe

## Overview

##### Project Type & Purpose
- Single-Page Application (SPA) built in React + TypeScript and bundled with Vite.
- Purpose: a browser-based audio transcription assistant (“SoniScribe”) that lets users drop audio files, play/back them, annotate waveforms, save “projects” to the local file system, and later revisit or export transcripts.

##### High-Level File‐Structure Analysis
Top-Level
- index.html, public/ → static entry point
- vite.config.ts, tsconfig*.json, package*.json, eslint.config.js → build & lint config
src/
- components/ → all UI building blocks (AudioPlayer, WaveformView, FileDropArea, Dialogs, Button, SubdivisionSelector, Transport, ProjectList)
- views/ → page‐level containers (ProjectView)
- hooks/ → reusable React hooks for cross-cutting concerns (useFileSystem, usePeaks, useProjects, etc.)
- stores/ → global application state using Zustand (dialogs.ts, settings.ts)
- helpers/ → pure utilities for file I/O, object ops, point/subdivision math
- theme/ → theming JSON + hook

##### Key README Insights
- Client runs over HTTPS (File System API requirement); Microsoft Dev Tunnels used in dev for HTTPS.
- No built-in backend—everything is client side, with data persisted via File System API.
- npm scripts for dev, build, preview, tunnel.

- Browser/Client – hosts the SPA, provides File System & Media APIs
- React App Shell – entry point (main.tsx → App.tsx)
- Presentation Layer – src/components + src/views
- State Layer – src/stores (Zustand)
- Logic Layer – src/hooks + src/helpers
- Theming Layer – theme.json + useTheme hook
- Build/Serve Layer – Vite server → HTTP/HTTPS
b. Relationships & Data Flow
1) User drags/drops an audio file → FileDropArea
2) FileDropArea invokes useFileSystem hook → writes/reads project directory via Browser File System API
3) File metadata passed to stores (useProjects) → triggers UI update in ProjectList & ProjectView
4) AudioPlayer & WaveformView request peaks (usePeaks/h e l p e r s/points) → render waveforms
5) Transport component controls playback (Media API) → AudioPlayer
6) DialogManager (store + Dialog components) orchestrates modals (e.g., for export)
c. Architectural Patterns & Principles
- Component-Based UI (React) with CSS Modules for scoping
- Unidirectional Data Flow via Zustand stores & custom hooks
- Separation of Concerns: UI vs. state vs. business logic vs. filesystem ops vs. theming
- Progressive Enhancement: runs on HTTPS only due to File System API
d. Key Technologies & Frameworks
- React 18 + TypeScript
- Vite for fast bundling & dev server
- Zustand for global state
- Browser File System Access API (via useFileSystem)
- Custom React Hooks & CSS Modules

##### Essential Elements to Capture
- App entry: index.html → main.tsx → App.tsx
- Module breakdown: components | views | hooks | stores | helpers | theme
- State propagation via Zustand (dialog & settings stores)
- File System API interactions for project persistence
- Media API usage for playback & waveform analysis
- Vite dev/build pipeline and HTTPS requirement

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Browser Layer
    User["User"]:::user
    Browser["Browser (HTTPS)"]:::api

    User -->|interacts via UI| Browser

    %% Build/Serve Layer
    subgraph "Build & Serve" 
        direction TB
        Vite["vite.config.ts"]:::build
        TSConfigs["tsconfig*.json"]:::build
        ESLint["eslint.config.js"]:::build
        Packages["package*.json"]:::build
    end

    Browser -->|loads| IndexHTML["index.html"]:::build
    IndexHTML --> Main["src/main.tsx"]:::build
    Main --> AppShell["src/App.tsx"]:::frontend

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        AudioPlayer["src/components/AudioPlayer"]:::frontend
        WaveformView["src/components/WaveformView"]:::frontend
        FileDropArea["src/components/FileDropArea"]:::frontend
        Button["src/components/Button"]:::frontend
        Dialog["src/components/Dialogs/Dialog"]:::frontend
        DialogManager["src/components/Dialogs/Dialog/DialogManager"]:::frontend
        DragAndDropDialog["src/components/Dialogs/DragAndDropDialog"]:::frontend
        SubdivisionSelector["src/components/SubdivisionSelector"]:::frontend
        Transport["src/components/Transport"]:::frontend
        ProjectList["src/components/ProjectList"]:::frontend
        ProjectView["src/views/ProjectView"]:::frontend
    end

    AppShell -->|renders| FileDropArea
    AppShell -->|renders| ProjectView

    FileDropArea -->|drops file| useFS
    ProjectView --> ProjectList
    ProjectView --> AudioPlayer
    ProjectView --> WaveformView
    ProjectView --> Transport
    ProjectView --> SubdivisionSelector
    ProjectView --> Button
    ProjectView --> Dialog
    ProjectView --> DragAndDropDialog
    ProjectView --> DialogManager

    %% State Layer
    subgraph "State Layer (Zustand)" 
        direction TB
        DialogStore["dialogs.ts"]:::store
        SettingsStore["settings.ts"]:::store
    end

    DialogStore --> DialogManager
    SettingsStore --> AppShell
    useFS --> SettingsStore
    ProjectList --> SettingsStore

    %% Logic Layer (Hooks)
    subgraph "Logic Layer (Hooks)" 
        direction TB
        useFS["useFileSystem"]:::logic
        useProjects["useProjects"]:::logic
        usePeaks["usePeaks"]:::logic
        useEventListener["useEventListener"]:::logic
        useMediaQuery["useMediaQuery"]:::logic
        useKeyPress["useKeyPress"]:::logic
        useTheme["useTheme"]:::logic
    end

    FileDropArea --> useFS
    AudioPlayer --> usePeaks
    WaveformView --> usePeaks
    useFS -->|reads/writes| FileSystemAPI
    useProjects --> SettingsStore
    useEventListener --> DialogManager
    useMediaQuery --> AppShell
    useKeyPress --> Transport
    AppShell --> useTheme

    %% Helper Utilities Layer
    subgraph "Helper Utilities" 
        direction TB
        FilesHelper["src/helpers/files.ts"]:::logic
        ObjectsHelper["src/helpers/objects.ts"]:::logic
        PointsHelper["src/helpers/points.ts"]:::logic
        SubdivHelper["src/helpers/subdivisions.ts"]:::logic
    end

    useFS --> FilesHelper
    useProjects --> ObjectsHelper
    usePeaks --> PointsHelper
    SubdivisionSelector --> SubdivHelper

    %% Theming Layer
    subgraph "Theming Layer" 
        direction TB
        ThemeDef["src/theme/theme.json"]:::theme
        ThemeHook["src/theme/useTheme.tsx"]:::theme
    end

    useTheme --> ThemeDef
    AppShell --> ThemeHook

    %% Browser APIs
    subgraph "Browser APIs" 
        direction TB
        FileSystemAPI["File System API"]:::api
        MediaAPI["Media API"]:::api
    end

    Transport --> MediaAPI
    AudioPlayer --> MediaAPI

    %% Click Events
    click IndexHTML "https://github.com/isfopo/soniscribe/blob/main/index.html"
    click Main "https://github.com/isfopo/soniscribe/blob/main/src/main.tsx"
    click AppShell "https://github.com/isfopo/soniscribe/blob/main/src/App.tsx"
    click AudioPlayer "https://github.com/isfopo/soniscribe/blob/main/src/components/AudioPlayer/index.tsx"
    click WaveformView "https://github.com/isfopo/soniscribe/blob/main/src/components/WaveformView/index.tsx"
    click FileDropArea "https://github.com/isfopo/soniscribe/blob/main/src/components/FileDropArea/index.tsx"
    click Button "https://github.com/isfopo/soniscribe/blob/main/src/components/Button/index.tsx"
    click Dialog "https://github.com/isfopo/soniscribe/blob/main/src/components/Dialogs/Dialog/index.tsx"
    click DialogManager "https://github.com/isfopo/soniscribe/blob/main/src/components/Dialogs/Dialog/DialogManager/index.tsx"
    click DragAndDropDialog "https://github.com/isfopo/soniscribe/blob/main/src/components/Dialogs/DragAndDropDialog/index.tsx"
    click SubdivisionSelector "https://github.com/isfopo/soniscribe/blob/main/src/components/SubdivisionSelector/index.tsx"
    click Transport "https://github.com/isfopo/soniscribe/blob/main/src/components/Transport/index.tsx"
    click ProjectList "https://github.com/isfopo/soniscribe/blob/main/src/components/ProjectList/index.tsx"
    click ProjectView "https://github.com/isfopo/soniscribe/blob/main/src/views/ProjectView/index.tsx"
    click DialogStore "https://github.com/isfopo/soniscribe/blob/main/src/stores/dialogs.ts"
    click SettingsStore "https://github.com/isfopo/soniscribe/blob/main/src/stores/settings.ts"
    click useFS "https://github.com/isfopo/soniscribe/blob/main/src/hooks/useFileSystem.tsx"
    click useProjects "https://github.com/isfopo/soniscribe/blob/main/src/hooks/useProjects.tsx"
    click usePeaks "https://github.com/isfopo/soniscribe/blob/main/src/hooks/usePeaks.tsx"
    click useEventListener "https://github.com/isfopo/soniscribe/blob/main/src/hooks/useEventListener.tsx"
    click useMediaQuery "https://github.com/isfopo/soniscribe/blob/main/src/hooks/useMediaQuery.tsx"
    click useKeyPress "https://github.com/isfopo/soniscribe/blob/main/src/hooks/useKeyPress.tsx"
    click FilesHelper "https://github.com/isfopo/soniscribe/blob/main/src/helpers/files.ts"
    click ObjectsHelper "https://github.com/isfopo/soniscribe/blob/main/src/helpers/objects.ts"
    click PointsHelper "https://github.com/isfopo/soniscribe/blob/main/src/helpers/points.ts"
    click SubdivHelper "https://github.com/isfopo/soniscribe/blob/main/src/helpers/subdivisions.ts"
    click ThemeDef "https://github.com/isfopo/soniscribe/blob/main/src/theme/theme.json"
    click ThemeHook "https://github.com/isfopo/soniscribe/blob/main/src/theme/useTheme.tsx"
    click Vite "https://github.com/isfopo/soniscribe/blob/main/vite.config.ts"
    click TSConfigs "https://github.com/isfopo/soniscribe/blob/main/tsconfig.json"
    click ESLint "https://github.com/isfopo/soniscribe/blob/main/eslint.config.js"
    click Packages "https://github.com/isfopo/soniscribe/blob/main/package.json"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#2b5797,stroke-width:1px
    classDef store fill:#d9ead3,stroke:#38761d,stroke-width:1px
    classDef logic fill:#f9cb9c,stroke:#b45f06,stroke-width:1px
    classDef api fill:#ffe599,stroke:#bf9000,stroke-width:1px
    classDef build fill:#d0e0e3,stroke:#134f5c,stroke-width:1px
    classDef theme fill:#ead1dc,stroke:#741b47,stroke-width:1px
    classDef user fill:#f4cccc,stroke:#990000,stroke-width:1px
```
