# nangohq/nango architecture

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

- Interactive diagram: https://gitdiagram.com/nangohq/nango
- Repository: https://github.com/nangohq/nango
- Video tour (about a minute): https://gitdiagram.com/nangohq/nango/video

## Overview

Nango is a platform for building and operating product integrations: teams configure providers, authorize customer connections, then make authenticated API calls or deploy integration functions that sync data, process webhooks, and perform actions. The graph follows those user-facing stages into execution, persistence, and observability, while retaining the CLI and embedded connection UI as distinct entry points. README statements establish the high-level product workflow; source-index references and excerpts support several internal links. Unsampled implementations are represented only where the tree supports a path.

Main entry points: [`packages/server/lib/routes.public.ts`](https://github.com/nangohq/nango/blob/master/packages/server/lib/routes.public.ts) (Public API routes), [`packages/jobs/lib/app.ts`](https://github.com/nangohq/nango/blob/master/packages/jobs/lib/app.ts) (Jobs service), [`packages/server/lib/controllers/oauth.controller.ts`](https://github.com/nangohq/nango/blob/master/packages/server/lib/controllers/oauth.controller.ts) (OAuth controller), [`packages/runner/lib/server.ts`](https://github.com/nangohq/nango/blob/master/packages/runner/lib/server.ts) (Function runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Integration setup"]
  node_cli["CLI<br/>[cli.ts]"]
  node_integration_config["Integration config<br/>[parser.ts]"]
end

subgraph group_auth["Connection and API access"]
  node_connect_ui["Connect UI<br/>[App.tsx]"]
  node_public_api["Public API routes<br/>[routes.public.ts]"]
  node_oauth["OAuth controller"]
  node_connection_service["Connection service"]
  node_node_client["Node client<br/>[index.ts]"]
  node_proxy_policy["Outbound policy<br/>[outbound-policy.ts]"]
end

subgraph group_execution["Function execution"]
  node_orchestrator["Task orchestrator<br/>[app.ts]"]
  node_jobs["Jobs service<br/>[app.ts]"]
  node_runtime["Runtime selection<br/>[runtimes.ts]"]
  node_runner["Function runner<br/>[server.ts]"]
  node_sync_manager["Sync manager<br/>[manager.service.ts]"]
end

subgraph group_state["Data and state"]
  node_persist["Persistence API<br/>[server.ts]"]
  node_records[("Record storage<br/>[store.ts]")]
end

subgraph group_operations["Operations"]
  node_logs[("Logs storage")]
  node_metering["Usage and audit<br/>[app.ts]"]
end

node_developer(("Developer"))
node_external_apis(("External APIs"))
node_customer_app(("Customer application"))

node_developer -->|"configures"| node_cli
node_cli -->|"parses config"| node_integration_config
node_developer -->|"embeds auth"| node_connect_ui
node_connect_ui -.->|"starts auth"| node_public_api
node_customer_app -->|"requests access"| node_public_api
node_public_api -->|"routes OAuth"| node_oauth
node_oauth -.->|"updates connection"| node_connection_service
node_oauth -->|"checks URL"| node_proxy_policy
node_customer_app -->|"calls API"| node_node_client
node_node_client -.->|"sends requests"| node_public_api
node_public_api -->|"proxies requests"| node_external_apis
node_developer -->|"schedules functions"| node_orchestrator
node_orchestrator -.->|"dispatches tasks"| node_jobs
node_jobs -->|"selects runtime"| node_runtime
node_runtime -.->|"runs functions"| node_runner
node_runner -->|"stores records"| node_persist
node_persist -.->|"reads and writes"| node_records
node_developer -->|"deploys syncs"| node_sync_manager
node_sync_manager -.->|"schedules syncs"| node_orchestrator
node_runner -->|"calls APIs"| node_external_apis
node_jobs -.->|"emits telemetry"| node_logs
node_jobs -.->|"publishes usage"| node_metering

click node_cli "https://github.com/nangohq/nango/blob/master/packages/cli/lib/cli.ts"
click node_integration_config "https://github.com/nangohq/nango/blob/master/packages/nango-yaml/lib/parser.ts"
click node_connect_ui "https://github.com/nangohq/nango/blob/master/packages/connect-ui/src/App.tsx"
click node_public_api "https://github.com/nangohq/nango/blob/master/packages/server/lib/routes.public.ts"
click node_oauth "https://github.com/nangohq/nango/blob/master/packages/server/lib/controllers/oauth.controller.ts"
click node_connection_service "https://github.com/nangohq/nango/blob/master/packages/shared/lib/services/connection.service.ts"
click node_node_client "https://github.com/nangohq/nango/blob/master/packages/node-client/lib/index.ts"
click node_proxy_policy "https://github.com/nangohq/nango/blob/master/packages/shared/lib/services/proxy/outbound-policy.ts"
click node_orchestrator "https://github.com/nangohq/nango/blob/master/packages/orchestrator/lib/app.ts"
click node_jobs "https://github.com/nangohq/nango/blob/master/packages/jobs/lib/app.ts"
click node_runtime "https://github.com/nangohq/nango/blob/master/packages/jobs/lib/runtime/runtimes.ts"
click node_runner "https://github.com/nangohq/nango/blob/master/packages/runner/lib/server.ts"
click node_sync_manager "https://github.com/nangohq/nango/blob/master/packages/shared/lib/services/sync/manager.service.ts"
click node_persist "https://github.com/nangohq/nango/blob/master/packages/persist/lib/server.ts"
click node_records "https://github.com/nangohq/nango/blob/master/packages/records/lib/store.ts"
click node_logs "https://github.com/nangohq/nango/blob/master/packages/logs/lib/storage/logsStorageClient.ts"
click node_metering "https://github.com/nangohq/nango/blob/master/packages/metering/lib/app.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_cli,node_integration_config toneBlue
class node_connect_ui,node_public_api,node_oauth,node_connection_service,node_node_client,node_proxy_policy toneAmber
class node_orchestrator,node_jobs,node_runtime,node_runner,node_sync_manager,node_external_apis toneMint
class node_persist,node_records toneRose
class node_logs,node_metering,node_developer,node_customer_app toneIndigo
```

## Components

### Integration setup

- [CLI](https://github.com/nangohq/nango/blob/master/packages/cli/lib/cli.ts): `packages/cli/lib/cli.ts`
- [Integration config](https://github.com/nangohq/nango/blob/master/packages/nango-yaml/lib/parser.ts): `packages/nango-yaml/lib/parser.ts`

### Connection and API access

- [Connect UI](https://github.com/nangohq/nango/blob/master/packages/connect-ui/src/App.tsx): `packages/connect-ui/src/App.tsx`
- [Public API routes](https://github.com/nangohq/nango/blob/master/packages/server/lib/routes.public.ts): `packages/server/lib/routes.public.ts`
- [OAuth controller](https://github.com/nangohq/nango/blob/master/packages/server/lib/controllers/oauth.controller.ts): `packages/server/lib/controllers/oauth.controller.ts`
- [Connection service](https://github.com/nangohq/nango/blob/master/packages/shared/lib/services/connection.service.ts): `packages/shared/lib/services/connection.service.ts`
- [Node client](https://github.com/nangohq/nango/blob/master/packages/node-client/lib/index.ts): `packages/node-client/lib/index.ts`
- [Outbound policy](https://github.com/nangohq/nango/blob/master/packages/shared/lib/services/proxy/outbound-policy.ts): `packages/shared/lib/services/proxy/outbound-policy.ts`

### Function execution

- [Task orchestrator](https://github.com/nangohq/nango/blob/master/packages/orchestrator/lib/app.ts): `packages/orchestrator/lib/app.ts`
- [Jobs service](https://github.com/nangohq/nango/blob/master/packages/jobs/lib/app.ts): `packages/jobs/lib/app.ts`
- [Runtime selection](https://github.com/nangohq/nango/blob/master/packages/jobs/lib/runtime/runtimes.ts): `packages/jobs/lib/runtime/runtimes.ts`
- [Function runner](https://github.com/nangohq/nango/blob/master/packages/runner/lib/server.ts): `packages/runner/lib/server.ts`
- [Sync manager](https://github.com/nangohq/nango/blob/master/packages/shared/lib/services/sync/manager.service.ts): `packages/shared/lib/services/sync/manager.service.ts`

### Data and state

- [Persistence API](https://github.com/nangohq/nango/blob/master/packages/persist/lib/server.ts): `packages/persist/lib/server.ts`
- [Record storage](https://github.com/nangohq/nango/blob/master/packages/records/lib/store.ts): `packages/records/lib/store.ts`

### Operations

- [Logs storage](https://github.com/nangohq/nango/blob/master/packages/logs/lib/storage/logsStorageClient.ts): `packages/logs/lib/storage/logsStorageClient.ts`
- [Usage and audit](https://github.com/nangohq/nango/blob/master/packages/metering/lib/app.ts): `packages/metering/lib/app.ts`

### Other components

- **Developer**
- **External APIs**
- **Customer application**

## Connections

- Developer → CLI: configures (evidence: `README.md`)
- CLI → Integration config: parses config
- Developer → Connect UI: embeds auth (evidence: `README.md`)
- Connect UI → Public API routes: starts auth
- Customer application → Public API routes: requests access (evidence: `README.md`)
- Public API routes → OAuth controller: routes OAuth (evidence: `packages/server/lib/routes.public.ts`)
- OAuth controller → Connection service: updates connection
- OAuth controller → Outbound policy: checks URL
- Customer application → Node client: calls API (evidence: `README.md`)
- Node client → Public API routes: sends requests
- Public API routes → External APIs: proxies requests (evidence: `README.md`)
- Developer → Task orchestrator: schedules functions (evidence: `README.md`)
- Task orchestrator → Jobs service: dispatches tasks
- Jobs service → Runtime selection: selects runtime (evidence: `packages/jobs/lib/app.ts`)
- Runtime selection → Function runner: runs functions
- Function runner → Persistence API: stores records (evidence: `packages/runner/lib/server.ts`)
- Persistence API → Record storage: reads and writes
- Developer → Sync manager: deploys syncs (evidence: `README.md`)
- Sync manager → Task orchestrator: schedules syncs
- Function runner → External APIs: calls APIs (evidence: `README.md`)
- Jobs service → Logs storage: emits telemetry
- Jobs service → Usage and audit: publishes usage
