# ustaxcourt/ustc-payment-portal architecture

> Architecture diagram of the GitHub repository ustaxcourt/ustc-payment-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ustaxcourt/ustc-payment-portal
- Repository: https://github.com/ustaxcourt/ustc-payment-portal

## Overview

USTC Payment Portal is a service that accepts payment requests from USTC applications, authorizes them, and brokers SOAP calls to Pay.gov while tracking transaction state. The primary workflow is initiate a collection, redirect the user to Pay.gov, then process the returned token; clients can also fetch current payment details. The README documents these flows, while sampled source confirms the Lambda request boundary, permission lookup, fee resolution, SOAP transport, and persistence. Reporting and health capabilities are represented from the source tree; their internal wiring was not sampled.

Main entry points: [`src/handlers/lambdaHandler.ts`](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/handlers/lambdaHandler.ts) (Lambda API boundary), [`src/useCases/initPayment.ts`](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/useCases/initPayment.ts) (Initiate payment), [`src/entities/SoapRequest.ts`](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/entities/SoapRequest.ts) (SOAP request transport), [`src/db/TransactionModel.ts`](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/db/TransactionModel.ts) (Transaction model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_portal["Lambda API boundary<br/>[lambdaHandler.ts]"]
  node_identity["Caller identity"]
  node_permissions["Client permissions"]
  node_validation["Request validation"]
end

subgraph group_payments["Payment lifecycle"]
  node_fee["Fee catalog<br/>[fees.ts]"]
  node_init["Initiate payment<br/>[initPayment.ts]"]
  node_process["Process payment<br/>[processPayment.ts]"]
  node_details["Payment details<br/>[getDetails.ts]"]
end

subgraph group_integration["Pay.gov integration"]
  node_soap["SOAP request transport<br/>[SoapRequest.ts]"]
end

subgraph group_state["Transactions and reporting"]
  node_transactions["Transaction model"]
  node_reporting["Transaction reporting"]
end

subgraph group_operations["Health and operations"]
  node_health["Health checks"]
end

node_client(("USTC application"))
node_paygov["Pay.gov"]
node_database[("Transaction database")]
node_user(("Paying user"))

node_client -->|"calls API"| node_portal
node_portal -->|"validates request"| node_validation
node_portal -->|"extracts caller"| node_identity
node_portal -->|"resolves client"| node_permissions
node_portal -.->|"dispatches initiation"| node_init
node_portal -.->|"dispatches processing"| node_process
node_portal -.->|"dispatches details"| node_details
node_init -->|"resolves fee"| node_fee
node_init -->|"records transaction"| node_transactions
node_init -->|"starts collection"| node_soap
node_soap -->|"sends SOAP"| node_paygov
node_paygov -->|"redirects for payment"| node_user
node_process -->|"completes collection"| node_soap
node_process -->|"updates transaction"| node_transactions
node_details -->|"checks transaction"| node_transactions
node_details -->|"refreshes pending status"| node_soap
node_transactions -->|"queries and writes"| node_database
node_portal -.->|"serves reports"| node_reporting
node_portal -.->|"serves health checks"| node_health

click node_portal "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/handlers/lambdaHandler.ts"
click node_identity "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/extractCallerArn.ts"
click node_permissions "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/clients/permissionsClient.ts"
click node_validation "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/utils/parseAndValidate.ts"
click node_fee "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/config/fees.ts"
click node_init "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/useCases/initPayment.ts"
click node_process "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/useCases/processPayment.ts"
click node_details "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/useCases/getDetails.ts"
click node_soap "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/entities/SoapRequest.ts"
click node_transactions "https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/db/TransactionModel.ts"
click node_reporting "https://github.com/ustaxcourt/ustc-payment-portal/tree/main/src/handlers"
click node_health "https://github.com/ustaxcourt/ustc-payment-portal/tree/main/src/health"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_portal,node_identity,node_permissions,node_validation,node_user toneBlue
class node_fee,node_init,node_process,node_details,node_database toneAmber
class node_soap toneMint
class node_transactions,node_reporting toneRose
class node_health,node_client,node_paygov toneIndigo
```

## Components

### API and access

- [Lambda API boundary](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/handlers/lambdaHandler.ts): `src/handlers/lambdaHandler.ts`
- [Caller identity](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/extractCallerArn.ts): `src/extractCallerArn.ts`
- [Client permissions](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/clients/permissionsClient.ts): `src/clients/permissionsClient.ts`
- [Request validation](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/utils/parseAndValidate.ts): `src/utils/parseAndValidate.ts`

### Payment lifecycle

- [Fee catalog](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/config/fees.ts): `src/config/fees.ts`
- [Initiate payment](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/useCases/initPayment.ts): `src/useCases/initPayment.ts`
- [Process payment](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/useCases/processPayment.ts): `src/useCases/processPayment.ts`
- [Payment details](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/useCases/getDetails.ts): `src/useCases/getDetails.ts`

### Pay.gov integration

- [SOAP request transport](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/entities/SoapRequest.ts): `src/entities/SoapRequest.ts`

### Transactions and reporting

- [Transaction model](https://github.com/ustaxcourt/ustc-payment-portal/blob/main/src/db/TransactionModel.ts): `src/db/TransactionModel.ts`
- [Transaction reporting](https://github.com/ustaxcourt/ustc-payment-portal/tree/main/src/handlers): `src/handlers`

### Health and operations

- [Health checks](https://github.com/ustaxcourt/ustc-payment-portal/tree/main/src/health): `src/health`

### Other components

- **USTC application**
- **Pay.gov**
- **Transaction database**
- **Paying user**

## Connections

- USTC application → Lambda API boundary: calls API (evidence: `README.md`)
- Lambda API boundary → Request validation: validates request (evidence: `src/handlers/lambdaHandler.ts`)
- Lambda API boundary → Caller identity: extracts caller (evidence: `src/handlers/lambdaHandler.ts`)
- Lambda API boundary → Client permissions: resolves client (evidence: `src/handlers/lambdaHandler.ts`)
- Lambda API boundary → Initiate payment: dispatches initiation
- Lambda API boundary → Process payment: dispatches processing
- Lambda API boundary → Payment details: dispatches details
- Initiate payment → Fee catalog: resolves fee (evidence: `README.md`)
- Initiate payment → Transaction model: records transaction (evidence: `README.md`)
- Initiate payment → SOAP request transport: starts collection (evidence: `README.md`)
- SOAP request transport → Pay.gov: sends SOAP (evidence: `src/entities/SoapRequest.ts`)
- Pay.gov → Paying user: redirects for payment (evidence: `README.md`)
- Process payment → SOAP request transport: completes collection (evidence: `README.md`)
- Process payment → Transaction model: updates transaction (evidence: `README.md`)
- Payment details → Transaction model: checks transaction (evidence: `README.md`)
- Payment details → SOAP request transport: refreshes pending status (evidence: `README.md`)
- Transaction model → Transaction database: queries and writes (evidence: `src/db/TransactionModel.ts`)
- Lambda API boundary → Transaction reporting: serves reports
- Lambda API boundary → Health checks: serves health checks