OpenParable
Skip to content
← Back to skills

Architecture Review

Testing & Quality
architecture-review

Architecture Review is an Agent Skill for testing & quality published in the fossasia/voxbento repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use this skill to evaluate proposed architecture changes against VoxBento's design principles.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/fossasia/voxbento/blob/HEAD/.agents/skills/architecture-review/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/architecture-review, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Skill: Architecture Review

Use this skill to evaluate proposed architecture changes against VoxBento's design principles.


Fundamental Architecture Principles

  1. Browser-first media. Audio never touches the Python process. Browser → WHIP → MediaMTX → WHEP → listener browser.
  2. FastAPI is coordination only. Routes, WebSocket signalling, auth, admin. No audio processing.
  3. Jitsi is monitoring only. Interpreters watch/hear the floor session. It is not the ingest path.
  4. Single publisher per channel. Enforced at two layers: Python (BoothRegistry.set_active_interpreter) and MediaMTX (overridePublisher: yes).
  5. In-memory booth state. BoothRegistry is module-level in portal/booth_state.py. No external state store yet (see TD-03 in TECHNICAL_DEBT_REPORT.md).

Component Responsibilities (strict boundaries)

ComponentDoesDoes NOT do
FastAPI portalRoutes, auth, admin, WS coordination, DB queriesAudio processing, transcoding, media relay
MediaMTXWHIP ingest, WHEP playback, RTSP for ffmpegAuth, coordination, UI
Jitsi MeetFloor session monitoring (receive-only iframe)Audio ingest, interpreter publishing
Browser JSWebRTC/WHIP, WebSocket, Jitsi iframe, mic meterServer-side logic, DB access
ffmpeg (spawned)PCM extraction from RTSP for transcriptionAnything else
Transcription providersText from PCM audioMedia relay, broadcast, DB write

Evaluating Proposed Changes

Does this introduce a new dependency?

  • Check if it's already in pyproject.toml.
  • Ask: can this be done with existing FastAPI/SQLAlchemy/httpx capabilities?
  • New Python dependencies → run uv add {pkg} (not pip); never edit uv.lock manually.

Does this add server-side audio processing?

  • STOP. Audio must not flow through the Python process.
  • Route audio directly: browser → MediaMTX → listener.
  • If transcription is needed: use the existing portal/transcription/ subsystem.

Does this add a frontend framework?

  • STOP. Frontend is plain ES modules. No Vue, React, jQuery, build step.
  • See .github/instructions/js.instructions.md for JavaScript conventions.

Does this require a new DB column?

  • Add to portal/models.py with proper Mapped typing.
  • Create an Alembic migration in alembic/versions/.
  • For SQLite compatibility: use batch_alter_table in the migration (see migration 008 as reference).

Does this change the WebSocket protocol?

  • The protocol is used by static/js/interpreter-booth.js — both files must change together.
  • New message types must be handled in portal/websockets/manager.py ws_booth loop + _handle_* function.
  • Role enforcement: role is always from session.granted_role, never from client data['role'].

Does this change auth?

  • Three separate token types exist (session_token, user_token, admin_token). Do not conflate.
  • All tokens use HS256 with settings.effective_jwt_secret.
  • WebSocket auth: cookies are read at connect time and stored in Session.granted_role.

Red Flags in Architecture Proposals

ProposalRisk
"Add a WebSocket message to send audio data"Violates browser-first principle
"Use Redis for real-time booth state"Valid but requires careful migration of BoothRegistry
"Add a REST endpoint that returns the JWT secret"Security violation
"Encode the role in the WebSocket join message and trust it"Violates role trust model
"Store all session data in a cookie"Risk of cookie size limits + replay attacks
"Add Vue for the admin panel"Violates no-framework constraint
"Use aiortc for SFU"Explicitly forbidden in invariants
"Proxy WHIP through FastAPI"Breaks browser-first media architecture

Good Architecture Patterns in This Codebase

  • safe_redirect(url) — validates redirects to prevent open redirect attacks. Use it for all redirects.
  • _ensure_mediamtx_path(channel_id) — creates alwaysAvailable paths. Call before returning WHIP URL.
  • asyncio.Lock in BoothRegistry — all booth mutations serialized. Prevents race conditions.
  • Lazy DB engine init — _get_engine() in portal/database.py defers connection until first use.
  • from __future__ import annotations — deferred evaluation prevents circular import issues.
  • Fernet encryption for API keys — SHA-256 derived key, supports key rotation via MultiFernet.