# ingres-si/ingressi architecture

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

- Interactive diagram: https://gitdiagram.com/ingres-si/ingressi
- Repository: https://github.com/ingres-si/ingressi

## Overview

Ingressi is a self-hosted Caddy reverse-proxy control plane. Administrators sign in to the dashboard or use the REST API to configure proxy and L4 hosts, certificates, and optional protections; Caddy serves the resulting traffic, while analytics and audit capabilities provide operational visibility. The tree and README support the major capability branches, but sampled source does not establish most runtime call paths, so documented relationships are cited to the README rather than inferred from imports.

Main entry points: [`app/(dashboard)`](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)) (Web dashboard), [`app/api/v1`](https://github.com/ingres-si/ingressi/tree/develop/app/api/v1) (REST API), [`app/(dashboard)/proxy-hosts`](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/proxy-hosts) (Proxy hosts), [`app/(dashboard)/l4-proxy-hosts`](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/l4-proxy-hosts) (L4 proxy hosts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_dashboard["Web dashboard"]
  node_rest["REST API"]
  node_storage[("Application database<br/>[db.ts]")]
end

subgraph group_proxy["Proxy and security"]
  node_proxyhosts["Proxy hosts"]
  node_l4hosts["L4 proxy hosts"]
  node_certs["Certificates"]
  node_protections["Host protections"]
  node_access["Access lists"]
  node_geoblock["Geo blocking and limits"]
  node_caddy["Caddy proxy"]
end

subgraph group_operations["Operations"]
  node_analytics["Traffic analytics"]
  node_audit["Audit log"]
  node_alerting["Alerting"]
  node_sync["Instance sync<br/>[route.ts]"]
end

subgraph group_identity["Identity and governance"]
  node_accounts["Users and sign-in"]
  node_portal["Forward-auth portal"]
end

subgraph group_enterprise["Extended capabilities"]
  node_approvals["Change approvals"]
  node_reviews["Access reviews"]
  node_compliance["Compliance reports"]
  node_fleet["Fleet management"]
  node_ha["High availability"]
  node_ai["AI analyst"]
  node_monetization["API monetization"]
end

node_admin(("Administrator"))

node_admin -->|"configures"| node_dashboard
node_admin -->|"configures"| node_rest
node_dashboard -->|"manages"| node_proxyhosts
node_dashboard -->|"manages"| node_l4hosts
node_dashboard -->|"manages"| node_certs
node_dashboard -->|"configures"| node_protections
node_dashboard -->|"configures"| node_access
node_dashboard -->|"configures"| node_geoblock
node_proxyhosts -->|"configures"| node_caddy
node_l4hosts -->|"configures"| node_caddy
node_certs -->|"enables HTTPS"| node_caddy
node_protections -->|"protects hosts"| node_caddy
node_access -->|"controls access"| node_caddy
node_geoblock -->|"limits traffic"| node_caddy
node_rest -.->|"persists configuration"| node_storage
node_dashboard -->|"views"| node_analytics
node_dashboard -->|"reviews"| node_audit
node_dashboard -->|"manages"| node_alerting
node_accounts -->|"authenticates"| node_dashboard
node_portal -->|"authenticates requests"| node_caddy
node_dashboard -->|"manages replicas"| node_sync
node_dashboard -->|"reviews changes"| node_approvals
node_dashboard -->|"conducts reviews"| node_reviews
node_dashboard -->|"views reports"| node_compliance
node_dashboard -->|"manages fleet"| node_fleet
node_dashboard -->|"configures availability"| node_ha
node_dashboard -->|"uses analyst"| node_ai
node_rest -->|"offers monetization"| node_monetization

click node_dashboard "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)"
click node_rest "https://github.com/ingres-si/ingressi/tree/develop/app/api/v1"
click node_storage "https://github.com/ingres-si/ingressi/blob/develop/src/lib/db.ts"
click node_proxyhosts "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/proxy-hosts"
click node_l4hosts "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/l4-proxy-hosts"
click node_certs "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/certificates"
click node_protections "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/waf"
click node_access "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/access-lists"
click node_geoblock "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/geo-blocking"
click node_analytics "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/analytics"
click node_audit "https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/audit-log"
click node_alerting "https://github.com/ingres-si/ingressi/tree/develop/ee/alerting"
click node_accounts "https://github.com/ingres-si/ingressi/tree/develop/app/(auth)"
click node_portal "https://github.com/ingres-si/ingressi/tree/develop/app/api/forward-auth"
click node_sync "https://github.com/ingres-si/ingressi/blob/develop/app/api/instances/sync/route.ts"
click node_approvals "https://github.com/ingres-si/ingressi/tree/develop/ee/approvals"
click node_reviews "https://github.com/ingres-si/ingressi/tree/develop/ee/access-reviews"
click node_compliance "https://github.com/ingres-si/ingressi/tree/develop/ee/compliance"
click node_fleet "https://github.com/ingres-si/ingressi/tree/develop/ee/fleet"
click node_ha "https://github.com/ingres-si/ingressi/tree/develop/ee/high-availability"
click node_ai "https://github.com/ingres-si/ingressi/tree/develop/ee/ai"
click node_monetization "https://github.com/ingres-si/ingressi/tree/develop/ee/monetization"

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_rest,node_storage toneBlue
class node_proxyhosts,node_l4hosts,node_certs,node_protections,node_access,node_geoblock,node_caddy toneAmber
class node_analytics,node_audit,node_alerting,node_sync toneMint
class node_accounts,node_portal toneRose
class node_approvals,node_reviews,node_compliance,node_fleet,node_ha,node_ai,node_monetization,node_admin toneIndigo
```

## Components

### Control plane

- [Web dashboard](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)): `app/(dashboard)`
- [REST API](https://github.com/ingres-si/ingressi/tree/develop/app/api/v1): `app/api/v1`
- [Application database](https://github.com/ingres-si/ingressi/blob/develop/src/lib/db.ts): `src/lib/db.ts`

### Proxy and security

- [Proxy hosts](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/proxy-hosts): `app/(dashboard)/proxy-hosts`
- [L4 proxy hosts](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/l4-proxy-hosts): `app/(dashboard)/l4-proxy-hosts`
- [Certificates](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/certificates): `app/(dashboard)/certificates`
- [Host protections](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/waf): `app/(dashboard)/waf`
- [Access lists](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/access-lists): `app/(dashboard)/access-lists`
- [Geo blocking and limits](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/geo-blocking): `app/(dashboard)/geo-blocking`
- **Caddy proxy**

### Operations

- [Traffic analytics](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/analytics): `app/(dashboard)/analytics`
- [Audit log](https://github.com/ingres-si/ingressi/tree/develop/app/(dashboard)/audit-log): `app/(dashboard)/audit-log`
- [Alerting](https://github.com/ingres-si/ingressi/tree/develop/ee/alerting): `ee/alerting`
- [Instance sync](https://github.com/ingres-si/ingressi/blob/develop/app/api/instances/sync/route.ts): `app/api/instances/sync/route.ts`

### Identity and governance

- [Users and sign-in](https://github.com/ingres-si/ingressi/tree/develop/app/(auth)): `app/(auth)`
- [Forward-auth portal](https://github.com/ingres-si/ingressi/tree/develop/app/api/forward-auth): `app/api/forward-auth`

### Extended capabilities

- [Change approvals](https://github.com/ingres-si/ingressi/tree/develop/ee/approvals): `ee/approvals`
- [Access reviews](https://github.com/ingres-si/ingressi/tree/develop/ee/access-reviews): `ee/access-reviews`
- [Compliance reports](https://github.com/ingres-si/ingressi/tree/develop/ee/compliance): `ee/compliance`
- [Fleet management](https://github.com/ingres-si/ingressi/tree/develop/ee/fleet): `ee/fleet`
- [High availability](https://github.com/ingres-si/ingressi/tree/develop/ee/high-availability): `ee/high-availability`
- [AI analyst](https://github.com/ingres-si/ingressi/tree/develop/ee/ai): `ee/ai`
- [API monetization](https://github.com/ingres-si/ingressi/tree/develop/ee/monetization): `ee/monetization`

### Other components

- **Administrator**

## Connections

- Administrator → Web dashboard: configures
- Administrator → REST API: configures
- Web dashboard → Proxy hosts: manages
- Web dashboard → L4 proxy hosts: manages
- Web dashboard → Certificates: manages
- Web dashboard → Host protections: configures
- Web dashboard → Access lists: configures
- Web dashboard → Geo blocking and limits: configures
- Proxy hosts → Caddy proxy: configures
- L4 proxy hosts → Caddy proxy: configures
- Certificates → Caddy proxy: enables HTTPS
- Host protections → Caddy proxy: protects hosts
- Access lists → Caddy proxy: controls access
- Geo blocking and limits → Caddy proxy: limits traffic
- REST API → Application database: persists configuration
- Web dashboard → Traffic analytics: views
- Web dashboard → Audit log: reviews
- Web dashboard → Alerting: manages
- Users and sign-in → Web dashboard: authenticates
- Forward-auth portal → Caddy proxy: authenticates requests
- Web dashboard → Instance sync: manages replicas
- Web dashboard → Change approvals: reviews changes
- Web dashboard → Access reviews: conducts reviews
- Web dashboard → Compliance reports: views reports
- Web dashboard → Fleet management: manages fleet
- Web dashboard → High availability: configures availability
- Web dashboard → AI analyst: uses analyst
- REST API → API monetization: offers monetization (evidence: `app/api/v1/openapi.json/route.ts`)
