Your Personal Code Guide for codedictate

Five nested try/except blocks make the control flow nearly impossible to follow.

try:
    try:
        try:
            result = whisper.transcribe(chunk)
        except APIError:
            try:
                result = whisper.transcribe(chunk, model="base")
            except:
                ...

app.py imports models.py, and models.py imports app.py for the db instance. This is worked around with delayed imports, making the code fragile.

# server/app.py
from server.models import User, Transcription

# server/models.py
from server.app import db  # circular!

Configuration values are spread across config.py, app.py, models.py, transcribe.py, whisper_api.py, and setup.py with sometimes conflicting defaults.

# config.py: WHISPER_MODEL = "medium"
# transcribe.py: MODEL = os.getenv("MODEL", "small")  # conflicts!
# whisper_api.py: DEFAULT_MODEL = "base"  # another conflict!

The chunking algorithm implements silence detection, overlap handling, and dynamic chunk sizing in a 120-line function with 8 local variables.

def chunk_audio(audio_data, sr=16000):
    threshold = 0.015  # magic number
    min_silence = int(sr * 0.3)  # magic number
    # ... 120 lines of sliding window logic

client/ui.py contains both GUI rendering and business logic (file selection, API calls, error handling) in a 450-line file.

class MainWindow:
    def on_record_click(self):
        # 80 lines mixing UI updates, API calls, and error handling
        self.status_label.config(text="Recording...")
        audio = self.recorder.record()
        response = requests.post(API_URL + "/upload", ...)

A single function handles audio decoding, chunking, Whisper API calls, post-processing, punctuation, and database writes — all in 380 lines.

def transcribe_and_process(audio_file, user_id, language="de"):
    # ... 380 lines of nested logic
    # audio decoding, chunking, API calls, text cleanup, DB writes

The /transcribe endpoint has 28 different decision paths through nested conditions and error handling.

@app.route("/transcribe", methods=["POST"])
def transcribe():
    if request.content_type:
        if "multipart" in request.content_type:
            if "audio" in request.files:
                # ... 15 more levels of nesting

Not a single API endpoint is tested with HTTP requests. Neither upload, transcription, nor admin routes have integration tests.

# No integration tests exist. Example of what should be:
# def test_upload_invalid_file(client):
#     response = client.post("/upload", data={"audio": (BytesIO(b"not audio"), "test.exe")})
#     assert response.status_code == 400

Test data is created inline without reusable fixtures. Every new test must write its own setup code.

# Current: no fixtures, each test duplicates setup
def test_something():
    app = create_app()  # duplicated
    db.create_all()  # duplicated
    user = User(email="test@test.com")  # duplicated

The only mock for the Whisper API returns a simplified object that doesn't match the actual API response format.

# Mock returns simplified format:
mock_whisper.return_value = {"text": "hello world"}
# Real API returns: {"text": "...", "segments": [...], "language": "de", "duration": 12.5}

The entire project has only 2 tests in a single test file. Core functionality like upload, transcription, and authentication is untested.

# tests/test_transcribe.py — ENTIRE test suite:
def test_whisper_returns_text():
    assert transcribe("hello.wav") != ""

def test_empty_audio():
    assert transcribe("empty.wav") == ""

Existing tests connect to the same database as production because no test configuration exists.

# tests/test_transcribe.py
from server.config import DATABASE_URL  # same as production!
from server.models import db

def test_save_transcription():
    db.session.add(...)  # writes to production DB!

There is no GitHub Actions, GitLab CI, or any other CI/CD configuration. Tests must be run manually.

# No CI/CD configuration files found:
# No .github/workflows/*.yml
# No .gitlab-ci.yml
# No Jenkinsfile

server/whisper_api.py is not imported by any other module. The Whisper integration is done directly in transcribe.py.

# server/whisper_api.py — 180 lines, imported by nobody
class WhisperClient:
    def __init__(self, api_key, model="medium"):
        ...
    def transcribe(self, audio_path, language="de"):
        ...

14 imported modules or functions are never used: json, sys, re in app.py, hashlib and hmac in auth.py, among others.

import json  # unused
import sys  # unused
import re  # unused
from flask import Flask, request, jsonify, redirect  # redirect unused

65 lines of commented-out WebSocket code for real-time streaming block readability without benefit.

# TODO: WebSocket streaming (v2)
# @socketio.on("audio_stream")
# def handle_stream(data):
#     chunk = data["chunk"]
#     # ... 60 more commented lines

After a return statement at line 288, there are 12 lines of code that can never execute.

    return result  # line 288

    # Dead code below — never executes:
    logger.info("Post-processing complete")
    stats.record_transcription(len(result))
    cache.set(cache_key, result)

A function migrate_v1_to_v2() in utils.py was written for a one-time data migration and is never called again.

def migrate_v1_to_v2():
    """One-time migration from v1 schema to v2. Run once, then delete."""
    # ... 40 lines of migration logic
    # Last run: 2024-08-15

except: without a specific exception catches everything including SystemExit, KeyboardInterrupt, and MemoryError.

try:
    result = process_audio(chunk)
except:  # catches EVERYTHING
    result = ""  # silently returns empty string

Multiple mutable global variables (active_jobs, cache_dict, stats_counter) are shared between requests without synchronization.

active_jobs = {}  # mutable global, shared across threads
cache_dict = {}  # mutable global, no TTL, no size limit
stats_counter = {"total": 0, "errors": 0}  # race condition!

Numeric values like 16000, 0.015, 0.3, 512 are used directly in code without explanatory constants.

audio = audio.set_frame_rate(16000)  # what is 16000?
if amplitude < 0.015:  # what threshold?
    if silence_frames > int(16000 * 0.3):  # ??

Different endpoints return errors in different formats: sometimes {"error": "..."}, sometimes {"message": "..."}, sometimes plain text.

# Endpoint A:
return jsonify({"error": "File too large"}), 400
# Endpoint B:
return jsonify({"message": "Invalid format"}), 422
# Endpoint C:
return "Server error", 500

Text fields like title and notes accept arbitrarily long strings without length restriction at the application level.

class Transcription(db.Model):
    title = db.Column(db.String)  # no length limit
    notes = db.Column(db.Text)  # no length limit

API calls to the Whisper service have no timeout, no retry, and no specific error handling. A 500 or timeout crashes the entire request handler.

response = openai.audio.transcriptions.create(
    model=WHISPER_MODEL,
    file=audio_chunk,
    language=language
)  # no timeout, no retry, no error handling

The entire project uses print() for output instead of the Python logging module. 47 print() calls spread across 6 files.

print(f"Processing file: {filename}")  # should be logger.info
print(f"ERROR: {str(e)}")  # should be logger.error
print(f"Transcription complete in {elapsed}s")  # should be logger.info

The README.md contains only "# codedictate" and a one-line description. Installation, usage, API documentation, and architecture are missing.

# codedictate
Voice-to-text dictation tool.

None of the 8 API endpoints are documented. Neither OpenAPI/Swagger nor inline docstrings describe request/response formats.

@app.route("/transcribe", methods=["POST"])
def transcribe():
    # No docstring, no type hints, no documentation
    file = request.files["audio"]
    ...

82% of functions in the project have no docstring. Only 5 of 28 functions describe what they do, what they expect, and what they return.

def chunk_audio(audio_data, sr=16000):
    # No docstring — what does it return? What format is audio_data?
    ...

def postprocess(text, language):
    # No docstring — what postprocessing? What languages supported?
    ...

There is neither a .env.example nor documentation of which environment variables are required.

# config.py uses these but nobody documents them:
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")  # required but undocumented
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///local.db")
SECRET_KEY = os.getenv("FLASK_SECRET_KEY", "dev-key-change-me")

No documentation about why certain technology decisions were made (Whisper model choice, SQLite vs. PostgreSQL, client architecture).

# No architecture documentation found.
# Questions that remain unanswered:
# - Why Whisper medium model instead of large?
# - Why SQLite instead of PostgreSQL?
# - Why desktop client instead of web-only?

The .gitignore file has no entries for .env, *.pem, *.key, or upload directories. Sensitive files could be accidentally committed.

# .gitignore (incomplete):
__pycache__/
*.pyc
# Missing: .env, *.pem, *.key, uploads/, *.sqlite

No documentation or configuration for virtual environments. Developers might install dependencies globally.

# No Makefile, no setup script, no venv documentation
# Developers are expected to... guess?
# pip install -r requirements.txt  # global? venv? who knows!

No /health or /readiness endpoint for monitoring, load balancers, or container orchestration.

# No health check endpoint exists.
# Docker and monitoring have no way to check if the app is running correctly.

The Flask SECRET_KEY has a hardcoded fallback "dev-key-change-me" that gets used in production when the environment variable is not set.

SECRET_KEY = os.getenv("FLASK_SECRET_KEY", "dev-key-change-me")  # predictable!

No code formatter (Black, Ruff) configured. The code has inconsistent indentation, line lengths, and string quoting.

# Inconsistent style throughout:
some_var="no spaces"  # line 12
other_var = "with spaces"  # line 13
very_long_function_call(argument1, argument2, argument3, argument4, argument5)  # 120+ chars

Only 8 direct dependencies are pinned but their transitive dependencies are not. pip install can install different versions on different machines.

# requirements.txt — only direct deps pinned:
Flask==2.2.3
openai==1.6.1
SQLAlchemy==2.0.25
# But what version of Jinja2? Markupsafe? Click? Unknown!

No check whether the licenses of the 8 dependencies are compatible with the planned licensing model.

# Unknown licenses in dependency tree:
# Flask — BSD-3-Clause (OK)
# openai — Apache-2.0 (OK)
# But what about transitive deps?

Flask 2.2.3 is vulnerable to session cookie manipulation (CVE-2023-30861). The current version is 3.1.x.

# requirements.txt
Flask==2.2.3  # CVE-2023-30861: session cookie vulnerability
Werkzeug==2.2.3  # also outdated, update together

The project uses setup.py instead of pyproject.toml. setup.py is being superseded by pyproject.toml per PEP 517/518.

# setup.py (deprecated pattern):
from setuptools import setup
setup(
    name="codedictate",
    version="0.1.0",
    install_requires=[...]
)

The audio upload endpoint accepts any file without checking file type, size, or content.

@app.route("/upload", methods=["POST"])
def upload_audio():
    file = request.files["audio"]
    file.save(os.path.join(UPLOAD_DIR, file.filename))

The filename is taken directly from the user without using secure_filename() or similar sanitization.

file.save(os.path.join(UPLOAD_DIR, file.filename))

CORS is configured with origins="*", allowing requests from any domain.

CORS(app, origins="*")

The OpenAI API key is hardcoded directly in the source code and gets committed to the repository with every push.

OPENAI_API_KEY = "sk-proj-abc123def456ghi789"

User input is directly interpolated into a SQL query without parameterization or escaping.

db.execute(f"SELECT * FROM transcriptions WHERE user_id = '{user_id}' AND title LIKE '%{search}%'")

Admin routes (/admin/users, /admin/stats) are accessible without any authentication whatsoever.

@app.route("/admin/users")
def admin_users():
    users = User.query.all()
    return jsonify([u.to_dict() for u in users])

The application starts with debug=True, enabling the interactive debugger and code reload in production.

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

None of the API endpoints have rate limiting implemented, neither for authentication nor for resource-intensive operations.

# No rate limiting configuration found anywhere in the project