# getlago/lago-api architecture

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

- Interactive diagram: https://gitdiagram.com/getlago/lago-api
- Repository: https://github.com/getlago/lago-api

## Overview

Lago API is an open-source billing platform for usage-based and subscription billing. Its central product flow accepts billing configuration and usage events, evaluates subscriptions and pricing, and produces invoices and payment outcomes; the tree also shows analytics, customer self-service, catalog management, and integrations. The graph reflects those documented capabilities, but most domain links are necessarily broad: sampled excerpts are concentrated on invoice preview and webhook querying, and the README does not specify detailed request routing or event dispatch.

Main entry points: [`app/graphql/mutations/invoices`](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/invoices) (Invoices), [`app/graphql/mutations/subscriptions`](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/subscriptions) (Subscriptions), [`app/controllers/api/v1/events_controller.rb`](https://github.com/getlago/lago-api/blob/main/app/controllers/api/v1/events_controller.rb) (Usage events), [`app/controllers/api`](https://github.com/getlago/lago-api/tree/main/app/controllers/api) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_rest_api["REST API"]
  node_graphql_api["GraphQL API"]
  node_customer_portal["Customer portal"]
end

subgraph group_billing["Billing lifecycle"]
  node_subscriptions["Subscriptions"]
  node_invoices["Invoices"]
  node_invoice_preview["Invoice preview"]
  node_preview_context["Preview context"]
  node_coupon_preview["Coupon preview<br/>[preview_service.rb]"]
  node_payments["Payments"]
  node_wallets["Wallets and credits"]
end

subgraph group_catalog["Catalog and contracts"]
  node_pricing["Pricing and fees"]
  node_plans["Plans and products"]
end

subgraph group_operations["Events and integrations"]
  node_event_ingest["Usage events"]
  node_webhook_endpoints["Webhook endpoints"]
  node_webhook_query["Webhook history query<br/>[webhooks_query.rb]"]
  node_webhook_record[("Webhook records<br/>[webhook.rb]")]
  node_webhook_delivery["Webhook delivery"]
end

subgraph group_insights["Analytics and reporting"]
  node_analytics["Billing analytics"]
end

node_customer(("Customer or operator"))
node_external_services["External billing services"]

node_customer -.->|"sends billing requests"| node_rest_api
node_customer -.->|"manages billing"| node_graphql_api
node_customer -.->|"uses self-service"| node_customer_portal
node_rest_api -.->|"submits usage"| node_event_ingest
node_event_ingest -.->|"supports usage billing"| node_subscriptions
node_subscriptions -.->|"applies pricing"| node_pricing
node_plans -.->|"defines subscription options"| node_subscriptions
node_subscriptions -.->|"supports subscription billing"| node_invoices
node_event_ingest -.->|"supports usage billing"| node_invoices
node_invoices -.->|"previews invoices"| node_invoice_preview
node_invoice_preview -.->|"builds preview context"| node_preview_context
node_preview_context -.->|"provides applied coupons"| node_coupon_preview
node_invoices -.->|"supports payment collection"| node_payments
node_customer_portal -.->|"manages wallet activity"| node_wallets
node_invoices -.->|"informs billing analytics"| node_analytics
node_webhook_query -->|"queries records"| node_webhook_record
node_webhook_endpoints -.->|"configures delivery targets"| node_external_services
node_webhook_delivery -.->|"delivers events"| node_external_services

click node_rest_api "https://github.com/getlago/lago-api/tree/main/app/controllers/api"
click node_graphql_api "https://github.com/getlago/lago-api/tree/main/app/graphql"
click node_customer_portal "https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/customer_portal"
click node_event_ingest "https://github.com/getlago/lago-api/blob/main/app/controllers/api/v1/events_controller.rb"
click node_subscriptions "https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/subscriptions"
click node_pricing "https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/charges"
click node_plans "https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/plans"
click node_invoices "https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/invoices"
click node_invoice_preview "https://github.com/getlago/lago-api/tree/main/app/services/invoices"
click node_preview_context "https://github.com/getlago/lago-api/blob/main/app/services/invoices/preview_context_service.rb"
click node_coupon_preview "https://github.com/getlago/lago-api/blob/main/app/services/coupons/preview_service.rb"
click node_payments "https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/payments"
click node_wallets "https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/wallets"
click node_analytics "https://github.com/getlago/lago-api/tree/main/app/graphql/resolvers/analytics"
click node_webhook_endpoints "https://github.com/getlago/lago-api/blob/main/app/queries/webhook_endpoints_query.rb"
click node_webhook_query "https://github.com/getlago/lago-api/blob/main/app/queries/webhooks_query.rb"
click node_webhook_record "https://github.com/getlago/lago-api/blob/main/app/models/webhook.rb"
click node_webhook_delivery "https://github.com/getlago/lago-api/blob/main/app/jobs/send_webhook_job.rb"

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_rest_api,node_graphql_api,node_customer_portal toneBlue
class node_subscriptions,node_invoices,node_invoice_preview,node_preview_context,node_coupon_preview,node_payments,node_wallets toneAmber
class node_pricing,node_plans toneMint
class node_event_ingest,node_webhook_endpoints,node_webhook_query,node_webhook_record,node_webhook_delivery toneRose
class node_analytics,node_customer,node_external_services toneIndigo
```

## Components

### API and access

- [REST API](https://github.com/getlago/lago-api/tree/main/app/controllers/api): `app/controllers/api`
- [GraphQL API](https://github.com/getlago/lago-api/tree/main/app/graphql): `app/graphql`
- [Customer portal](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/customer_portal): `app/graphql/mutations/customer_portal`

### Billing lifecycle

- [Subscriptions](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/subscriptions): `app/graphql/mutations/subscriptions`
- [Invoices](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/invoices): `app/graphql/mutations/invoices`
- [Invoice preview](https://github.com/getlago/lago-api/tree/main/app/services/invoices): `app/services/invoices`
- [Preview context](https://github.com/getlago/lago-api/blob/main/app/services/invoices/preview_context_service.rb): `app/services/invoices/preview_context_service.rb`
- [Coupon preview](https://github.com/getlago/lago-api/blob/main/app/services/coupons/preview_service.rb): `app/services/coupons/preview_service.rb`
- [Payments](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/payments): `app/graphql/mutations/payments`
- [Wallets and credits](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/wallets): `app/graphql/mutations/wallets`

### Catalog and contracts

- [Pricing and fees](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/charges): `app/graphql/mutations/charges`
- [Plans and products](https://github.com/getlago/lago-api/tree/main/app/graphql/mutations/plans): `app/graphql/mutations/plans`

### Events and integrations

- [Usage events](https://github.com/getlago/lago-api/blob/main/app/controllers/api/v1/events_controller.rb): `app/controllers/api/v1/events_controller.rb`
- [Webhook endpoints](https://github.com/getlago/lago-api/blob/main/app/queries/webhook_endpoints_query.rb): `app/queries/webhook_endpoints_query.rb`
- [Webhook history query](https://github.com/getlago/lago-api/blob/main/app/queries/webhooks_query.rb): `app/queries/webhooks_query.rb`
- [Webhook records](https://github.com/getlago/lago-api/blob/main/app/models/webhook.rb): `app/models/webhook.rb`
- [Webhook delivery](https://github.com/getlago/lago-api/blob/main/app/jobs/send_webhook_job.rb): `app/jobs/send_webhook_job.rb`

### Analytics and reporting

- [Billing analytics](https://github.com/getlago/lago-api/tree/main/app/graphql/resolvers/analytics): `app/graphql/resolvers/analytics`

### Other components

- **Customer or operator**
- **External billing services**

## Connections

- Customer or operator → REST API: sends billing requests
- Customer or operator → GraphQL API: manages billing
- Customer or operator → Customer portal: uses self-service
- REST API → Usage events: submits usage
- Usage events → Subscriptions: supports usage billing
- Subscriptions → Pricing and fees: applies pricing
- Plans and products → Subscriptions: defines subscription options
- Subscriptions → Invoices: supports subscription billing
- Usage events → Invoices: supports usage billing
- Invoices → Invoice preview: previews invoices
- Invoice preview → Preview context: builds preview context
- Preview context → Coupon preview: provides applied coupons
- Invoices → Payments: supports payment collection
- Customer portal → Wallets and credits: manages wallet activity
- Invoices → Billing analytics: informs billing analytics
- Webhook history query → Webhook records: queries records (evidence: `app/queries/webhooks_query.rb`)
- Webhook endpoints → External billing services: configures delivery targets
- Webhook delivery → External billing services: delivers events
