How murtaza-nasir/speakr works
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