# shan1412/customgpt_middleware_app architecture

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

- Interactive diagram: https://gitdiagram.com/shan1412/customgpt_middleware_app
- Repository: https://github.com/shan1412/customgpt_middleware_app

## Overview

This is a FastAPI middleware service connecting CustomGPT actions with Salesforce OAuth and account access. The documented user journey is to authenticate through Salesforce, then use bearer-token actions to retrieve records and save responses; account retrieval is a separate Salesforce-backed action. The graph includes OAuth/token handling, authorization and refresh, and the two persistence paths. Note that the sampled CustomGPT routes currently return anonymous/sample data rather than applying the README-described authentication; unsampled route behavior is not inferred.

Main entry points: [`routes/action_routes.py`](https://github.com/shan1412/customgpt_middleware_app/blob/main/routes/action_routes.py) (Account Action), [`routes/auth_routes.py`](https://github.com/shan1412/customgpt_middleware_app/blob/main/routes/auth_routes.py) (OAuth Routes), [`services/db.py`](https://github.com/shan1412/customgpt_middleware_app/blob/main/services/db.py) (Token Database), [`main.py`](https://github.com/shan1412/customgpt_middleware_app/blob/main/main.py) (FastAPI Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Actions"]
  node_customgpt["CustomGPT Actions"]
  node_app["FastAPI Application<br/>[main.py]"]
  node_account_action["Account Action<br/>[action_routes.py]"]
end

subgraph group_oauth["OAuth and Identity"]
  node_auth_routes["OAuth Routes<br/>[auth_routes.py]"]
  node_validator["Bearer Validator<br/>[validator.py]"]
  node_jwt["JWT Handler<br/>[jwt_handler.py]"]
  node_sf_oauth["Salesforce OAuth<br/>[salesforce.py]"]
end

subgraph group_salesforce["Salesforce Access"]
  node_token_refresh["Token Refresh<br/>[token_refresh.py]"]
  node_sf_service["Account API Client"]
end

subgraph group_storage["Persistence and Audit"]
  node_token_db[("Token Database<br/>[db.py]")]
  node_excel[("Response Workbook<br/>[excel_service.py]")]
  node_logger["Audit and Error Logs<br/>[logger.py]"]
end

node_user(("CustomGPT User"))
node_salesforce{{"Salesforce"}}

node_app -->|"registers routes"| node_auth_routes
node_app -->|"registers routes"| node_account_action
node_app -->|"registers routes"| node_customgpt
node_app -->|"initializes"| node_token_db
node_user -->|"starts login"| node_auth_routes
node_auth_routes -->|"builds login URL"| node_sf_oauth
node_auth_routes -->|"exchanges code"| node_sf_oauth
node_auth_routes -->|"saves tokens"| node_token_db
node_auth_routes -->|"issues JWT"| node_jwt
node_sf_oauth -->|"requests OAuth tokens"| node_salesforce
node_user -->|"calls actions"| node_customgpt
node_customgpt -->|"appends response"| node_excel
node_user -->|"requests accounts"| node_account_action
node_account_action -->|"validates bearer token"| node_validator
node_validator -->|"decodes JWT"| node_jwt
node_validator -->|"checks user token"| node_token_db
node_account_action -->|"reads token"| node_token_db
node_account_action -->|"refreshes expired token"| node_token_refresh
node_token_refresh -->|"reads and updates"| node_token_db
node_token_refresh -->|"requests refresh"| node_salesforce
node_account_action -->|"fetches accounts"| node_sf_service
node_sf_service -->|"queries accounts"| node_salesforce
node_account_action -->|"logs outcome"| node_logger

click node_customgpt "https://github.com/shan1412/customgpt_middleware_app/blob/main/routes/customgpt_routes.py"
click node_auth_routes "https://github.com/shan1412/customgpt_middleware_app/blob/main/routes/auth_routes.py"
click node_app "https://github.com/shan1412/customgpt_middleware_app/blob/main/main.py"
click node_validator "https://github.com/shan1412/customgpt_middleware_app/blob/main/auth/validator.py"
click node_jwt "https://github.com/shan1412/customgpt_middleware_app/blob/main/auth/jwt_handler.py"
click node_sf_oauth "https://github.com/shan1412/customgpt_middleware_app/blob/main/auth/salesforce.py"
click node_token_refresh "https://github.com/shan1412/customgpt_middleware_app/blob/main/auth/token_refresh.py"
click node_account_action "https://github.com/shan1412/customgpt_middleware_app/blob/main/routes/action_routes.py"
click node_sf_service "https://github.com/shan1412/customgpt_middleware_app/blob/main/services/salesforce_service.py"
click node_token_db "https://github.com/shan1412/customgpt_middleware_app/blob/main/services/db.py"
click node_excel "https://github.com/shan1412/customgpt_middleware_app/blob/main/services/excel_service.py"
click node_logger "https://github.com/shan1412/customgpt_middleware_app/blob/main/utils/logger.py"

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_customgpt,node_app,node_account_action,node_user toneBlue
class node_auth_routes,node_validator,node_jwt,node_sf_oauth toneAmber
class node_token_refresh,node_sf_service toneMint
class node_token_db,node_excel,node_logger toneRose
class node_salesforce toneIndigo
```

## Components

### API and Actions

- [CustomGPT Actions](https://github.com/shan1412/customgpt_middleware_app/blob/main/routes/customgpt_routes.py): `routes/customgpt_routes.py`
- [FastAPI Application](https://github.com/shan1412/customgpt_middleware_app/blob/main/main.py): `main.py`
- [Account Action](https://github.com/shan1412/customgpt_middleware_app/blob/main/routes/action_routes.py): `routes/action_routes.py`

### OAuth and Identity

- [OAuth Routes](https://github.com/shan1412/customgpt_middleware_app/blob/main/routes/auth_routes.py): `routes/auth_routes.py`
- [Bearer Validator](https://github.com/shan1412/customgpt_middleware_app/blob/main/auth/validator.py): `auth/validator.py`
- [JWT Handler](https://github.com/shan1412/customgpt_middleware_app/blob/main/auth/jwt_handler.py): `auth/jwt_handler.py`
- [Salesforce OAuth](https://github.com/shan1412/customgpt_middleware_app/blob/main/auth/salesforce.py): `auth/salesforce.py`

### Salesforce Access

- [Token Refresh](https://github.com/shan1412/customgpt_middleware_app/blob/main/auth/token_refresh.py): `auth/token_refresh.py`
- [Account API Client](https://github.com/shan1412/customgpt_middleware_app/blob/main/services/salesforce_service.py): `services/salesforce_service.py`

### Persistence and Audit

- [Token Database](https://github.com/shan1412/customgpt_middleware_app/blob/main/services/db.py): `services/db.py`
- [Response Workbook](https://github.com/shan1412/customgpt_middleware_app/blob/main/services/excel_service.py): `services/excel_service.py`
- [Audit and Error Logs](https://github.com/shan1412/customgpt_middleware_app/blob/main/utils/logger.py): `utils/logger.py`

### Other components

- **CustomGPT User**
- **Salesforce**

## Connections

- FastAPI Application → OAuth Routes: registers routes (evidence: `main.py`)
- FastAPI Application → Account Action: registers routes (evidence: `main.py`)
- FastAPI Application → CustomGPT Actions: registers routes (evidence: `main.py`)
- FastAPI Application → Token Database: initializes (evidence: `main.py`)
- CustomGPT User → OAuth Routes: starts login (evidence: `README.md`)
- OAuth Routes → Salesforce OAuth: builds login URL (evidence: `routes/auth_routes.py`)
- OAuth Routes → Salesforce OAuth: exchanges code (evidence: `routes/auth_routes.py`)
- OAuth Routes → Token Database: saves tokens (evidence: `routes/auth_routes.py`)
- OAuth Routes → JWT Handler: issues JWT (evidence: `routes/auth_routes.py`)
- Salesforce OAuth → Salesforce: requests OAuth tokens (evidence: `auth/salesforce.py`)
- CustomGPT User → CustomGPT Actions: calls actions (evidence: `README.md`)
- CustomGPT Actions → Response Workbook: appends response (evidence: `routes/customgpt_routes.py`)
- CustomGPT User → Account Action: requests accounts (evidence: `routes/action_routes.py`)
- Account Action → Bearer Validator: validates bearer token (evidence: `routes/action_routes.py`)
- Bearer Validator → JWT Handler: decodes JWT (evidence: `auth/validator.py`)
- Bearer Validator → Token Database: checks user token (evidence: `auth/validator.py`)
- Account Action → Token Database: reads token (evidence: `routes/action_routes.py`)
- Account Action → Token Refresh: refreshes expired token (evidence: `routes/action_routes.py`)
- Token Refresh → Token Database: reads and updates (evidence: `auth/token_refresh.py`)
- Token Refresh → Salesforce: requests refresh (evidence: `auth/token_refresh.py`)
- Account Action → Account API Client: fetches accounts (evidence: `routes/action_routes.py`)
- Account API Client → Salesforce: queries accounts (evidence: `services/salesforce_service.py`)
- Account Action → Audit and Error Logs: logs outcome (evidence: `routes/action_routes.py`)
