Architecture
============

System Components
-----------------

.. list-table:: Component responsibilities
	 :header-rows: 1
	 :class: feature-table

	 * - Component
		 - Responsibility
	 * - frontend
		 - Next.js interface for wizard flows, authentication, and visualization.
	 * - backend
		 - FastAPI endpoints, orchestration, and business logic.
	 * - database
		 - PostgreSQL persistence and schema migrations.
	 * - shared
		 - Shared Pydantic models used across services.
	 * - nginx
		 - Reverse proxy and environment-aware routing.
	 * - keycloack
		 - Identity provider and realm management.

Simplified Flow
---------------

1. The frontend calls backend endpoints.
2. The backend orchestrates extraction and computation workflows.
3. Persistent entities are stored in PostgreSQL.
4. Nginx exposes services through a unified URL.

Key Technical Points
--------------------

- The backend uses FastAPI lifespan to initialize the orchestrator.
- Background tasks run for checkpoint cleanup.
- Configuration depends heavily on environment variables.