How rajat-wyrm/intelliview-orchestrator works
1. System shape
- IntelliView is split into four runtime domains: a Next.js dashboard, a FastAPI orchestrator API, Celery-based worker processes, and a monitoring stack built around Prometheus/Grafana.
- Redis sits in the middle as shared cache, queue/broker, and coordination layer; PostgreSQL is the durable source of truth for application state.
2. Frontend boundary
- The frontend/ app is a Next.js 14 single-page dashboard with route-based pages for overview, sessions, interview, candidates, workers, analytics, and settings.
- UI state is split between reusable components and client-side hooks such as WebSocket subscription, keyboard navigation, debounce, toast handling, and token hydration.
- The frontend’s main job is read-heavy visualization plus a few authenticated mutation actions through the backend API.
3. Backend orchestration boundary
- orchestrator/main.py is the FastAPI entrypoint and exposes the REST API used by the dashboard and automation clients.
- The orchestrator layer is not doing heavy AI or media processing itself; instead it coordinates sessions, worker assignment, validation, retries, and state synchronization.
- Key responsibilities are separated into focused managers such as session_manager, candidate_manager, worker_registry, load_balancer, scheduler, fault_manager, and health_monitor.
4. Session lifecycle as the core data flow
- The main business flow is: start interview session → schedule work → stream updates → store state → display status on dashboard.
- Session and candidate state are tracked in the orchestrator, persisted in PostgreSQL, cached in Redis, and pushed live to the frontend through WebSockets.
- Session tracking and moment tracking are first-class concerns, indicating the app is designed around real-time interview execution rather than batch reporting.
5. Worker execution layer
- workers/ contains the distributed processing side: video_pipeline, audio_pipeline, evaluation_pipeline, and risk_engine.
- worker_agent and worker_entrypoint suggest each worker node runs independently, registers itself, and pulls/executes tasks from the broker.
- Celery is the execution substrate, with Redis acting as broker/backend coordination for asynchronous processing.
6. AI/provider abstraction
- AI behavior is intentionally decoupled from the UI and orchestrator via worker-side modules such as ai_client and evaluation_pipeline.
- The README indicates multiple model providers with fallback behavior: Gemini, Grok, and OpenAI.
- This means provider switching is an architectural concern inside the processing tier, not exposed as separate user-facing services.
7. State, caching, and resiliency
- database/ holds SQLAlchemy models and database access, while orchestrator/http_cache.py, redis_client.py, retry_manager.py, and rate_limiter.py show a deliberate split between durable state and transient operational state.
- Redis is treated as a fault-prone dependency with resilience patterns like circuit breaking, caching, and retries.
- The presence of request_validation.py, audit_logger.py, and logging_config.py points to a controlled API boundary with compliance-oriented logging.
8. Realtime update path
- monitoring/websocket_manager.py and frontend useWebSocket/dashboard components indicate live updates are pushed from backend to browser rather than polled.
- This path is used for session progress, worker heartbeats, health updates, and interview events.
- The frontend’s sidebar/topbar/session detail components are built to reflect fast-changing state such as status, risk, and pipeline stage.
9. Monitoring and observability subsystem
- monitoring/ is a separate subsystem with Prometheus metrics collection and Grafana provisioning.
- There is also a monitoring dashboard API and static dashboard page, which suggests internal operational visibility beyond the main product UI.
- Metrics are exposed through the backend and scraped by Prometheus, while Grafana renders the operational dashboards.
10. Data persistence and schema
- PostgreSQL is the authoritative persistence layer for sessions, candidates, worker state, and historical records.
- SQLAlchemy 2.0 is the ORM layer, and the tests include a migration compatibility check, indicating schema evolution is part of the architecture.
- Database writes are the durable record; Redis and in-memory state are treated as ephemeral coordination.
11. Operational controls
- The backend includes load balancing, worker registry, heartbeat/health monitoring, fault management, and scheduler components, showing the system is designed for distributed execution with dynamic capacity.
- Rate limiting and authentication tokens protect sensitive mutations such as starting interviews and submitting answers.
- The dashboard also includes a screen-lock feature and settings for token management and strategy switching, which are application-level controls around operational use.
12. Deployment and environment model
- The repo is designed to run with Docker Compose as a multi-container stack: frontend, API, Redis, PostgreSQL, Prometheus, and Grafana.
- Environment variables control external service integration and security-sensitive values such as API tokens, AI keys, Redis URL, and PostgreSQL SSL mode.
- This makes the deployment boundary explicit: the app is containerized, infrastructure-aware, and externally configurable.
13. Testing and contract boundaries
- The tests are structured around architectural seams: API contract tests, session manager tests, worker registry tests, load balancer tests, risk engine tests, and smoke/e2e tests.
- That test layout mirrors the subsystem boundaries and suggests the codebase is organized around behavior at service edges rather than a monolith of mixed concerns.
14. How to draw the architecture
- Place the dashboard on the left, the FastAPI orchestrator in the center, Redis/PostgreSQL beneath or beside it as shared infrastructure, and the worker pool on the right.
- Add a separate observability lane for Prometheus/Grafana and a real-time lane for WebSocket updates from backend to frontend.
- The key arrows are: frontend API calls to orchestrator, orchestrator state changes to PostgreSQL/Redis, orchestrator task dispatch to workers, workers returning results/state, and metrics flowing to monitoring.
Main entry points: main.py FastAPI API · app Next.js UI · worker_registry.py Coordination Core · session_manager.py Session Flow
Components 17
Dashboard
Next.js user-facing dashboard and client state
- Next.js UI · Route-based dashboard for overview, sessions, interview, candidates, workers, analytics, and settings
frontend/src/app - Client State · WebSocket, token hydration, keyboard navigation, debounce, and toast/session UI state
frontend/src/hooks - UI Components · Reusable dashboard surfaces such as sidebar, topbar, session detail, lock, and palette
frontend/src/components
API Orchestrator
FastAPI control plane for sessions, coordination, and state sync
- FastAPI API · REST entrypoint for dashboard and automation clients
orchestrator/main.py - Session Flow · Starts interviews, tracks lifecycle, and coordinates session state
orchestrator/session_manager.py - Coordination Core · Candidate management, worker registry, load balancing, scheduling, fault handling, and health checks
orchestrator/worker_registry.py - State Sync · Redis-backed cache, retries, rate limiting, request validation, and live synchronization
orchestrator/state_sync.py
Worker Pool
Distributed Celery execution and AI processing
- Celery Runtime · Asynchronous execution substrate for worker tasks
workers/celery_app.py - Worker Agent · Registers worker nodes and executes distributed jobs
workers/worker_agent.py - Pipelines · Video, audio, evaluation, and risk processing stages
workers/video_pipeline.py - AI Providers · Provider abstraction with Gemini, Grok, and OpenAI fallback behavior
workers/ai_client.py
Shared Infra
Persistent and transient infrastructure services
- Postgres Layer · SQLAlchemy models and durable application persistence
database/models.py - Redis Layer · Shared cache, queue/broker, and coordination backend
orchestrator/redis_client.py
Observability
Metrics, dashboards, and operational visibility
- Metrics API · Metrics collection and dashboard API for operational visibility
monitoring/dashboard_api.py - Live Updates · Backend websocket fanout for session, worker, and health events
monitoring/websocket_manager.py - Prometheus · Scrapes exported metrics from the application stack
monitoring/prometheus.yml - Grafana · Provisioned dashboards and datasources for ops visibility
monitoring/grafana/provisioning/dashboards/dashboard.yml
Connections 21
- Next.js UI → FastAPI API: REST calls · Dashboard reads and authenticated mutations go through the API
- Next.js UI → Live Updates: live feed · UI subscribes to real-time updates for sessions and health
- Client State → Next.js UI: UI behavior · Hooks provide hydration, navigation, debounce, and toast flow
- UI Components → Next.js UI: rendering · Shared components assemble the dashboard screens
- FastAPI API → Session Flow: session ops · Entrypoint delegates interview lifecycle control
- FastAPI API → Coordination Core: control ops · API exposes worker, scheduling, and health coordination actions
- FastAPI API → State Sync: state access · API boundary applies validation, rate limiting, retries, and cache sync
- Session Flow → Postgres Layer: persist · Session and candidate state are stored durably
- Session Flow → Redis Layer: cache state · Session progress and transient coordination use Redis
- Coordination Core → Redis Layer: broker/coordination · Worker registry, scheduling, and load balancing coordinate through Redis
- Coordination Core → Postgres Layer: state writes · Worker and candidate state updates are recorded in Postgres
- Coordination Core → Celery Runtime: dispatch · Tasks are scheduled onto the asynchronous execution layer
- Celery Runtime → Worker Agent: execute · Workers consume tasks from the broker/runtime
- Worker Agent → Pipelines: run pipelines · Worker nodes execute video, audio, evaluation, and risk stages
- Pipelines → AI Providers: model calls · Processing stages invoke provider abstractions for AI behavior
- Pipelines → Postgres Layer: results · Processed outputs and state updates are persisted
- Live Updates → Next.js UI: push updates · Live events are pushed to the browser UI
- Metrics API → Prometheus: expose metrics · Application metrics are scraped by Prometheus
- Prometheus → Grafana: visualize · Grafana renders the collected operational metrics
- FastAPI API → Metrics API: export stats · Backend exposes operational telemetry through the monitoring subsystem
- Worker Agent → Live Updates: events · Worker heartbeats and pipeline progress feed the realtime channel