How isfopo/soniscribe works
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