# 24markjr/ai-compliance-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/24markjr/ai-compliance-gateway
- Repository: https://github.com/24markjr/ai-compliance-gateway

## Overview

#### Purpose and Deployment Shape
This repository implements an AI privacy/compliance gateway: sensitive text is detected and masked before LLM inference, then selectively rehydrated for the caller while audit/history records are retained. The current tree contains both an original Node/Express application and a more extensive Python gateway implementation. Deployment and monitoring assets support containerized services and Prometheus/Grafana.
- `docker-compose.yml`
- `render.yaml`
- `gateway/app/main.py`

#### Client Application and Entry Points
The React/Vite client is the user-facing application. It provides login/registration, protected analysis, and history views; API service modules connect it to a backend/gateway. Browser startup is through Vite’s React entry point.
- `frontend/src/main.jsx`
- `frontend/src/App.jsx`
- `frontend/src/pages/Analyze.jsx`

#### Primary Gateway Runtime
The Python gateway is the architecture-rich service boundary for clients and LLM providers. Its FastAPI-style application assembly registers health, auth, chat, analysis, history, dashboard, and administrative routes; dependency wiring and middleware establish shared request behavior.
- `gateway/app/main.py`
- `gateway/app/routers/chat.py`
- `gateway/app/routers/analyze.py`

#### Compliance Processing Pipeline
Incoming text passes through policy-driven compliance scanning before provider dispatch. The engine coordinates detectors for regex, Presidio, secrets, and prompt injection; overlap resolution produces a consistent set of findings. The masker converts findings to safe replacements, and the vault supports reversible values needed for server-side restoration. Policies separate healthcare, HIPAA, PCI-DSS, GDPR, and DPDP rules from application logic.
- `gateway/app/compliance/engine.py`
- `gateway/app/compliance/masker.py`
- `gateway/app/compliance/vault.py`

#### LLM Provider Boundary
The gateway isolates model-specific API behavior behind a provider interface and router. Implementations include OpenAI, Gemini, Claude, DeepSeek, and Ollama, allowing routing changes without exposing raw sensitive content outside the compliance stage. Streaming support is modeled within the compliance layer, so masking behavior can remain applicable to streamed interactions.
- `gateway/app/providers/base.py`
- `gateway/app/providers/router.py`
- `gateway/app/compliance/streaming.py`

#### Identity, Persistence, and Auditability
Authentication middleware and security utilities protect gateway routes. Database modules manage users and request history, while audit models/logger/reader provide compliance records. History is additionally abstracted behind a sink. The original Node backend separately exposes analysis and log routes and uses Supabase, matching the README’s stated React → Express → Gemini → Supabase deployment; it appears to be a legacy or parallel implementation relative to the Python gateway.
- `gateway/app/middleware/auth.py`
- `gateway/app/db/history.py`
- `gateway/app/audit/logger.py`
- `backend/server.js`
- `backend/config/supabase.js`

#### Observability and Operations
Request context, logging, and metrics middleware instrument gateway traffic. Prometheus scrapes metrics and Grafana provisions a gateway dashboard. Runtime configuration, secrets, database/provider endpoints, and policies are externalized rather than embedded in request handlers.
- `gateway/app/middleware/metrics.py`
- `gateway/app/observability/metrics.py`
- `prometheus/prometheus.yml`
- `grafana/dashboards/gateway.json`

Main entry points: [`gateway/app/main.py`](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/main.py) (Gateway application), [`gateway/app/compliance/masker.py`](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/masker.py) (Masker), [`gateway/app/providers/router.py`](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/providers/router.py) (Provider router), [`gateway/app/compliance/engine.py`](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/engine.py) (Compliance engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend["React/Vite client<br/>web client<br/>[main.jsx]"]
  node_app["Client routes<br/>React app<br/>[App.jsx]"]
  node_analyze_ui["Analysis view<br/>React page<br/>[Analyze.jsx]"]
end

subgraph group_gateway["Python Gateway"]
  node_gateway_main["Gateway application<br/>FastAPI app<br/>[main.py]"]
  node_chat_api["Chat API<br/>gateway router<br/>[chat.py]"]
  node_analyze_api["Analysis API<br/>gateway router<br/>[analyze.py]"]
  node_auth["Authentication<br/>auth middleware<br/>[auth.py]"]
  node_history[("Request history<br/>persistence module<br/>[history.py]")]
  node_audit[("Audit logger<br/>compliance audit<br/>[logger.py]")]
end

subgraph group_compliance["Compliance Pipeline"]
  node_compliance_engine["Compliance engine<br/>processing coordinator<br/>[engine.py]"]
  node_masker["Masker<br/>redaction service<br/>[masker.py]"]
  node_vault[("Rehydration vault<br/>reversible token store<br/>[vault.py]")]
  node_streaming["Safe streaming<br/>compliance stream layer<br/>[streaming.py]"]
end

subgraph group_providers["LLM Providers"]
  node_provider_router["Provider router<br/>LLM routing<br/>[router.py]"]
  node_provider_interface["Provider interface<br/>LLM abstraction<br/>[base.py]"]
end

subgraph group_ops["Operations"]
  node_metrics["Metrics middleware<br/>request instrumentation<br/>[metrics.py]"]
  node_prometheus["Prometheus<br/>metrics collector<br/>[prometheus.yml]"]
  node_grafana["Gateway dashboard<br/>Grafana dashboard<br/>[gateway.json]"]
end

subgraph group_legacy["Legacy Node Stack"]
  node_legacy_backend["Express backend<br/>legacy API<br/>[server.js]"]
  node_supabase[("Supabase<br/>legacy persistence<br/>[supabase.js]")]
end

node_frontend -->|"boots"| node_app
node_app -->|"renders"| node_analyze_ui
node_analyze_ui -->|"API requests"| node_gateway_main
node_gateway_main -->|"protects routes"| node_auth
node_gateway_main -->|"registers"| node_chat_api
node_gateway_main -->|"registers"| node_analyze_api
node_chat_api -->|"submits text"| node_compliance_engine
node_analyze_api -->|"submits text"| node_compliance_engine
node_compliance_engine -->|"findings"| node_masker
node_masker -->|"stores reversible values"| node_vault
node_masker -->|"masked prompt"| node_provider_router
node_provider_router -->|"dispatches through"| node_provider_interface
node_provider_router -->|"streamed responses"| node_streaming
node_streaming -->|"restores authorized values"| node_vault
node_gateway_main -->|"records requests"| node_history
node_gateway_main -->|"writes compliance events"| node_audit
node_gateway_main -->|"instruments traffic"| node_metrics
node_prometheus -->|"scrapes"| node_metrics
node_grafana -->|"queries"| node_prometheus
node_frontend -.->|"legacy API path"| node_legacy_backend
node_legacy_backend -->|"stores logs and users"| node_supabase

click node_frontend "https://github.com/24markjr/ai-compliance-gateway/blob/master/frontend/src/main.jsx"
click node_app "https://github.com/24markjr/ai-compliance-gateway/blob/master/frontend/src/App.jsx"
click node_analyze_ui "https://github.com/24markjr/ai-compliance-gateway/blob/master/frontend/src/pages/Analyze.jsx"
click node_gateway_main "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/main.py"
click node_chat_api "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/routers/chat.py"
click node_analyze_api "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/routers/analyze.py"
click node_auth "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/middleware/auth.py"
click node_compliance_engine "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/engine.py"
click node_masker "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/masker.py"
click node_vault "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/vault.py"
click node_streaming "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/streaming.py"
click node_provider_router "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/providers/router.py"
click node_provider_interface "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/providers/base.py"
click node_history "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/db/history.py"
click node_audit "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/audit/logger.py"
click node_metrics "https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/middleware/metrics.py"
click node_prometheus "https://github.com/24markjr/ai-compliance-gateway/blob/master/prometheus/prometheus.yml"
click node_grafana "https://github.com/24markjr/ai-compliance-gateway/blob/master/grafana/dashboards/gateway.json"
click node_legacy_backend "https://github.com/24markjr/ai-compliance-gateway/blob/master/backend/server.js"
click node_supabase "https://github.com/24markjr/ai-compliance-gateway/blob/master/backend/config/supabase.js"

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_frontend,node_app,node_analyze_ui toneBlue
class node_gateway_main,node_chat_api,node_analyze_api,node_auth,node_history,node_audit toneAmber
class node_compliance_engine,node_masker,node_vault,node_streaming toneMint
class node_provider_router,node_provider_interface toneRose
class node_metrics,node_prometheus,node_grafana toneIndigo
class node_legacy_backend,node_supabase toneTeal
```

## Components

### Client

- [React/Vite client](https://github.com/24markjr/ai-compliance-gateway/blob/master/frontend/src/main.jsx): web client · Login, protected analysis, and history UI. · `frontend/src/main.jsx`
- [Client routes](https://github.com/24markjr/ai-compliance-gateway/blob/master/frontend/src/App.jsx): React app · `frontend/src/App.jsx`
- [Analysis view](https://github.com/24markjr/ai-compliance-gateway/blob/master/frontend/src/pages/Analyze.jsx): React page · `frontend/src/pages/Analyze.jsx`

### Python Gateway

- [Gateway application](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/main.py): FastAPI app · Registers API routes, shared dependencies, and middleware. · `gateway/app/main.py`
- [Chat API](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/routers/chat.py): gateway router · `gateway/app/routers/chat.py`
- [Analysis API](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/routers/analyze.py): gateway router · `gateway/app/routers/analyze.py`
- [Authentication](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/middleware/auth.py): auth middleware · `gateway/app/middleware/auth.py`
- [Request history](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/db/history.py): persistence module · `gateway/app/db/history.py`
- [Audit logger](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/audit/logger.py): compliance audit · `gateway/app/audit/logger.py`

### Compliance Pipeline

- [Compliance engine](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/engine.py): processing coordinator · Runs detection and resolves overlapping findings. · `gateway/app/compliance/engine.py`
- [Masker](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/masker.py): redaction service · Replaces findings before model dispatch. · `gateway/app/compliance/masker.py`
- [Rehydration vault](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/vault.py): reversible token store · Holds values needed for server-side restoration. · `gateway/app/compliance/vault.py`
- [Safe streaming](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/compliance/streaming.py): compliance stream layer · `gateway/app/compliance/streaming.py`

### LLM Providers

- [Provider router](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/providers/router.py): LLM routing · Selects OpenAI, Gemini, Claude, DeepSeek, or Ollama implementations. · `gateway/app/providers/router.py`
- [Provider interface](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/providers/base.py): LLM abstraction · `gateway/app/providers/base.py`

### Operations

- [Metrics middleware](https://github.com/24markjr/ai-compliance-gateway/blob/master/gateway/app/middleware/metrics.py): request instrumentation · `gateway/app/middleware/metrics.py`
- [Prometheus](https://github.com/24markjr/ai-compliance-gateway/blob/master/prometheus/prometheus.yml): metrics collector · Scrapes gateway metrics. · `prometheus/prometheus.yml`
- [Gateway dashboard](https://github.com/24markjr/ai-compliance-gateway/blob/master/grafana/dashboards/gateway.json): Grafana dashboard · `grafana/dashboards/gateway.json`

### Legacy Node Stack

Parallel or legacy React–Express deployment path.

- [Express backend](https://github.com/24markjr/ai-compliance-gateway/blob/master/backend/server.js): legacy API · Original analysis and log route implementation. · `backend/server.js`
- [Supabase](https://github.com/24markjr/ai-compliance-gateway/blob/master/backend/config/supabase.js): legacy persistence · `backend/config/supabase.js`

## Connections

- React/Vite client → Client routes: boots
- Client routes → Analysis view: renders
- Analysis view → Gateway application: API requests
- Gateway application → Authentication: protects routes
- Gateway application → Chat API: registers
- Gateway application → Analysis API: registers
- Chat API → Compliance engine: submits text
- Analysis API → Compliance engine: submits text
- Compliance engine → Masker: findings
- Masker → Rehydration vault: stores reversible values
- Masker → Provider router: masked prompt
- Provider router → Provider interface: dispatches through
- Provider router → Safe streaming: streamed responses
- Safe streaming → Rehydration vault: restores authorized values
- Gateway application → Request history: records requests
- Gateway application → Audit logger: writes compliance events
- Gateway application → Metrics middleware: instruments traffic
- Prometheus → Metrics middleware: scrapes
- Gateway dashboard → Prometheus: queries
- React/Vite client → Express backend: legacy API path
- Express backend → Supabase: stores logs and users