# fosrl/pangolin architecture

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

- Interactive diagram: https://gitdiagram.com/fosrl/pangolin
- Repository: https://github.com/fosrl/pangolin

## Overview

Pangolin is a unified SASE control plane for private networking, identity-aware proxy access, and AI traffic. Users and administrators manage access through the dashboard and APIs; the server applies identity and policy controls, then supports traffic routing, DNS, certificates, and audit/usage workflows. The README documents the product’s major capabilities; sampled source confirms server startup, API wiring, Traefik certificate/exit-node interactions, and log-streaming provider behavior. Several domain branches are represented at their exact enclosing directories because their implementations were not sampled.

Main entry points: [`server/lib/traefik/TraefikConfigManager.ts`](https://github.com/fosrl/pangolin/blob/main/server/lib/traefik/TraefikConfigManager.ts) (Proxy routing), [`server/private/lib/logStreaming/LogStreamingManager.ts`](https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/LogStreamingManager.ts) (Log streaming), [`server/routers/aiGateway/pipeline.ts`](https://github.com/fosrl/pangolin/blob/main/server/routers/aiGateway/pipeline.ts) (AI gateway), [`server/apiServer.ts`](https://github.com/fosrl/pangolin/blob/main/server/apiServer.ts) (Core API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product interfaces"]
  node_dashboard["Dashboard UI<br/>[page.tsx]"]
  node_server["Server startup<br/>[index.ts]"]
  node_api["Core API<br/>[apiServer.ts]"]
  node_integration["Integration API"]
end

subgraph group_identity["Identity and policy"]
  node_auth["Authentication"]
  node_rbac["Access policies"]
  node_idp["Identity providers"]
end

subgraph group_connect["Network access"]
  node_sites["Sites and clients"]
  node_resources["Resource access"]
  node_proxy["Proxy routing"]
  node_proxy_rules["Routing rules<br/>[rule.ts]"]
  node_dns["DNS service<br/>[server.ts]"]
  node_exit["Exit nodes<br/>[exitNodes.ts]"]
  node_certs["Certificates"]
end

subgraph group_ai["AI gateway"]
  node_ai_gateway["AI gateway<br/>[pipeline.ts]"]
  node_ai_models["AI model catalog<br/>[aiModelCatalog.ts]"]
  node_ai_budgets["AI budgets"]
end

subgraph group_ops["Operations and audit"]
  node_audit[("Audit records")]
  node_log_manager["Log streaming"]
  node_log_provider["Destination providers"]
  node_http_dest["HTTP destination"]
  node_s3_dest["S3 destination"]
end

node_admin(("Admin and users"))

node_admin -->|"manages access"| node_dashboard
node_dashboard -.->|"uses APIs"| node_api
node_server -->|"starts"| node_api
node_server -->|"starts optionally"| node_integration
node_admin -->|"integrates"| node_integration
node_api -.->|"protects requests"| node_auth
node_auth -.->|"authorizes access"| node_rbac
node_idp -.->|"supplies identity"| node_auth
node_admin -->|"configures networks"| node_sites
node_admin -->|"grants access"| node_resources
node_resources -->|"publishes resources"| node_proxy
node_proxy -->|"uses rules"| node_proxy_rules
node_proxy -->|"fetches certificates"| node_certs
node_proxy -->|"updates exit node"| node_exit
node_sites -.->|"resolves resources"| node_dns
node_admin -->|"configures gateway"| node_ai_gateway
node_ai_gateway -.->|"uses model catalog"| node_ai_models
node_ai_gateway -.->|"enforces budgets"| node_ai_budgets
node_admin -->|"reviews activity"| node_audit
node_audit -.->|"streams events"| node_log_manager
node_log_manager -->|"creates providers"| node_log_provider
node_log_manager -->|"dispatches batches"| node_http_dest
node_log_manager -->|"dispatches batches"| node_s3_dest
node_http_dest -->|"implements interface"| node_log_provider
node_s3_dest -->|"implements interface"| node_log_provider

click node_dashboard "https://github.com/fosrl/pangolin/blob/main/src/app/setup/page.tsx"
click node_server "https://github.com/fosrl/pangolin/blob/main/server/index.ts"
click node_api "https://github.com/fosrl/pangolin/blob/main/server/apiServer.ts"
click node_integration "https://github.com/fosrl/pangolin/blob/main/server/integrationApiServer.ts"
click node_auth "https://github.com/fosrl/pangolin/tree/main/server/auth"
click node_rbac "https://github.com/fosrl/pangolin/tree/main/server/middlewares"
click node_idp "https://github.com/fosrl/pangolin/tree/main/server/private/routers/orgIdp"
click node_sites "https://github.com/fosrl/pangolin/tree/main/server/private/routers/remoteExitNode"
click node_resources "https://github.com/fosrl/pangolin/tree/main/server/private/routers/resource"
click node_proxy "https://github.com/fosrl/pangolin/blob/main/server/lib/traefik/TraefikConfigManager.ts"
click node_proxy_rules "https://github.com/fosrl/pangolin/blob/main/server/lib/traefik/rule.ts"
click node_dns "https://github.com/fosrl/pangolin/blob/main/server/private/lib/dns/server.ts"
click node_exit "https://github.com/fosrl/pangolin/blob/main/server/private/lib/exitNodes/exitNodes.ts"
click node_certs "https://github.com/fosrl/pangolin/tree/main/server/private/lib/certificates"
click node_ai_gateway "https://github.com/fosrl/pangolin/blob/main/server/routers/aiGateway/pipeline.ts"
click node_ai_models "https://github.com/fosrl/pangolin/blob/main/server/lib/aiModelCatalog.ts"
click node_ai_budgets "https://github.com/fosrl/pangolin/tree/main/server/routers/aiBudget"
click node_audit "https://github.com/fosrl/pangolin/tree/main/server/private/routers/auditLogs"
click node_log_manager "https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/LogStreamingManager.ts"
click node_log_provider "https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/providers/LogDestinationProvider.ts"
click node_http_dest "https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/providers/HttpLogDestination.ts"
click node_s3_dest "https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/providers/S3LogDestination.ts"

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_dashboard,node_server,node_api,node_integration,node_admin toneBlue
class node_auth,node_rbac,node_idp toneAmber
class node_sites,node_resources,node_proxy,node_proxy_rules,node_dns,node_exit,node_certs toneMint
class node_ai_gateway,node_ai_models,node_ai_budgets toneRose
class node_audit,node_log_manager,node_log_provider,node_http_dest,node_s3_dest toneIndigo
```

## Components

### Product interfaces

- [Dashboard UI](https://github.com/fosrl/pangolin/blob/main/src/app/setup/page.tsx): `src/app/setup/page.tsx`
- [Server startup](https://github.com/fosrl/pangolin/blob/main/server/index.ts): `server/index.ts`
- [Core API](https://github.com/fosrl/pangolin/blob/main/server/apiServer.ts): `server/apiServer.ts`
- [Integration API](https://github.com/fosrl/pangolin/blob/main/server/integrationApiServer.ts): `server/integrationApiServer.ts`

### Identity and policy

- [Authentication](https://github.com/fosrl/pangolin/tree/main/server/auth): `server/auth`
- [Access policies](https://github.com/fosrl/pangolin/tree/main/server/middlewares): `server/middlewares`
- [Identity providers](https://github.com/fosrl/pangolin/tree/main/server/private/routers/orgIdp): `server/private/routers/orgIdp`

### Network access

- [Sites and clients](https://github.com/fosrl/pangolin/tree/main/server/private/routers/remoteExitNode): `server/private/routers/remoteExitNode`
- [Resource access](https://github.com/fosrl/pangolin/tree/main/server/private/routers/resource): `server/private/routers/resource`
- [Proxy routing](https://github.com/fosrl/pangolin/blob/main/server/lib/traefik/TraefikConfigManager.ts): `server/lib/traefik/TraefikConfigManager.ts`
- [Routing rules](https://github.com/fosrl/pangolin/blob/main/server/lib/traefik/rule.ts): `server/lib/traefik/rule.ts`
- [DNS service](https://github.com/fosrl/pangolin/blob/main/server/private/lib/dns/server.ts): `server/private/lib/dns/server.ts`
- [Exit nodes](https://github.com/fosrl/pangolin/blob/main/server/private/lib/exitNodes/exitNodes.ts): `server/private/lib/exitNodes/exitNodes.ts`
- [Certificates](https://github.com/fosrl/pangolin/tree/main/server/private/lib/certificates): `server/private/lib/certificates`

### AI gateway

- [AI gateway](https://github.com/fosrl/pangolin/blob/main/server/routers/aiGateway/pipeline.ts): `server/routers/aiGateway/pipeline.ts`
- [AI model catalog](https://github.com/fosrl/pangolin/blob/main/server/lib/aiModelCatalog.ts): `server/lib/aiModelCatalog.ts`
- [AI budgets](https://github.com/fosrl/pangolin/tree/main/server/routers/aiBudget): `server/routers/aiBudget`

### Operations and audit

- [Audit records](https://github.com/fosrl/pangolin/tree/main/server/private/routers/auditLogs): `server/private/routers/auditLogs`
- [Log streaming](https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/LogStreamingManager.ts): `server/private/lib/logStreaming/LogStreamingManager.ts`
- [Destination providers](https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/providers/LogDestinationProvider.ts): `server/private/lib/logStreaming/providers/LogDestinationProvider.ts`
- [HTTP destination](https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/providers/HttpLogDestination.ts): `server/private/lib/logStreaming/providers/HttpLogDestination.ts`
- [S3 destination](https://github.com/fosrl/pangolin/blob/main/server/private/lib/logStreaming/providers/S3LogDestination.ts): `server/private/lib/logStreaming/providers/S3LogDestination.ts`

### Other components

- **Admin and users**

## Connections

- Admin and users → Dashboard UI: manages access (evidence: `README.md`)
- Dashboard UI → Core API: uses APIs
- Server startup → Core API: starts (evidence: `server/index.ts`)
- Server startup → Integration API: starts optionally (evidence: `server/index.ts`)
- Admin and users → Integration API: integrates (evidence: `README.md`)
- Core API → Authentication: protects requests
- Authentication → Access policies: authorizes access
- Identity providers → Authentication: supplies identity
- Admin and users → Sites and clients: configures networks (evidence: `README.md`)
- Admin and users → Resource access: grants access (evidence: `README.md`)
- Resource access → Proxy routing: publishes resources (evidence: `README.md`)
- Proxy routing → Routing rules: uses rules (evidence: `server/lib/traefik/TraefikConfigManager.ts`)
- Proxy routing → Certificates: fetches certificates (evidence: `server/lib/traefik/TraefikConfigManager.ts`)
- Proxy routing → Exit nodes: updates exit node (evidence: `server/lib/traefik/TraefikConfigManager.ts`)
- Sites and clients → DNS service: resolves resources
- Admin and users → AI gateway: configures gateway (evidence: `README.md`)
- AI gateway → AI model catalog: uses model catalog
- AI gateway → AI budgets: enforces budgets
- Admin and users → Audit records: reviews activity (evidence: `README.md`)
- Audit records → Log streaming: streams events
- Log streaming → Destination providers: creates providers (evidence: `server/private/lib/logStreaming/LogStreamingManager.ts`)
- Log streaming → HTTP destination: dispatches batches (evidence: `server/private/lib/logStreaming/LogStreamingManager.ts`)
- Log streaming → S3 destination: dispatches batches (evidence: `server/private/lib/logStreaming/LogStreamingManager.ts`)
- HTTP destination → Destination providers: implements interface (evidence: `server/private/lib/logStreaming/providers/HttpLogDestination.ts`)
- S3 destination → Destination providers: implements interface (evidence: `server/private/lib/logStreaming/providers/S3LogDestination.ts`)
