Skill: Repo Navigation
Use this skill to find files, understand module ownership, and locate code in VoxBento.
Module Map (Quick Reference)
| What you're looking for |
Where to look |
| Route definition for any URL |
portal/routers/ — search for @router.get, @app.post, @app.websocket |
| Auth logic (JWT, cookies, role) |
portal/auth.py |
| Booth state / participant logic |
portal/booth_state.py |
| Database models (table schema) |
portal/models.py |
| Database CRUD helpers |
portal/database.py |
| Booth ID / MediaMTX path math |
portal/booth_identity.py |
| Role permissions |
portal/roles.py |
| App settings / env vars |
portal/config.py |
| API key encryption / decryption |
portal/crypto.py |
| Transcription provider logic |
portal/transcription/providers/{provider}.py |
| Worker lifecycle (start/stop) |
portal/transcription/worker.py |
| Caption aggregation |
portal/transcription/aggregator.py |
| Interpreter UI (JS) |
static/js/interpreter-booth.js |
| Listener WHEP client (JS) |
static/js/whep-listener.js |
| Admin JS |
static/js/admin.js |
| HTML templates |
templates/ (base, booth, listener, auth) + templates/admin/ |
| DB migrations |
alembic/versions/001_*.py through 008_*.py |
| MediaMTX configuration |
mediamtx.yml |
| Docker services |
docker-compose.yml |
| Tests |
tests/ — see test file map below |
Test File Map
| Test file |
What it covers |
tests/conftest.py |
anyio fixture, sys.path setup |
tests/test_fastapi_app.py |
HTTP routes, auth flows, page renders |
tests/test_booth_state.py |
BoothRegistry in-memory logic |
tests/test_booth_identity.py |
make_booth_id, make_mediamtx_path, validation |
tests/test_database.py |
CRUD helpers with in-memory SQLite |
tests/test_database_e2e.py |
End-to-end database flows |
tests/test_admin_panel.py |
Admin route auth and operations |
tests/test_roles.py |
Permission enum, ROLE_PERMISSIONS |
tests/test_crypto.py |
encrypt_val / decrypt_val |
tests/test_user_auth.py |
Registration, login, user token |
tests/test_join_flow.py |
Invite token redemption → JWT cookie |
tests/test_memberships_tokens.py |
Membership and token CRUD |
tests/test_transcription_concurrency.py |
Worker start/stop, concurrency limits |
tests/docker_e2e_test.py |
Full Docker stack smoke tests |
tests/verify_persistence.py |
DB persistence checks |
Searching Effectively
Find all routes
grep -rn "@router\." portal/routers/
Find where a WS message type is handled
grep -rn "booth:join\|booth:chat\|booth:set-active" portal/websockets/
Find all settings
grep -rn "settings\." portal/ | head -40
Find all auth cookie checks
grep -rn "session_token\|user_token\|admin_token" portal/routers/
Find where a DB model is used
grep -rn "DBBooth\|InviteToken\|BoothMembership" portal/
File Size Guide
| File |
~Lines |
Complexity |
portal/routers/ |
Various |
High |
portal/database.py |
~400 |
Medium |
portal/models.py |
~250 |
Medium |
portal/booth_state.py |
~300 |
Medium |
portal/auth.py |
~230 |
Medium |
static/js/interpreter-booth.js |
~900 |
High — use search |
portal/transcription/worker.py |
~130 |
Low |
portal/transcription/aggregator.py |
~120 |
Low |
Navigation Tips
- **Routes are split into sub-modules in
portal/routers/.
- Admin routes all start with
/admin/ and use dependencies=[Depends(require_admin)].
- WebSocket handlers are
_handle_join, _handle_leave, _handle_chat, _handle_set_active, _handle_update_state — all in portal/websockets/handlers.py.
- The in-memory
booths variable is a module-level BoothRegistry() instance in portal/booth_state.py — the only source of live booth state.
- Templates inherit from
templates/base.html (user pages) or templates/admin/base.html (admin pages).
1---2name: repo-navigation3description: Use this skill to find files, understand module ownership, and locate code in VoxBento.4---56# Skill: Repo Navigation78> Use this skill to find files, understand module ownership, and locate code in VoxBento.910---1112## Module Map (Quick Reference)1314| What you're looking for | Where to look |15|---|---|16| Route definition for any URL | `portal/routers/` — search for `@router.get`, `@app.post`, `@app.websocket` |17| Auth logic (JWT, cookies, role) | `portal/auth.py` |18| Booth state / participant logic | `portal/booth_state.py` |19| Database models (table schema) | `portal/models.py` |20| Database CRUD helpers | `portal/database.py` |21| Booth ID / MediaMTX path math | `portal/booth_identity.py` |22| Role permissions | `portal/roles.py` |23| App settings / env vars | `portal/config.py` |24| API key encryption / decryption | `portal/crypto.py` |25| Transcription provider logic | `portal/transcription/providers/{provider}.py` |26| Worker lifecycle (start/stop) | `portal/transcription/worker.py` |27| Caption aggregation | `portal/transcription/aggregator.py` |28| Interpreter UI (JS) | `static/js/interpreter-booth.js` |29| Listener WHEP client (JS) | `static/js/whep-listener.js` |30| Admin JS | `static/js/admin.js` |31| HTML templates | `templates/` (base, booth, listener, auth) + `templates/admin/` |32| DB migrations | `alembic/versions/001_*.py` through `008_*.py` |33| MediaMTX configuration | `mediamtx.yml` |34| Docker services | `docker-compose.yml` |35| Tests | `tests/` — see test file map below |3637---3839## Test File Map4041| Test file | What it covers |42|---|---|43| `tests/conftest.py` | anyio fixture, sys.path setup |44| `tests/test_fastapi_app.py` | HTTP routes, auth flows, page renders |45| `tests/test_booth_state.py` | `BoothRegistry` in-memory logic |46| `tests/test_booth_identity.py` | `make_booth_id`, `make_mediamtx_path`, validation |47| `tests/test_database.py` | CRUD helpers with in-memory SQLite |48| `tests/test_database_e2e.py` | End-to-end database flows |49| `tests/test_admin_panel.py` | Admin route auth and operations |50| `tests/test_roles.py` | `Permission` enum, `ROLE_PERMISSIONS` |51| `tests/test_crypto.py` | `encrypt_val` / `decrypt_val` |52| `tests/test_user_auth.py` | Registration, login, user token |53| `tests/test_join_flow.py` | Invite token redemption → JWT cookie |54| `tests/test_memberships_tokens.py` | Membership and token CRUD |55| `tests/test_transcription_concurrency.py` | Worker start/stop, concurrency limits |56| `tests/docker_e2e_test.py` | Full Docker stack smoke tests |57| `tests/verify_persistence.py` | DB persistence checks |5859---6061## Searching Effectively6263### Find all routes64```bash65grep -rn "@router\." portal/routers/66```6768### Find where a WS message type is handled69```bash70grep -rn "booth:join\|booth:chat\|booth:set-active" portal/websockets/71```7273### Find all settings74```bash75grep -rn "settings\." portal/ | head -4076```7778### Find all auth cookie checks79```bash80grep -rn "session_token\|user_token\|admin_token" portal/routers/81```8283### Find where a DB model is used84```bash85grep -rn "DBBooth\|InviteToken\|BoothMembership" portal/86```8788---8990## File Size Guide9192| File | ~Lines | Complexity |93|---|---|---|94| `portal/routers/` | Various | High |95| `portal/database.py` | ~400 | Medium |96| `portal/models.py` | ~250 | Medium |97| `portal/booth_state.py` | ~300 | Medium |98| `portal/auth.py` | ~230 | Medium |99| `static/js/interpreter-booth.js` | ~900 | High — use search |100| `portal/transcription/worker.py` | ~130 | Low |101| `portal/transcription/aggregator.py` | ~120 | Low |102103---104105## Navigation Tips1061071. **Routes are split into sub-modules in `portal/routers/`.1082. **Admin routes** all start with `/admin/` and use `dependencies=[Depends(require_admin)]`.1093. **WebSocket handlers** are `_handle_join`, `_handle_leave`, `_handle_chat`, `_handle_set_active`, `_handle_update_state` — all in `portal/websockets/handlers.py`.1104. **The in-memory `booths` variable** is a module-level `BoothRegistry()` instance in `portal/booth_state.py` — the only source of live booth state.1115. **Templates inherit from** `templates/base.html` (user pages) or `templates/admin/base.html` (admin pages).
fossasia