System Architecture

Last reviewed: 2026-07-05

High-Level Shape

The Python Server is a single-worker orchestration process with supporting local HTTP services. Its durable architecture is a set of explicit boundaries: webapp for external worker API calls, jobs for local render-job work, unity for process and ZeroMQ protocol handling, servers for local dashboard/content HTTP apps, simulator for fake Web App behavior, monitoring for health snapshots, and config for settings.

Runtime Processes And Modules

Runtime surface	Status	Main files	Responsibility
CLI process	Implemented/Partial	`src/anuva_python_server/cli.py`	Starts commands for config, polling, manual job runs, Unity, servers, simulator, certs, and NSSM script output.
Job runner	Implemented/Partial	`src/anuva_python_server/jobs/runner.py`	Coordinates claim, prepare, render, completion, failure, cancellation, and one-active-job state.
Content server	Implemented	`src/anuva_python_server/servers/content.py`	Serves local config/assets under the worker root to Unity.
Dashboard server	Partial	`src/anuva_python_server/servers/dashboard.py`	Local operator UI and APIs for status, manual job actions, Unity actions, logs, and simulator state.
Simulator server	Implemented/Partial	`src/anuva_python_server/simulator/app.py`	FastAPI fake Web App worker API with scenarios and state machine.
Unity ZeroMQ client	Implemented	`src/anuva_python_server/unity/zmq_client.py`	Sends commands to Unity and receives status/heartbeat events.
Unity supervisor/process controller	Partial	`src/anuva_python_server/unity/supervisor.py`, `src/anuva_python_server/unity/process.py`	Starts EXE mode, waits for readiness, tracks heartbeat/render/process state, restarts/stops Unity.

Data Flow

Web App or simulator
  -> list/next queued job
  -> atomic claim
  -> job package
Python Server
  -> create worker/job workspace
  -> download assets
  -> write original and local Presentation Config
  -> write job_manifest.json
  -> serve local content URLs
  -> send render.start to Unity over ZeroMQ
Unity
  -> emit accepted/progress/completed/failed events
Python Server
  -> update Web App job status
  -> validate final.mp4
  -> generate thumbnail artifact
  -> upload MP4 through configured strategy
  -> complete/fail/cancel job

The current run CLI command does not execute this whole loop continuously. The complete lifecycle is exercised through run-manual-job, dashboard run actions, unit tests, and integration tests.

Key Dependencies

Dependency	Use	Source
FastAPI/Uvicorn	Content server, dashboard, simulator	`pyproject.toml`, `src/anuva_python_server/servers/`, `src/anuva_python_server/simulator/app.py`
httpx	Web App API calls, asset downloads, content readiness checks, S3 PUT	`src/anuva_python_server/webapp/client.py`, `src/anuva_python_server/jobs/assets.py`, `src/anuva_python_server/webapp/uploads.py`
Pydantic/Pydantic Settings	Typed models and config	`src/anuva_python_server/config/settings.py`, `src/anuva_python_server/webapp/models.py`
PyYAML	YAML config and disk simulator scenarios	`src/anuva_python_server/config/settings.py`, `src/anuva_python_server/simulator/scenarios.py`
pyzmq	Unity command/event transport	`src/anuva_python_server/unity/zmq_client.py`
psutil	Unity process and system metrics	`src/anuva_python_server/unity/process.py`, `src/anuva_python_server/monitoring/system_metrics.py`
GPUtil	GPU diagnostics with graceful unavailable state	`src/anuva_python_server/monitoring/gpu_metrics.py`
ffmpeg/ffprobe	Thumbnail generation and optional output validation	`src/anuva_python_server/jobs/output.py`
OpenSSL	Local localhost certificate generation	`src/anuva_python_server/cli.py`

External Services

Service	Status	Notes
Anuva Web App `/api/worker/v1`	External	Documented in `docs/AnuvaWeb_API_Doc.md`; client paths are configurable.
S3 or compatible storage	External	Signed S3 upload strategy is preferred for real Web App mode.
Unity Editor or Unity EXE	External	Python owns process/protocol side, not Unity render semantics.
Windows NSSM or equivalent startup	Partial	Script generation exists; interactive graphics session remains an operational requirement.

Related state maps: ModuleMap, RenderJobFlowMap, EnvAndServices.