How ananya-ys/churnguard-ai works
1. Overall shape
- ChurnGuard AI is a split full-stack system: a React/Vite frontend and a FastAPI backend.
- The backend owns all business logic, persistence, ML inference, background jobs, and auth.
- Runtime dependencies are PostgreSQL for durable state, Redis for Celery broker/cache-style coordination, and Celery workers for asynchronous ML tasks.
2. Frontend boundary
- The frontend is a single-page app built with React 18 and served through nginx in production.
- UI routes map to a few product areas: Dashboard, Predict, Batch Upload, Models, Jobs, and Login.
- All API access is centralized in src/api.js, so the frontend is a thin client and does not contain domain logic.
3. HTTP/API layer in the backend
- FastAPI routes live under backend/app/api/v1/endpoints/.
- The API is organized by domain: auth, predict, upload, jobs, models, experiments, ab_tests, drift, metrics, audit_logs, health, and explain.
- router.py assembles the versioned API surface, while middleware and error handlers in app/core/ provide shared cross-cutting behavior.
4. Backend internal layering
- The backend uses a clean separation:
- API endpoints: request/response translation
- Services: business rules and orchestration
- Repositories: database access
- ORM models: SQLAlchemy entities
- Schemas: Pydantic contracts
- This layering makes the backend easy to diagram as a pipeline from HTTP → service logic → repository/DB, with ML and task execution branching off where needed.
5. Authentication and security
- Auth is handled by auth_service, dependencies/auth.py, and security helpers in core/security.py.
- The system uses JWT-based auth and Argon2 password hashing.
- RBAC is present in tests and likely enforced through dependencies/middleware, so authenticated identity is a first-class concern across the API.
6. Core application state
- Persistent entities include users, model versions, prediction jobs, drift reports, experiments, A/B tests, and audit logs.
- These map to SQLAlchemy models and dedicated repositories, indicating that most product features are stored and queried from PostgreSQL rather than computed on the fly.
- Alembic migrations define the schema evolution, with 0001_initial_schema and 0002_phases_1_6 showing the system has grown in phases.
7. Prediction and ML inference path
- Online prediction is handled by predict_service and the ML package under app/ml/.
- The ML subsystem includes a pipeline singleton, explainer, training script, and a prebuilt artifact store (app/ml/artifacts/v1.pkl).
- The expected flow is: frontend submits features → FastAPI validates input → prediction service loads the active model → result is returned and likely logged/audited.
8. Batch processing and asynchronous jobs
- Batch uploads do not appear to run inline; they create a prediction job and are processed asynchronously.
- Celery tasks in app/tasks/ cover batch_predict, drift_check, retrain, and the worker entrypoint.
- Redis acts as the coordination layer for these jobs, while PostgreSQL stores job state and results for the Jobs UI to poll.
9. Drift, retraining, and model lifecycle
- The architecture includes explicit support for model drift detection and retraining.
- drift_service, drift_repository, and tasks/drift_check.py indicate scheduled or triggered monitoring of prediction quality/data shift.
- model_service and the Models UI support model registration and promotion, so model lifecycle is a managed backend workflow rather than a manual file swap.
10. Experiments and A/B tests
- There are dedicated subsystems for experiments and A/B testing, with services, repositories, and API endpoints for both.
- This suggests the platform can compare model variants or controlled rollout strategies, storing outcomes in the database and exposing them through the API.
- These features sit beside the main inference path, not inside it, which is important for diagramming feature experimentation as an orthogonal capability.
11. Observability and auditability
- The backend includes metrics, logging, audit logs, and a health endpoint.
- Prometheus and Grafana provisioning under infra/ show a real monitoring stack rather than ad hoc logs.
- Audit logs are a separate persisted domain, which implies user actions and model operations are meant to be traceable.
12. Deployment and orchestration
- docker-compose.yml is the main local orchestrator: PostgreSQL, Redis, migrations, FastAPI app, Celery worker/beat, Flower, and the React frontend.
- The frontend container uses nginx to serve static assets and proxy API traffic.
- The backend uses Docker and Alembic; CI is defined in GitHub Actions, and the repo includes deployment guidance for cloud hosting.
13. Testing and verification
- The backend has layered tests: unit, integration, security, concurrency, and smoke.
- This mirrors the architecture: business logic can be tested independently from the HTTP layer, while auth and concurrency are verified where the system is stateful and async.
- CI is therefore likely validating the full pipeline from API behavior to model/infrastructure assumptions.
14. How to draw the main data flows
- Primary synchronous flow: Browser → Frontend → FastAPI endpoint → Service → Repository → PostgreSQL / ML pipeline → response.
- Primary asynchronous flow: Frontend upload/API request → job record in PostgreSQL → Celery task via Redis → worker processes batch/drift/retrain → results persisted back to PostgreSQL.
- Monitoring flow: app metrics/logs → Prometheus/Grafana, with audit logs stored in the database for domain-level traceability.
Main entry points: endpoints API Endpoints · core Core · tasks Celery Tasks · App.jsx React App
Components 22
Frontend
React/Vite SPA served by nginx in production.
- Browser · End user entrypoint for the SPA.
- React App · Single-page frontend with product pages and shared layout.
frontend/src/App.jsx - API Client · Centralized frontend API access layer.
frontend/src/api.js - Nginx · Serves the built frontend and fronts the app in production.
frontend/nginx.conf
Backend
FastAPI application with layered business logic and persistence.
- API Router · Assembles the versioned HTTP surface.
backend/app/api/v1/router.py - API Endpoints · Domain routes for auth, predict, upload, jobs, models, experiments, drift, metrics, audit, health, and explain.
backend/app/api/v1/endpoints - Core · Shared config, database, middleware, errors, logging, metrics, cache, and security helpers.
backend/app/core - Auth Service · JWT auth, password hashing, and user identity handling.
backend/app/services/auth_service.py - Predict Service · Online prediction orchestration and model invocation.
backend/app/services/predict_service.py - Batch Service · Creates and coordinates asynchronous batch prediction work.
backend/app/services/batch_service.py - Model Service · Manages model registration, promotion, and active version selection.
backend/app/services/model_service.py - Drift Service · Detects drift and coordinates monitoring workflows.
backend/app/services/drift_service.py - Experiment Service · Handles experiments and A/B test orchestration.
backend/app/services/experiment_service.py - Repositories · Persistence layer for users, jobs, models, drift reports, experiments, AB tests, and audit logs.
backend/app/repositories - Schemas · Pydantic request and response models.
backend/app/schemas - ORM Models · Persistent domain entities mapped to PostgreSQL.
backend/app/models - ML Pipeline · Model pipeline, explainer, training, and stored artifact loading.
backend/app/ml/pipeline.py - Celery Tasks · Background workers for batch prediction, drift checks, and retraining.
backend/app/tasks
Runtime
External state and async infrastructure used by the app.
- PostgreSQL · Durable storage for users, jobs, models, experiments, drift reports, and logs.
- Redis · Celery broker and coordination store.
Ops
Monitoring and deployment tooling.
- Prometheus · Collects application and infrastructure metrics.
infra/prometheus/prometheus.yml - Grafana · Operational dashboards and visualization.
infra/grafana/dashboards/churnguard.json
Connections 24
- Browser → Nginx: uses · Users access the frontend through production serving.
- Nginx → React App: serves · Nginx serves the compiled React app.
- React App → API Client: calls · UI actions use the centralized API client.
- API Client → API Router: HTTP · Frontend API requests hit the versioned backend surface.
- API Router → API Endpoints: routes · Router assembles domain endpoints.
- API Endpoints → Schemas: validates · Endpoints use request and response contracts.
- API Endpoints → Auth Service: auth · Authentication routes and dependencies delegate to the auth service.
- API Endpoints → Predict Service: predict · Online prediction requests flow into the inference service.
- API Endpoints → Batch Service: jobs · Batch upload and job routes create async work.
- API Endpoints → Model Service: models · Model management routes call the model lifecycle service.
- API Endpoints → Drift Service: drift · Drift routes expose monitoring workflows.
- API Endpoints → Experiment Service: experiments · Experiment and A/B test routes use the experiment service.
- Auth Service → Core: security · Auth depends on shared security and error handling.
- Predict Service → ML Pipeline: infer · Prediction service loads and executes the ML pipeline.
- Batch Service → Celery Tasks: enqueue · Batch requests schedule asynchronous tasks.
- Drift Service → Celery Tasks: schedule · Drift monitoring can be executed by background workers.
- Celery Tasks → Redis: broker · Celery uses Redis for coordination and delivery.
- Celery Tasks → PostgreSQL: persist · Workers write outcomes and job state back to the database.
- Repositories → PostgreSQL: reads/writes · Repositories encapsulate PostgreSQL access.
- ORM Models → PostgreSQL: maps to · ORM entities represent durable database rows.
- Core → PostgreSQL: db · Shared database session and config support persistence.
- Core → Redis: cache/broker · Shared cache and queue coordination live here.
- Core → Prometheus: metrics · Application metrics are exposed for scraping.
- Prometheus → Grafana: visualizes · Grafana dashboards consume Prometheus metrics.