# polarsource/polar architecture

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

- Interactive diagram: https://gitdiagram.com/polarsource/polar
- Repository: https://github.com/polarsource/polar

## Overview

Polar is an open-source monetization platform and merchant of record. The principal workflow is: a developer’s product sends usage, Polar meters and bills it, customers complete checkout, payments and tax are handled, and the merchant receives payouts. Customers can manage orders and subscriptions through a portal, while merchants use dashboards for analytics, finance, and operations. The tree shows broad product surfaces and integrations; core server implementations are represented by the supported `server/polar` directory because they were not sampled.

Main entry points: [`server/polar`](https://github.com/polarsource/polar/tree/main/server/polar) (Checkout Orchestration), [`clients/apps/web/src/app/(main)/[organization]/portal`](https://github.com/polarsource/polar/tree/main/clients/apps/web/src/app/(main)/%5Borganization%5D/portal) (Customer Portal), [`clients/adapters`](https://github.com/polarsource/polar/tree/main/clients/adapters) (Framework Adapters), [`clients/adapters/nextjs/src/checkout/checkout.ts`](https://github.com/polarsource/polar/blob/main/clients/adapters/nextjs/src/checkout/checkout.ts) (Checkout Adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integrations["Integrations"]
  node_framework_adapters["Framework Adapters"]
  node_usage_ingestion["Usage Ingestion"]
  node_webhook_delivery["Webhook Delivery<br/>[webhooks.ts]"]
  node_checkout_adapters["Checkout Adapters<br/>[checkout.ts]"]
end

subgraph group_commerce["Commerce Platform"]
  node_billing_engine["Usage Billing"]
  node_subscriptions["Subscriptions"]
  node_orders["Orders"]
  node_checkout_orchestration["Checkout Orchestration"]
  node_payment_processing["Payment Processing"]
  node_tax_compliance["Tax Compliance"]
  node_merchant_operations["Merchant Operations"]
  node_payouts["Merchant Payouts"]
  node_analytics_insights["Analytics Insights"]
end

subgraph group_customer_surfaces["Customer Surfaces"]
  node_checkout_ui["Checkout UI"]
  node_customer_portal["Customer Portal"]
end

subgraph group_merchant_surfaces["Merchant Surfaces"]
  node_merchant_dashboard["Merchant Dashboard"]
  node_mobile_dashboard["Mobile Dashboard"]
end

subgraph group_platform["Platform Services"]
  node_oauth_service["OAuth Service<br/>[oauth_service.py]"]
  node_oauth_client_store[("OAuth Client Store<br/>[oauth2_client.py]")]
  node_query_state["Query State"]
end

node_developer(("Developer"))
node_product_app(("Product App"))
node_end_customer(("End Customer"))
node_payment_networks(("Payment Networks"))
node_tax_authorities(("Tax Authorities"))
node_payout_bank(("Payout Bank"))
node_oauth_provider(("OAuth Provider"))

node_developer -->|"integrates SDKs"| node_framework_adapters
node_product_app -->|"sends usage"| node_usage_ingestion
node_framework_adapters -.->|"calls checkout"| node_checkout_adapters
node_usage_ingestion -->|"meters events"| node_billing_engine
node_billing_engine -->|"creates charges"| node_orders
node_billing_engine -->|"manages plans"| node_subscriptions
node_end_customer -->|"starts checkout"| node_checkout_ui
node_checkout_ui -->|"submits purchase"| node_checkout_orchestration
node_checkout_adapters -.->|"opens sessions"| node_checkout_orchestration
node_checkout_orchestration -->|"captures payment"| node_payment_processing
node_checkout_orchestration -->|"calculates tax"| node_tax_compliance
node_checkout_orchestration -->|"records order"| node_orders
node_checkout_orchestration -->|"issues receipts"| node_merchant_operations
node_payment_processing -->|"authorizes payment"| node_payment_networks
node_tax_compliance -->|"remits tax"| node_tax_authorities
node_merchant_operations -->|"exposes account"| node_customer_portal
node_customer_portal -->|"reads orders"| node_orders
node_customer_portal -->|"manages subscriptions"| node_subscriptions
node_analytics_insights -->|"serves metrics"| node_merchant_dashboard
node_merchant_dashboard -->|"binds table state"| node_query_state
node_mobile_dashboard -->|"reads metrics"| node_analytics_insights
node_payouts -->|"sends payouts"| node_payout_bank
node_webhook_delivery -->|"delivers events"| node_product_app
node_oauth_provider -->|"authenticates user"| node_oauth_service
node_oauth_service -->|"reads and writes"| node_oauth_client_store

click node_framework_adapters "https://github.com/polarsource/polar/tree/main/clients/adapters"
click node_usage_ingestion "https://github.com/polarsource/polar/tree/main/server/polar"
click node_webhook_delivery "https://github.com/polarsource/polar/blob/main/clients/adapters/adapter-utils/src/webhooks/webhooks.ts"
click node_checkout_adapters "https://github.com/polarsource/polar/blob/main/clients/adapters/nextjs/src/checkout/checkout.ts"
click node_billing_engine "https://github.com/polarsource/polar/tree/main/server/polar"
click node_subscriptions "https://github.com/polarsource/polar/tree/main/server/polar"
click node_orders "https://github.com/polarsource/polar/tree/main/server/polar"
click node_checkout_orchestration "https://github.com/polarsource/polar/tree/main/server/polar"
click node_payment_processing "https://github.com/polarsource/polar/tree/main/server/polar"
click node_tax_compliance "https://github.com/polarsource/polar/tree/main/server/polar"
click node_merchant_operations "https://github.com/polarsource/polar/tree/main/server/polar"
click node_payouts "https://github.com/polarsource/polar/tree/main/server/polar"
click node_analytics_insights "https://github.com/polarsource/polar/tree/main/server/polar"
click node_checkout_ui "https://github.com/polarsource/polar/tree/main/clients/apps/web/src/app/(embed)/embed/payment-method"
click node_customer_portal "https://github.com/polarsource/polar/tree/main/clients/apps/web/src/app/(main)/%5Borganization%5D/portal"
click node_merchant_dashboard "https://github.com/polarsource/polar/tree/main/clients/apps/web/src/app/(main)/dashboard/%5Borganization%5D"
click node_mobile_dashboard "https://github.com/polarsource/polar/tree/main/clients/apps/app/app/(authenticated)"
click node_oauth_service "https://github.com/polarsource/polar/blob/main/server/polar/user/oauth_service.py"
click node_oauth_client_store "https://github.com/polarsource/polar/blob/main/server/polar/models/oauth2_client.py"
click node_query_state "https://github.com/polarsource/polar/blob/main/clients/apps/web/src/hooks/useDataTableQueryState.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_framework_adapters,node_usage_ingestion,node_webhook_delivery,node_checkout_adapters toneBlue
class node_billing_engine,node_subscriptions,node_orders,node_checkout_orchestration,node_payment_processing,node_tax_compliance,node_merchant_operations,node_payouts,node_analytics_insights toneAmber
class node_checkout_ui,node_customer_portal toneMint
class node_merchant_dashboard,node_mobile_dashboard toneRose
class node_oauth_service,node_oauth_client_store,node_query_state,node_developer,node_product_app,node_end_customer,node_payment_networks,node_tax_authorities,node_payout_bank,node_oauth_provider toneIndigo
```

## Components

### Integrations

- [Framework Adapters](https://github.com/polarsource/polar/tree/main/clients/adapters): `clients/adapters`
- [Usage Ingestion](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Webhook Delivery](https://github.com/polarsource/polar/blob/main/clients/adapters/adapter-utils/src/webhooks/webhooks.ts): `clients/adapters/adapter-utils/src/webhooks/webhooks.ts`
- [Checkout Adapters](https://github.com/polarsource/polar/blob/main/clients/adapters/nextjs/src/checkout/checkout.ts): `clients/adapters/nextjs/src/checkout/checkout.ts`

### Commerce Platform

- [Usage Billing](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Subscriptions](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Orders](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Checkout Orchestration](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Payment Processing](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Tax Compliance](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Merchant Operations](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Merchant Payouts](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`
- [Analytics Insights](https://github.com/polarsource/polar/tree/main/server/polar): `server/polar`

### Customer Surfaces

- [Checkout UI](https://github.com/polarsource/polar/tree/main/clients/apps/web/src/app/(embed)/embed/payment-method): `clients/apps/web/src/app/(embed)/embed/payment-method`
- [Customer Portal](https://github.com/polarsource/polar/tree/main/clients/apps/web/src/app/(main)/%5Borganization%5D/portal): `clients/apps/web/src/app/(main)/[organization]/portal`

### Merchant Surfaces

- [Merchant Dashboard](https://github.com/polarsource/polar/tree/main/clients/apps/web/src/app/(main)/dashboard/%5Borganization%5D): `clients/apps/web/src/app/(main)/dashboard/[organization]`
- [Mobile Dashboard](https://github.com/polarsource/polar/tree/main/clients/apps/app/app/(authenticated)): `clients/apps/app/app/(authenticated)`

### Platform Services

- [OAuth Service](https://github.com/polarsource/polar/blob/main/server/polar/user/oauth_service.py): `server/polar/user/oauth_service.py`
- [OAuth Client Store](https://github.com/polarsource/polar/blob/main/server/polar/models/oauth2_client.py): `server/polar/models/oauth2_client.py`
- [Query State](https://github.com/polarsource/polar/blob/main/clients/apps/web/src/hooks/useDataTableQueryState.ts): `clients/apps/web/src/hooks/useDataTableQueryState.ts`

### Other components

- **Developer**
- **Product App**
- **End Customer**
- **Payment Networks**
- **Tax Authorities**
- **Payout Bank**
- **OAuth Provider**

## Connections

- Developer → Framework Adapters: integrates SDKs
- Product App → Usage Ingestion: sends usage
- Framework Adapters → Checkout Adapters: calls checkout
- Usage Ingestion → Usage Billing: meters events
- Usage Billing → Orders: creates charges
- Usage Billing → Subscriptions: manages plans
- End Customer → Checkout UI: starts checkout
- Checkout UI → Checkout Orchestration: submits purchase
- Checkout Adapters → Checkout Orchestration: opens sessions
- Checkout Orchestration → Payment Processing: captures payment
- Checkout Orchestration → Tax Compliance: calculates tax
- Checkout Orchestration → Orders: records order
- Checkout Orchestration → Merchant Operations: issues receipts
- Payment Processing → Payment Networks: authorizes payment
- Tax Compliance → Tax Authorities: remits tax
- Merchant Operations → Customer Portal: exposes account
- Customer Portal → Orders: reads orders
- Customer Portal → Subscriptions: manages subscriptions
- Analytics Insights → Merchant Dashboard: serves metrics
- Merchant Dashboard → Query State: binds table state
- Mobile Dashboard → Analytics Insights: reads metrics
- Merchant Payouts → Payout Bank: sends payouts
- Webhook Delivery → Product App: delivers events
- OAuth Provider → OAuth Service: authenticates user
- OAuth Service → OAuth Client Store: reads and writes
