Financial Desk · Multi-Tenant Case Platform & Gateway

Managing High-Volume Institutional Arbitration Across Competing Lenders

IO2i provides dispute resolution and arbitration management operations to commercial banks and NBFCs across India. In high-volume dispute operations, institutional legal teams manage large caseloads and require structured operational visibility across the entire dispute lifecycle: intake schedules, physical notice dispatch tracking, arbitrator appointment, hearing sessions, and certified award uploads.

Financial Desk was designed to resolve several key operational and architectural challenges in dispute management:

• Centralized Case Management: Legal operations teams handling multiple dispute portfolios require a structured interface for case lifecycles rather than fragmented file transfers and manual tracking sheets.
• Automated Document Generation: Preparing dispute notices and legal claims manually introduces data transcription errors across arbitrator names, loan account numbers (LANs), and claim figures.
• Unified Case Visibility: Operations teams require a consolidated interface to inspect notice delivery progress, advocate assignments, hearing schedules, and certified award documents.
• Strict Multi-Tenant Isolation: Commercial lenders operate competing portfolios under strict confidentiality agreements. Institution A must never view, query, or infer claims, borrower identities, arbitrator allocations, or counsel rosters belonging to Institution B.

Deploying dedicated server instances and independent database clusters for every client increases infrastructure cost and operational maintenance overhead. Conversely, a shared database relying solely on manual WHERE tenant_id = ... query filters introduces significant risk of cross-tenant data leaks if a filter condition is accidentally omitted.

Full-Stack Case-Operations Client & Tenant-Aware Gateway

I built the frontend client and the backend gateway service for Financial Desk from scratch, establishing a clear separation between our delivery platform and upstream business systems:

End-to-End Request Flow: Leptos, Nginx, FastAPI & Upstream Frappe

Financial Desk operates as a stateless proxy gateway. The incoming domain identifies the tenant, the gateway dynamically injects the tenant's distinct API keys, and the upstream Frappe ERP executes queries strictly within that institution's database boundary:

[ Institutional Browser Client (e.g. bank-a.firmportal.in) ]
                             │
                             ▼ (HTTPS Request)
┌────────────────────────────────────────────────────────────────────────┐
│ NGINX Edge Reverse Proxy (TLS Termination)                             │
│ • Serves compiled Rust/Leptos WebAssembly SPA bundle (CSR)             │
│ • Enforces client_max_body_size and passes X-Forwarded-Host header     │
│ • Proxies /api/* requests to internal Uvicorn ASGI socket              │
└────────────────────────────────────────────────────────────────────────┘
                             │
                             ▼ (Internal HTTP)
┌────────────────────────────────────────────────────────────────────────┐
│ FastAPI Gateway Service (Python 3.12 / AsyncIO)                        │
│ 1. Logging Middleware: Injects X-Request-ID (UUID4) for tracing        │
│ 2. Security Headers: Applies CSP, HSTS, X-Frame-Options: DENY          │
│ 3. Tenant Middleware:                                                  │
│    • Resolves hostname via in-memory _tenant_by_host cache             │
│    • Sets ContextVar: _current_tenant.set(tenant_config)               │
│ 4. Session Middleware: Validates HMAC-signed bearer session token      │
│ 5. API Client (lwt_api_client.py):                                     │
│    • Reads current_tenant ContextVar                                   │
│    • Signs outbound request with tenant.api_key & tenant.api_secret    │
└────────────────────────────────────────────────────────────────────────┘
                             │
                             ▼ (Outbound HTTPS with Tenant Token)
┌────────────────────────────────────────────────────────────────────────┐
│ Upstream Frappe ODR Core Services                                      │
│ • Authenticates tenant API key/secret                                  │
│ • Executes queries against isolated MariaDB/PostgreSQL database        │
│ • Enforces business workflows and returns JSON case records            │
└────────────────────────────────────────────────────────────────────────┘

Implementation Decisions Backed by Source Code

from contextvars import ContextVar
from dataclasses import dataclass
from fastapi import Request, HTTPException
from fastapi.responses import JSONResponse

@dataclass(frozen=True)
class TenantConfig:
    host: str
    tenant_code: str
    lwt_base_url: str
    api_key: str
    api_secret: str
    bulk_base_url: str
    bulk_api_key: str

# ContextVar scoped strictly to the current asynchronous coroutine
_current_tenant: ContextVar[TenantConfig | None] = ContextVar("current_tenant", default=None)

@app.middleware("http")
async def bind_tenant_context(request: Request, call_next):
    # Exclude non-tenant endpoints
    if request.url.path in {"/health", "/metrics", "/docs", "/openapi.json"}:
        return await call_next(request)

    try:
        tenant = await resolve_request_tenant(request)
    except HTTPException as exc:
        return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})

    request.state.tenant = tenant
    token = _current_tenant.set(tenant)
    try:
        response = await call_next(request)
        return response
    finally:
        # Guarantee cleanup even on unhandled exceptions
        _current_tenant.reset(token)

import hmac, hashlib, socket, time, json

def _request_signature(timestamp: str) -> str:
    message = f"{timestamp}:GET:{_central_url()}:{socket.gethostname()}"
    return hmac.new(_central_secret().encode(), message.encode(), hashlib.sha256).hexdigest()

async def refresh_tenant_registry() -> None:
    ts = str(int(time.time()))
    headers = {
        "x-timestamp": ts,
        "x-signature": _request_signature(ts),
        "x-host-node": socket.gethostname(),
    }
    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.get(_central_url(), headers=headers)
        resp.raise_for_status()
        payload = resp.json()
        
    # Atomically swap in-memory tenant registry
    new_registry = { _normalize_host(row["host"]): _coalesce_tenant_row(row) for row in payload["tenants"] }
    global _tenant_by_host
    _tenant_by_host = new_registry

Observed Technical Constraints & How They Were Resolved

Containerized Delivery & Telemetry

Financial Desk is packaged as a multi-container Docker Compose deployment managed behind an Nginx reverse proxy on Linux hosts:

Architectural Trade-Offs & Next Iterations