Stage Router

A full-stack, containerized application designed to manage live stage plots, automate audio routing, and track hardware endpoints for theatrical productions and live events.

Built with a focus on strict data validation, test-driven development, and modular 2D spatial interfaces.

Quick Start

The entire environment is containerized. You do not need Node or Python installed on your host machine to run the application.

1. Clone the repository:

   git clone https://git.sunokaj3.com/daniel/stagerouter.git
   cd stagerouter
   

2. Set your Pre-Shared Key (Optional but recommended): The application is secured via a Pre-Shared Key (PSK). By default, it is set to coro. You can override this by exporting an environment variable before starting Docker:

   export STAGE_ROUTER_PSK="your_custom_password"
   

3. Spin up the stack:

   docker compose up -d --build
   

4. Access the Application:

   • Frontend UI: http://localhost:13000
   • Backend API Docs: http://localhost:18080/docs

Architecture Stack

• Frontend: React, Vite, @dnd-kit/core (Drag and Drop)
• Backend: Python 3.11, FastAPI, SQLModel (SQLite)
• Testing: Pytest (Unit/Coverage), Newman (API Contract Testing)
• DevOps: Docker Compose, Forgejo Actions (CI Pipeline)

Security Model

This application uses a stateless Pre-Shared Key (PSK) authentication model.

• The backend protects all /api/v1/ endpoints by looking for the X-Stage-Key header.
• The frontend intercepts unauthenticated traffic, presents a full-screen login prompt, and securely stores the key in localStorage to append to future Axios requests.

Testing Strategy

The project maintains a strict 100% test coverage requirement for core routing logic and API endpoints.

Backend Unit Tests: Pytest

Run the Python white-box tests and generate a coverage report:

docker compose exec backend python -m pytest --cov=. --cov-report=term-missing -v

API Contract Tests: Newman

Run the Postman black-box tests against the live Docker network to verify HTTP routing and JSON serialization:

docker compose exec e2e-tests npx newman run /tests/api/stage_router.postman_collection.json -e /tests/api/docker.postman_environment.json

Frontend Linting: ESLint

Ensure React best practices and prevent cascading render loops:

docker compose exec frontend npx eslint src/**/*.jsx

Continuous Integration (CI)

This repository includes a .forgejo/workflows/ci.yml pipeline. Upon every push or pull request to the main branch, the Forgejo runner will automatically:

1. Check frontend code syntax using ESLint.
2. Run Pytest and fail the build if coverage drops below 95%.
3. Spin up the Docker stack and run Newman contract tests against the live API.

Project Structure

stagerouter/
├── backend/
│   ├── main.py              # FastAPI application and routing
│   ├── models.py            # SQLModel schemas and database entities
│   ├── routing.py           # Core audio routing math and logic
│   ├── tests/               # Pytest suite
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── App.jsx          # Master DndContext and state manager
│   │   ├── api/client.js    # Axios instance with PSK interceptor
│   │   └── components/      # React components (Performer, Snake, Login)
│   └── package.json
├── tests/                   # End-to-End and Contract testing assets
│   └── api/                 # Postman collections and environments
├── .forgejo/workflows/      # CI/CD Pipeline definitions
└── docker-compose.yml       # Infrastructure orchestration

License

This project is licensed under the MIT License - see the LICENSE file for details.