VoiceStudio/docs/STRUCTURE.md

Project Structure

Every folder has a single job. Every file at the root earns its place.

Layout

OmniVoice/
│
├── README.md                    ⟵ user-facing overview
├── CHANGELOG.md                 ⟵ release history
├── LICENSE
│
├── pyproject.toml               ⟵ Python project manifest
├── uv.lock                      ⟵ Python lockfile
├── package.json                 ⟵ monorepo manifest (Bun workspaces + Turborepo)
├── bun.lock                     ⟵ JS lockfile
├── turbo.json                   ⟵ turborepo pipeline
│
├── .dockerignore                ⟵ Docker build context filter
├── backend.spec                 ⟵ pyinstaller spec (stays at root by pyinstaller convention)
├── alembic.ini                  ⟵ DB migration config (stays at root by alembic convention)
│
├── .env                         ⟵ user config; gitignored, .env.example is the template
├── .gitignore
│
├── backend/                     ⟵ FastAPI server
│   ├── main.py
│   ├── api/routers/             HTTP endpoints (thin)
│   ├── core/                    config, db, task queue, metrics
│   ├── services/                business logic
│   └── schemas/                 pydantic request/response shapes
│
├── frontend/                    ⟵ React 19 + Vite + Tauri desktop
│   ├── src/
│   │   ├── pages/               one file per top-level view
│   │   ├── components/          reusable UI
│   │   ├── api/                 typed API clients
│   │   ├── store/               Zustand slices
│   │   ├── hooks/               custom React hooks
│   │   └── utils/
│   ├── src-tauri/               Rust desktop shell
│   └── public/
│
├── omnivoice/                   ⟵ the underlying TTS model package
│   ├── models/
│   ├── cli/                     CLI entry points (omnivoice-infer, etc.)
│   ├── data/                    data utilities used by the model
│   ├── eval/                    evaluation scripts
│   ├── scripts/                 one-off utilities that ship with the package
│   ├── training/
│   └── utils/
│
├── tests/                       ⟵ all tests live here, no exceptions
│   ├── conftest.py
│   ├── test_api.py
│   ├── test_dub_*.py
│   ├── test_job_queue.py
│   ├── test_segmentation.py
│   └── frontend/                Node-based frontend tests
│
├── scripts/                     ⟵ dev / build / release shell + python scripts
│   ├── install.sh               universal installer
│   ├── run.sh                   universal launcher
│   ├── smoke-test.sh            end-to-end validation
│   └── desktop-prod.sh          production desktop build
│
├── deploy/                      ⟵ Docker deployment configs
│   ├── Dockerfile               single-stage CUDA image
│   └── docker-compose.yml       one-click local deployment
│
├── docs/                        ⟵ developer docs, screenshots, branding
│   ├── ROADMAP.md               where this project is going
│   ├── STRUCTURE.md             you are here
│   ├── mcp.json                 MCP config template
│   ├── preview.png              README hero image
│   ├── logo.png, logo.svg       branding assets
│   ├── screenshot-*.png         feature screenshots
│   ├── languages.md
│   ├── training.md
│   ├── data_preparation.md
│   ├── evaluation.md
│   └── voice-design.md
│
├── design/                      ⟵ ASCII mockups of the target UX
│   ├── README.md
│   └── 00–08-*.md               per-feature specs
│
├── research/                    ⟵ reference material, competitor analysis, archived code
│   ├── LEARNINGS.md             competitive analysis, what to absorb
│   ├── TheWhisper/              vendored reference (read-only)
│   ├── voice-pro/               vendored reference
│   └── legacy_gradio/           archived Gradio UI (pre-React rewrite)
│
├── examples/                    ⟵ runnable demos + sample inputs
│
├── omnivoice_data/              ⟵ Docker bind-mount target (gitignored)
│                                   DB + HF cache live here when running via compose
│
└── .git/

Rules of the root

1. Nothing at the root is a runtime artifact. Outputs, temp files, local DBs, crash logs — all go to ~/Library/Application Support/OmniVoice/ (or the OS equivalent), never into the repo. The one exception is omnivoice_data/, which exists as a bind-mount anchor for Docker.

2. No ad-hoc scripts at the root. One-off debug scripts live in scripts/. Tests live in tests/. Benchmarks live in scripts/benchmarks/ (when we create them).

3. Each subdirectory owns one concern. If you can't describe what goes in a directory in one sentence, it's wrong.

4. Every package has a manifest. backend/, frontend/, omnivoice/ each have their own deps declared via pyproject.toml / package.json — they are independently testable.

What lives where

Kind of thing	Goes in
User-facing product code	backend/, frontend/
The TTS model (independent of the studio)	omnivoice/
Everything executable but not user-facing	scripts/
Tests	tests/
Developer + user docs (Markdown)	docs/
Target-state mockups	design/
Competitor clones, legacy code, ref material	research/
Runnable demos and sample data	examples/
Runtime data (never committed)	~/Library/Application Support/OmniVoice/ on Mac

What doesn't live at the root anymore

Removed in the cleanup pass:

File	Why it was there	Where it went
test_crash.py, test_server.py, test_whisper.py, test_mock.py, test_pyannote.py	One-off debug scripts from an April 14 crash investigation. Imported symbols that no longer exist after the router refactor.	Deleted (already gitignored, referenced dead code).
benchmark.py	Another stale debug script; imported backend.main._get_db which no longer exists.	Deleted.
output.wav, test.wav	Runtime artifacts.	Deleted / moved out.
crash_log.txt	Runtime log. Now written to $DATA_DIR/crash_log.txt.	Deleted.
omnivoice.zip (148 MB)	Offline reference archive of the project itself.	Moved out of the repo to ../omnivoice.zip.bak.
data/	Only contained .DS_Store.	Deleted.
legacy_gradio/	The pre-React Gradio UI. Kept for historical reference.	Archived to research/legacy_gradio/.
Scattered .DS_Store files	macOS Finder droppings.	Deleted from every non-ignored directory.

Scaling path (proposed, not yet executed)

The current flat layout works fine for the current size. If the project grows to include additional apps (a mobile companion, a plugin SDK, multiple backends), migrate to a Turborepo-style monorepo:

OmniVoice/
├── apps/
│   ├── api/                 ← was backend/
│   ├── web/                 ← was frontend/
│   └── desktop/             ← could extract src-tauri/ here later
├── packages/
│   ├── omnivoice-model/     ← was omnivoice/
│   └── tts-adapters/        ← new; the pluggable TTS interface from ROADMAP phase 3
├── config/
│   ├── docker/
│   └── pyinstaller/
├── tests/
├── docs/
├── design/
└── research/

Do not execute this migration without a dedicated PR. It breaks:

• pyproject.toml [tool.hatch.build.targets.{sdist,wheel}] paths
• package.json workspaces and scripts
• turbo.json, Dockerfile, docker-compose.yml paths
• backend.spec (['backend/main.py'], pathex=['.'])
• frontend/src-tauri/tauri.*.conf.json sidecar paths
• every import that reads from backend.main import … (tests, scripts)

Migrate when adding the second apps/* or the second packages/*. Not before.

Conventions

• Filenames: snake_case for Python, kebab-case or PascalCase for JS/TS components, lowercase for Markdown.
• Tests mirror source paths. backend/services/dub_pipeline.py → tests/services/test_dub_pipeline.py.
• One-off scripts go into scripts/ with a descriptive name, not test_*.py at the root.
• New top-level directories require a PR that updates this file.