tts-voice-creator-clone-and-design-2/PROJECT_MAP.md

Project map

Living index of where things are and what state they are in. Update in the same commit as the change it describes.

Current phase

Magazine projects, P0 and P1 complete (frontend reachable at Studio → Magazines). Audiobook/Rehearser/voice-library features are mature and in daily use.

Deployment

Self-hosted Docker on the DGX Spark, port 7890, image ghcr.io/martin-b78/tts-voice-creator-clone-and-design-2. Python and static files are bind-mounted, so code changes need only a container recreate; rebuild and push only when Dockerfile or requirements.txt change.

Layout

Path	Role
server.py	FastAPI app, router registration, auth middleware
core/	domain logic — config, database, audio, voice, routing, magazine
routes/	HTTP boundary, one module per feature area
static/js/	frontend, one module per feature area (no build step for most)
tests/	test_*.py (unittest) and *.spec.js (Playwright)
architecture/	SOPs for subsystems whose design is not obvious from code
workflows/	ComfyUI graphs for character portrait generation

Feature areas

Area	Server	Frontend	State
Voice library / clone / design	routes/library.py, core/voice.py	library.js	mature
Read Aloud (books, PDFs)	routes/reader.py	reader.js	mature
Audiobook casting	routes/conversation.py	audiobook*.js	mature
Rehearser	routes/rehearsals_db.py	rehearser-*.js	mature
Studio (phase wizard)	—	studio.js	mature
TTS engines / routing	routes/tts.py, core/routing.py	engines.js	mature
STT	routes/stt.py	—	mature
Magazines	core/magazine.py, routes/magazine.py	magazine.js, s-magazine.html	P0 + P1

Data model

Documents (books and magazines alike) live under <CONFIG_DIR>/reader_library/<doc_id>/, discriminated by meta.json → kind:

• kind: "pdf" / text — Read Aloud book. Text is extracted in the browser and not persisted; meta.json holds counts and a flat idx resume position.
• kind: "magazine" — adds layout.json, articles.json, pages/, images/, podcast/, and a per-article progress map. See architecture/magazine-ingestion.md.

Settings, presets, routes and the SQLite database also live under CONFIG_DIR, which is the writable volume.

Environment

Variable	Purpose
CONFIG_DIR	writable state (settings, library, database)
VOICES_DIR / OUTPUT_DIR	voice WAV library
TTS_CONTAINER_NAMES	containers restarted after a voice change
DOCKER_HOST	points at the socket proxy; the raw socket is not mounted
llm_url / llm_model / llm_api_key	settings.json, OpenAI-compatible LLM

Pending decisions

• Container registry: ghcr costs quota against a private package (≈427 MB per push, 500 MB free on the Free plan). Local registry vs. ghcr vs. no re-pull is unresolved — the compose files currently point at ghcr.

Known limitations

• gitea backup remote is 157 commits behind origin; main tracks gitea.
• Magazine sidebar exclusion is a narrow-column geometry heuristic (mark_sidebars), not certain — review always shows every sidebar block.
• Magazine word-level highlighting is a character-length estimate against real measured audio duration, not true forced alignment.
• No formal cross-engine OCR accuracy benchmark exists (two engines wired: ocr-baidu-unlimited-ocr primary, KDL Frontier Parser nano fallback).
• No npm run qa aggregate command yet; Python tests run via unittest, browser tests via playwright test.
• The app has no authentication for the browser UI and no per-user data isolation — single-tenant/LAN-trust only (one global settings/database/voice library, no accounts). See architecture/multi-tenant-and-identity.md and TODO.md's "Deferred — public multi-user readiness" section.

Next logical step

Magazine P2 per TODO.md: image descriptions, table/chart handling, EPUB 3 Media Overlay export, and a formal OCR-engine benchmark (see architecture/magazine-ingestion.md).