Credit Risk Modelling Platform

A production-grade credit risk modelling platform with interactive exploration, stakeholder demos, and a production UI.

Architecture

apps/web/     → Next.js 16 (App Router, TypeScript strict) — Production UI
apps/api/     → FastAPI (Python 3.12+, async-first) — Model serving
apps/gradio/  → Gradio (stakeholder demos, HF Spaces)
shared/       → Pydantic schemas + business logic (single source of truth)
notebooks/    → Marimo (.py files only) — Developer exploration
docs/         → RFCs, ADRs, deployment guide

Architecture Diagram

graph TB
    subgraph notebooks["📓 Notebooks"]
        marimo["Marimo (.py)<br/>Exploration & Analysis"]
    end

    subgraph shared["🔗 Shared Layer"]
        schemas["Pydantic Schemas<br/>Data Models"]
        logic["Business Logic<br/>Algorithms"]
    end

    subgraph apps["📱 Applications"]
        gradio["Gradio Demo<br/>Stakeholder Feedback"]
        api["FastAPI Server<br/>Model Training & Inference"]
        web["Next.js UI<br/>Production Dashboard"]
    end

    marimo -->|imports| shared
    marimo -->|deploy to HF Spaces| gradio

    gradio -->|API calls| api
    web -->|API calls| api

    api -->|uses| shared
    api -->|reads/writes| data["💾 Model Data<br/>Predictions & Artifacts"]

    shared -.->|syncs with| web

    style marimo fill:#ffffcc
    style gradio fill:#ffe6e6
    style web fill:#e6f3ff
    style api fill:#e6ffe6
    style shared fill:#f0e6ff

Loading

UI progression: Marimo (explore) → Gradio (validate) → Next.js (ship)

Quick Start

# Install dependencies
uv sync --extra api --extra dev

# Start API (no auth)
uv run uvicorn apps.api.main:app --reload

# Start API (with auth)
CREDIT_RISK_REQUIRE_AUTH=true CREDIT_RISK_API_KEYS=my-key uv run uvicorn apps.api.main:app --reload

# Start Next.js UI
cd apps/web && npm install && npm run dev

# Start Gradio demo
uv run python -m apps.gradio.app

API Endpoints

Method	Path	Auth	Description
GET	/health	No	Health check
POST	/auth/verify	Yes	Verify API key
POST	/train	Yes	Train a model
POST	/predict	Yes	Make predictions
GET	/models	No	List models
GET	/models/{id}	No	Get model metadata
GET	/models/{id}/results	No	Get training results
POST	/models/{id}/persist	Yes	Persist model to disk

Documentation

Document	Description
RFCs	Architecture proposals and design specs
ADRs	Architecture decision records
Deployment Guide	Cloud Run deployment instructions
Environment Variables	Configuration reference

Contributing

1. Create a feature branch: git checkout -b feature/description
2. Use conventional commits: feat(scope): description
3. Run tests: uv run pytest && npm test
4. Run linting: uv run ruff check . && npm run lint
5. Push and create a PR

References

• Credit Risk Modeling in Python (Datacamp) — Methodology and data
• Threshold-Moving for Imbalanced Classification — Youden's J statistic

License

OpenRAIL