# us-trustee-program/bankruptcy-oversight-support-systems architecture

> Architecture diagram of the GitHub repository us-trustee-program/bankruptcy-oversight-support-systems, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/us-trustee-program/bankruptcy-oversight-support-systems
- Repository: https://github.com/us-trustee-program/bankruptcy-oversight-support-systems

## Overview

##### Project Type and Purpose
- This is a full-stack case management system (CAMS) for the U.S. Trustee Program.
- It consists of:
– A React-based single-page application (user-interface).
– A suite of Azure Functions (backend) exposing HTTP and queue endpoints.
– Common shared TypeScript libraries (common, dev-tools).
– Infrastructure as code (Bicep) under ops/cloud-deployment.
– End-to-end, unit, DAST and accessibility test pipelines in GitHub Actions.

##### File Structure
- Top-level directories:
– user-interface: frontend React app, tests, Playwright e2e config, static web assets.
– backend: Azure Function Apps (api and dataflows), shared adapters, controllers, use-cases, gateways.
– common: domain and API utilities shared across frontend & backend.
– dev-tools: scripts for data generation, cosmos records, API key creation.
– ops/cloud-deployment: Bicep templates for Azure resources (Function Apps, Cosmos DB, SQL DB, Storage Queues, App Insights, Key Vault, VNETs).
– test: DAST and e2e test harnesses.

##### README
- Confirms full-stack case management system for USTP.
- Points to extensive architecture docs under docs/architecture.

##### Main Components
a. User Layer
– Browser (React SPA).
– CDN / Azure Static Web App.

b. Identity & Security
– Okta Authorization Server (OAuth2).
– Azure Key Vault (secrets for functions).
– Feature flags (App Configuration or custom feature-flag service).

c. API Layer
– Azure Function App “api”:
- HTTP-triggered functions (cases, courts, orders, me, healthcheck, etc.).
- Auth middleware (Okta gateway).
– Azure Function App “dataflows”:
- Timer or queue-triggered functions for batch migrations and event processing.
- Storage Queues as triggers and outputs.

d. Business Logic Layer
– Controllers invoke Use-Cases.
– Use-Cases coordinate gateways and domain logic.
– Adapters/Gateways for data access:
- Cosmos DB (Mongo API) repositories.
- ACMS and DXTR external systems via REST.
- SQL Database healthchecks.
- Azure Storage queues.

e. Persistence Layer
– Cosmos DB for cases, notes, users’ sessions, runtime state.
– Azure SQL DB for ancillary health checks.
– Storage Queues for inter-function communication.

f. Observability & Monitoring
– Azure Application Insights for telemetry (function logs, performance).
– GitHub Actions for CI/CD, DAST, SCA scans, e2e tests.

g. Infrastructure
– Bicep templates under ops/cloud-deployment define resource groups, VNETs, private endpoints, networking, Key Vault, Managed Identity, App Insights, Cosmos DB, SQL, Storage Accounts, Function Apps, Web Apps.

##### Relationships & Data Flow
1. User → Browser SPA → API via HTTPS
2. Browser authenticates via Okta → receives tokens.
3. Functions API verifies token via Okta gateway.
4. API function invokes controller → use-case → gateway → Cosmos DB or external system.
5. Dataflows functions triggered by queue or timer → update data in Cosmos or send messages to other queues.
6. App Insights collects logs/metrics.
7. GitHub Actions deploys Bicep templates and application code to Azure.

##### Architectural Patterns & Design Principles
- Clean Architecture (controllers → use-cases → gateways).
- Serverless microservices (Azure Functions).
- Domain-driven modules in common library.
- Infrastructure as Code (Bicep).
- CI/CD pipelines via GitHub Actions reusable workflows.
- Test pyramid: unit tests (lib, common), integration (functions), e2e (Playwright), security (DAST/SCA).

##### Final Checklist
- Components: Browser SPA, Okta, Static Web App, Function Apps (api, dataflows), Cosmos DB, SQL DB, Storage Queues, App Insights, Key Vault, ACMS/DXTR external systems.
- Data flows: HTTP, Queue, Timer.
- Auth flow: OAuth2 via Okta.
- Infra layers: VNET/private endpoints for DB access.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "Presentation Layer"
        Browser["Browser (React SPA)"]:::frontend
        StaticWeb["Azure Static Web App (CDN)"]:::frontend
    end

    %% Identity & Security
    subgraph "Identity & Security"
        Okta["Okta Authorization Server"]:::external
        KeyVault["Azure Key Vault"]:::external
        FeatureFlagsShared["Feature Flags (common)"]:::external
        FeatureFlagsFront["Feature Flags (frontend)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        APIApp["Function App: api"]:::api
        AuthMiddleware["Auth Middleware"]:::api
        OAuthMock["Mock OAuth2 Function"]:::api
        HealthCosmos["Healthcheck Cosmos"]:::api
        HealthSQL["Healthcheck SQL"]:::api
    end

    %% Dataflows Layer
    subgraph "Dataflows Layer"
        DataflowsApp["Function App: dataflows"]:::api
        Timer["Timer Trigger"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Controllers["Controllers"]:::logic
        UseCases["Use Cases"]:::logic
        CommonLib["Common Domain/API Lib"]:::logic
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        CosmosRepo["Cosmos DB Repository"]:::db
        SQLClient["Abstract MSSQL Client"]:::db
        QueueGateway["Storage Queue Gateway"]:::db
        ACMSGateway["ACMS Gateway"]:::external
        DXTRGateway["DXTR Gateway"]:::external
        CosmosDB["Azure Cosmos DB"]:::db
        SQLDB["Azure SQL DB"]:::db
        StorageQueues["Azure Storage Queues"]:::db
    end

    %% Observability & CI/CD
    subgraph "Observability & CI/CD"
        AppInsights["Application Insights"]:::infra
        GitHubActions["GitHub Actions"]:::infra
        DevTools["Dev Tools"]:::infra
    end

    %% Infrastructure as Code
    subgraph "Infrastructure (IaC)"
        Bicep["Bicep Templates"]:::infra
    end

    %% Connections
    Browser --> StaticWeb
    StaticWeb -->|"HTTPS"| APIApp
    Browser -.->|"OAuth2"| Okta
    APIApp --> AuthMiddleware
    APIApp --> OAuthMock
    APIApp --> HealthCosmos
    APIApp --> HealthSQL
    APIApp --> Controllers
    Controllers --> UseCases
    UseCases --> CosmosRepo
    UseCases --> SQLClient
    UseCases --> QueueGateway
    UseCases --> ACMSGateway
    UseCases --> DXTRGateway

    StorageQueues -->|"QueueTrigger"| DataflowsApp
    Timer -->|"TimerTrigger"| DataflowsApp
    DataflowsApp --> CosmosRepo
    DataflowsApp --> QueueGateway

    APIApp -->|"logs/metrics"| AppInsights
    DataflowsApp -->|"logs/metrics"| AppInsights

    GitHubActions --> Bicep
    GitHubActions --> APIApp
    GitHubActions --> DataflowsApp
    GitHubActions --> StaticWeb
    GitHubActions --> DevTools

    Bicep --> CosmosDB
    Bicep --> SQLDB
    Bicep --> StorageQueues
    Bicep --> APIApp
    Bicep --> DataflowsApp
    Bicep --> StaticWeb
    Bicep --> KeyVault
    Bicep --> AppInsights

    CommonLib --> Controllers
    CommonLib --> Browser
    DevTools --> CosmosDB
    DevTools --> StorageQueues

    %% Click Events
    click Browser "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/user-interface/"
    click StaticWeb "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/user-interface/"
    click Okta "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/lib/adapters/gateways/okta/okta-gateway.ts"
    click KeyVault "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/ops/cloud-deployment/"
    click FeatureFlagsShared "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/common/src/feature-flags.ts"
    click FeatureFlagsFront "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/user-interface/src/configuration/featureFlagConfiguration.ts"
    click APIApp "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/backend/function-apps/api/"
    click AuthMiddleware "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/function-apps/api/host.json"
    click OAuthMock "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/function-apps/api/oauth2/mock-oauth2.function.ts"
    click HealthCosmos "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/function-apps/api/healthcheck/healthcheck.db.cosmos.ts"
    click HealthSQL "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/function-apps/api/healthcheck/healthcheck.db.sql.ts"
    click DataflowsApp "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/backend/function-apps/dataflows/"
    click Controllers "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/backend/lib/controllers/"
    click UseCases "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/backend/lib/use-cases/"
    click CosmosRepo "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/backend/lib/adapters/gateways/mongo/"
    click SQLClient "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/lib/adapters/gateways/abstract-mssql-client.ts"
    click QueueGateway "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/lib/adapters/gateways/storage-queue/storage-queue-gateway.ts"
    click ACMSGateway "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/lib/adapters/gateways/acms/acms.gateway.ts"
    click DXTRGateway "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/backend/lib/adapters/gateways/dxtr/"
    click AppInsights "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/blob/main/backend/function-apps/azure/app-insights.ts"
    click GitHubActions "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/.github/workflows/"
    click CommonLib "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/common/src/"
    click DevTools "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/dev-tools/"
    click Bicep "https://github.com/us-trustee-program/bankruptcy-oversight-support-systems/tree/main/ops/cloud-deployment/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#4385F5,color:#000
    classDef api fill:#FFE0B2,stroke:#FF9800,color:#000
    classDef logic fill:#FFF4C1,stroke:#FBC02D,color:#000
    classDef db fill:#C8E6C9,stroke:#4CAF50,color:#000
    classDef external fill:#E1BEE7,stroke:#9C27B0,color:#000
    classDef infra fill:#ECEFF1,stroke:#607D8B,color:#000
```
