# sean1-git/gateforge architecture

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

- Interactive diagram: https://gitdiagram.com/sean1-git/gateforge
- Repository: https://github.com/sean1-git/gateforge

## Overview

GateForge is an API gateway and administrator platform. Its main workflow accepts an application request, matches a configured route, applies credentials and quotas, optionally serves a cacheable public response, and proxies to a backend; the dashboard manages routes and keys and observes gateway activity. The repository also documents request explanations, audit history, and a failure lab. The route handler and frontend imports are visible in excerpts; several backend and admin relationships are documented by the README rather than sampled implementation.

Main entry points: [`internal/gateway/routes.go`](https://github.com/sean1-git/gateforge/blob/main/internal/gateway/routes.go) (Route matching), [`internal/app/admin_api.go`](https://github.com/sean1-git/gateforge/blob/main/internal/app/admin_api.go) (Admin API), [`web/src/main.jsx`](https://github.com/sean1-git/gateforge/blob/main/web/src/main.jsx) (Dashboard shell), [`web/src/pages.jsx`](https://github.com/sean1-git/gateforge/blob/main/web/src/pages.jsx) (Control pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Request gateway"]
  node_gateway["Gateway runtime<br/>[routes.go]"]
  node_route_match["Route matching<br/>[routes.go]"]
  node_credentials["API credentials<br/>[security.go]"]
  node_quotas["Shared quotas<br/>[redis.go]"]
  node_cache["Response cache<br/>[redis.go]"]
  node_balancing["Backend balancing<br/>[pool.go]"]
end

subgraph group_admin["Administration"]
  node_admin_http["Admin API<br/>[admin_api.go]"]
  node_admin_auth["Admin sign-in<br/>[admin_auth.go]"]
  node_sessions["Admin sessions<br/>[session.go]"]
  node_key_storage["Keys and routes<br/>[admin.go]"]
end

subgraph group_observability["Operations and learning"]
  node_metrics["Metrics<br/>[metrics.go]"]
  node_explanations["Request explanations<br/>[explain.go]"]
  node_experiments["Failure experiments<br/>[experiment.go]"]
end

subgraph group_frontend["Dashboard UI"]
  node_dashboard["Dashboard shell<br/>[main.jsx]"]
  node_gateway_state["Dashboard state<br/>[useGateway.js]"]
  node_api_client["Admin API client<br/>[api.js]"]
  node_dashboard_pages["Control pages<br/>[pages.jsx]"]
  node_request_view["Request explorer<br/>[Requests.jsx]"]
  node_audit_view["Audit view<br/>[Audit.jsx]"]
  node_lab_view["Failure lab UI<br/>[Lab.jsx]"]
  node_learn_view["Interactive explainer<br/>[Learn.jsx]"]
end

node_caller(("API client"))
node_backends["Service backends"]
node_redis[("Redis")]
node_admin_user(("Administrator"))
node_postgres[("PostgreSQL")]

node_caller -->|"sends request"| node_gateway
node_gateway -->|"dispatches to"| node_route_match
node_route_match -.->|"validates credentials"| node_credentials
node_route_match -.->|"checks quota"| node_quotas
node_quotas -->|"shares counters"| node_redis
node_route_match -.->|"checks cache"| node_cache
node_cache -->|"uses cache"| node_redis
node_route_match -.->|"selects backend"| node_balancing
node_balancing -.->|"proxies request"| node_backends
node_admin_user -->|"uses dashboard"| node_dashboard
node_dashboard -->|"renders pages"| node_dashboard_pages
node_dashboard -->|"loads state"| node_gateway_state
node_gateway_state -->|"requests data"| node_api_client
node_api_client -.->|"calls admin API"| node_admin_http
node_admin_user -.->|"signs in"| node_admin_auth
node_admin_auth -.->|"issues sessions"| node_sessions
node_admin_http -.->|"reads and saves"| node_key_storage
node_key_storage -->|"persists configuration"| node_postgres
node_admin_http -.->|"serves metrics"| node_metrics
node_admin_http -.->|"serves request records"| node_explanations
node_admin_http -.->|"runs experiments"| node_experiments
node_dashboard_pages -->|"includes explorer"| node_request_view
node_dashboard_pages -->|"includes audit"| node_audit_view
node_dashboard_pages -->|"includes lab"| node_lab_view
node_dashboard -->|"opens explainer"| node_learn_view
node_request_view -.->|"loads requests"| node_api_client
node_audit_view -.->|"reads audit"| node_gateway_state
node_lab_view -.->|"submits experiment"| node_api_client

click node_gateway "https://github.com/sean1-git/gateforge/blob/main/internal/gateway/routes.go"
click node_route_match "https://github.com/sean1-git/gateforge/blob/main/internal/gateway/routes.go"
click node_credentials "https://github.com/sean1-git/gateforge/blob/main/internal/security/security.go"
click node_quotas "https://github.com/sean1-git/gateforge/blob/main/internal/shared/redis.go"
click node_cache "https://github.com/sean1-git/gateforge/blob/main/internal/shared/redis.go"
click node_balancing "https://github.com/sean1-git/gateforge/blob/main/internal/gateway/pool.go"
click node_admin_http "https://github.com/sean1-git/gateforge/blob/main/internal/app/admin_api.go"
click node_admin_auth "https://github.com/sean1-git/gateforge/blob/main/internal/app/admin_auth.go"
click node_sessions "https://github.com/sean1-git/gateforge/blob/main/internal/adminauth/session.go"
click node_key_storage "https://github.com/sean1-git/gateforge/blob/main/internal/storage/admin.go"
click node_metrics "https://github.com/sean1-git/gateforge/blob/main/internal/analytics/metrics.go"
click node_explanations "https://github.com/sean1-git/gateforge/blob/main/internal/explain/explain.go"
click node_experiments "https://github.com/sean1-git/gateforge/blob/main/internal/experiment/experiment.go"
click node_dashboard "https://github.com/sean1-git/gateforge/blob/main/web/src/main.jsx"
click node_gateway_state "https://github.com/sean1-git/gateforge/blob/main/web/src/useGateway.js"
click node_api_client "https://github.com/sean1-git/gateforge/blob/main/web/src/api.js"
click node_dashboard_pages "https://github.com/sean1-git/gateforge/blob/main/web/src/pages.jsx"
click node_request_view "https://github.com/sean1-git/gateforge/blob/main/web/src/Requests.jsx"
click node_audit_view "https://github.com/sean1-git/gateforge/blob/main/web/src/Audit.jsx"
click node_lab_view "https://github.com/sean1-git/gateforge/blob/main/web/src/Lab.jsx"
click node_learn_view "https://github.com/sean1-git/gateforge/blob/main/web/src/Learn.jsx"

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_gateway,node_route_match,node_credentials,node_quotas,node_cache,node_balancing,node_caller toneBlue
class node_admin_http,node_admin_auth,node_sessions,node_key_storage,node_redis,node_postgres toneAmber
class node_metrics,node_explanations,node_experiments toneMint
class node_dashboard,node_gateway_state,node_api_client,node_dashboard_pages,node_request_view,node_audit_view,node_lab_view,node_learn_view toneRose
class node_backends,node_admin_user toneIndigo
```

## Components

### Request gateway

- [Gateway runtime](https://github.com/sean1-git/gateforge/blob/main/internal/gateway/routes.go): `internal/gateway/routes.go`
- [Route matching](https://github.com/sean1-git/gateforge/blob/main/internal/gateway/routes.go): `internal/gateway/routes.go`
- [API credentials](https://github.com/sean1-git/gateforge/blob/main/internal/security/security.go): `internal/security/security.go`
- [Shared quotas](https://github.com/sean1-git/gateforge/blob/main/internal/shared/redis.go): `internal/shared/redis.go`
- [Response cache](https://github.com/sean1-git/gateforge/blob/main/internal/shared/redis.go): `internal/shared/redis.go`
- [Backend balancing](https://github.com/sean1-git/gateforge/blob/main/internal/gateway/pool.go): `internal/gateway/pool.go`

### Administration

- [Admin API](https://github.com/sean1-git/gateforge/blob/main/internal/app/admin_api.go): `internal/app/admin_api.go`
- [Admin sign-in](https://github.com/sean1-git/gateforge/blob/main/internal/app/admin_auth.go): `internal/app/admin_auth.go`
- [Admin sessions](https://github.com/sean1-git/gateforge/blob/main/internal/adminauth/session.go): `internal/adminauth/session.go`
- [Keys and routes](https://github.com/sean1-git/gateforge/blob/main/internal/storage/admin.go): `internal/storage/admin.go`

### Operations and learning

- [Metrics](https://github.com/sean1-git/gateforge/blob/main/internal/analytics/metrics.go): `internal/analytics/metrics.go`
- [Request explanations](https://github.com/sean1-git/gateforge/blob/main/internal/explain/explain.go): `internal/explain/explain.go`
- [Failure experiments](https://github.com/sean1-git/gateforge/blob/main/internal/experiment/experiment.go): `internal/experiment/experiment.go`

### Dashboard UI

- [Dashboard shell](https://github.com/sean1-git/gateforge/blob/main/web/src/main.jsx): `web/src/main.jsx`
- [Dashboard state](https://github.com/sean1-git/gateforge/blob/main/web/src/useGateway.js): `web/src/useGateway.js`
- [Admin API client](https://github.com/sean1-git/gateforge/blob/main/web/src/api.js): `web/src/api.js`
- [Control pages](https://github.com/sean1-git/gateforge/blob/main/web/src/pages.jsx): `web/src/pages.jsx`
- [Request explorer](https://github.com/sean1-git/gateforge/blob/main/web/src/Requests.jsx): `web/src/Requests.jsx`
- [Audit view](https://github.com/sean1-git/gateforge/blob/main/web/src/Audit.jsx): `web/src/Audit.jsx`
- [Failure lab UI](https://github.com/sean1-git/gateforge/blob/main/web/src/Lab.jsx): `web/src/Lab.jsx`
- [Interactive explainer](https://github.com/sean1-git/gateforge/blob/main/web/src/Learn.jsx): `web/src/Learn.jsx`

### Other components

- **API client**
- **Service backends**
- **Redis**
- **Administrator**
- **PostgreSQL**

## Connections

- API client → Gateway runtime: sends request
- Gateway runtime → Route matching: dispatches to (evidence: `internal/gateway/routes.go`)
- Route matching → API credentials: validates credentials
- Route matching → Shared quotas: checks quota
- Shared quotas → Redis: shares counters
- Route matching → Response cache: checks cache
- Response cache → Redis: uses cache
- Route matching → Backend balancing: selects backend
- Backend balancing → Service backends: proxies request
- Administrator → Dashboard shell: uses dashboard
- Dashboard shell → Control pages: renders pages (evidence: `web/src/main.jsx`)
- Dashboard shell → Dashboard state: loads state (evidence: `web/src/main.jsx`)
- Dashboard state → Admin API client: requests data (evidence: `web/src/useGateway.js`)
- Admin API client → Admin API: calls admin API
- Administrator → Admin sign-in: signs in
- Admin sign-in → Admin sessions: issues sessions
- Admin API → Keys and routes: reads and saves
- Keys and routes → PostgreSQL: persists configuration
- Admin API → Metrics: serves metrics
- Admin API → Request explanations: serves request records
- Admin API → Failure experiments: runs experiments
- Control pages → Request explorer: includes explorer (evidence: `web/src/main.jsx`)
- Control pages → Audit view: includes audit (evidence: `web/src/main.jsx`)
- Control pages → Failure lab UI: includes lab (evidence: `web/src/main.jsx`)
- Dashboard shell → Interactive explainer: opens explainer (evidence: `web/src/main.jsx`)
- Request explorer → Admin API client: loads requests (evidence: `web/src/Requests.jsx`)
- Audit view → Dashboard state: reads audit
- Failure lab UI → Admin API client: submits experiment
