# vidinfra/flexprice-v1 architecture

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

- Interactive diagram: https://gitdiagram.com/vidinfra/flexprice-v1
- Repository: https://github.com/vidinfra/flexprice-v1

## Overview

1. **Overall shape**
   - This is a Go-based billing platform built as a modular backend service rather than a UI-centric app.
   - The core product concerns are metering, pricing, subscriptions, credits/wallets, invoicing, tax, and integrations.
   - The repository is organized around a layered architecture: HTTP/API layer, application services, domain models, persistence adapters, and async/workflow infrastructure.

2. **Runtime entrypoints**
   - `cmd/server/main.go` is the main API/runtime entrypoint.
   - `cmd/migrate/main.go` handles database migrations.
   - `main.go` at the repo root likely delegates to the server bootstrap.
   - The repo also includes operational scripts and Dockerfiles for local and ECS-style deployment.

3. **HTTP API boundary**
   - The API surface is concentrated under `internal/api/v1`, with route wiring in `internal/api/router.go`.
   - Request/response shaping is separated into `internal/api/dto`.
   - Cross-cutting API concerns are handled by middleware in `internal/rest/middleware`:
     auth, permissions, CORS, env access, request context, error handling, Sentry, and Pyroscope instrumentation.

4. **Application/service layer**
   - Business logic lives primarily in `internal/service`.
   - This layer orchestrates validation, billing rules, pricing, invoice creation, payment flow, event processing, subscription changes, wallet operations, onboarding, and sync/export tasks.
   - Services are the main coordination boundary between HTTP handlers, repositories, integrations, and async systems.

5. **Domain model and business boundaries**
   - Rich domain models live under `internal/domain`, grouped by business capability: invoice, subscription, wallet, payment, price, plan, feature, entitlement, coupon, tax, customer, tenant, and more.
   - Several domains have dedicated logic for state transitions and derived operations, such as proration, subscription phases, credit grants, wallet transactions, and invoice line items.
   - `internal/types` contains shared value types and API/domain data structures used across layers.

6. **Persistence model**
   - Primary relational persistence is generated through Ent under `ent` and wrapped by repository adapters in `internal/repository/ent`.
   - Schema definitions are in `ent/schema`, which is the canonical model for PostgreSQL-backed operational data.
   - Migrations exist for PostgreSQL and ClickHouse, indicating two distinct storage roles:
     operational billing data in Postgres, and analytical/event data in ClickHouse.

7. **Analytics and event storage**
   - ClickHouse is used for event and usage analytics.
   - `internal/repository/clickhouse` contains query builders and aggregations for usage/cost analytics.
   - The migration set shows event tables, processed-event tracking, feature usage, and costsheet usage tables, which implies an ingestion-and-aggregation pipeline for metering data.

8. **Async/event-driven backbone**
   - Kafka/pub-sub is a key architectural boundary for decoupling request handling from downstream processing.
   - There are Kafka-backed and in-memory pubsub implementations under `internal/pubsub`, plus consumer/producer helpers in `internal/kafka`.
   - The system uses event publishing, monitoring, and retry routing to process billing events, post-processing, and possibly usage aggregation asynchronously.

9. **Temporal for long-running workflows**
   - Temporal is a first-class subsystem under `internal/temporal`.
   - It contains workflows, activities, models, service wrappers, and worker registration for processes like customer onboarding, invoice generation, subscription billing, task execution, and third-party sync jobs.
   - This is the main boundary for durable, long-running, retryable business processes that should not run inside a single HTTP request.

10. **Integrations and external systems**
    - External billing/CRM/accounting/payment integrations are isolated under `internal/integration`.
    - Supported systems include Stripe, Chargebee, QuickBooks, HubSpot, Razorpay, and a “nomod” integration path.
    - S3 is also integrated for file storage/export delivery.
    - Each integration has its own client, DTOs, sync logic, and webhook handlers, which keeps provider-specific concerns out of the core domain.

11. **Webhook and outbound communication architecture**
    - `internal/webhook` handles outbound webhook payload construction, publishing, and delivery abstractions.
    - `internal/integration/*/webhook` handles inbound webhooks from external providers.
    - This suggests two distinct flows: incoming provider events that update state, and outgoing Flexprice events that notify customer systems.

12. **Core billing flows**
    - The most important business pipelines are metering -> aggregation -> pricing -> invoice generation -> payment/sync.
    - Related flows include credit grants/wallet debits, subscription changes and proration, feature entitlement checks, tax application, and invoice/payment reconciliation.
    - The presence of proration calculators, subscription phases, balance alerts, and billing lifecycle docs indicates a sophisticated stateful billing engine rather than simple invoice CRUD.

13. **Operational services**
    - Email sending lives under `internal/email`.
    - PDF generation is isolated under `internal/pdf`, likely for invoice artifacts.
    - Security/encryption, RBAC, Sentry, Pyroscope, cache, and idempotency support show production-grade operational concerns around correctness and observability.

14. **Configuration and deployment model**
    - Configuration is centralized under `internal/config`, with YAML plus environment-driven settings for webhooks, DynamoDB/event config, and RBAC roles.
    - `docker-compose.yml`, `Dockerfile.*`, and GitHub Actions workflows show a containerized, CI/CD-friendly service deployment model.
    - The repo also includes docs, PRDs, and API SDK generation assets, which indicates the API is a product surface as much as the backend runtime.

15. **SDKs and generated API surface**
    - The `api/` directory contains generated client SDKs for Go, JavaScript, and Python, including examples and custom patches.
    - Swagger/OpenAPI definitions live under `docs/swagger`, making the API contract a formal artifact in the architecture.
    - This matters because the backend is designed to be consumed programmatically by customers’ applications and automation, not just by a human-operated frontend.

16. **Testing and simulation**
    - The repo includes extensive unit/integration tests, in-memory store implementations, and mock clients under `internal/testutil`.
    - There are local event fixtures, Kafka test helpers, and SDK tests, which support deterministic testing of both synchronous business logic and async/event-driven behavior.

Main entry points: [`internal/service`](https://github.com/vidinfra/flexprice-v1/tree/main/internal/service) (Services), [`internal/api/v1`](https://github.com/vidinfra/flexprice-v1/tree/main/internal/api/v1) (v1 API), [`internal/pubsub`](https://github.com/vidinfra/flexprice-v1/tree/main/internal/pubsub) (PubSub), [`internal/temporal`](https://github.com/vidinfra/flexprice-v1/tree/main/internal/temporal) (Temporal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>bootstrap<br/>[main.go]"]
  node_server_cmd["Server<br/>api service<br/>[main.go]"]
  node_migrate_cmd["Migrate<br/>db migrator<br/>[main.go]"]
end

subgraph group_api["API Layer"]
  node_router["Router<br/>[router.go]"]
  node_api_v1["v1 API<br/>handlers"]
  node_api_dto["DTOs<br/>contracts"]
  node_middleware["Middleware<br/>cross-cutting"]
end

subgraph group_core["Core Billing"]
  node_services["Services<br/>application layer"]
  node_domain_billing["Billing<br/>domain suite"]
  node_domain_proration["Proration<br/>domain logic"]
  node_domain_events["Events<br/>analytics domain"]
  node_domain_task["Tasks<br/>workflow domain"]
end

subgraph group_data["Persistence"]
  node_ent_repo["Ent Repos<br/>postgres adapters"]
  node_clickhouse_repo["ClickHouse<br/>analytics adapters"]
end

subgraph group_async["Async Backbone"]
  node_pubsub["PubSub<br/>event bus"]
  node_kafka["Kafka<br/>streaming"]
  node_temporal["Temporal<br/>durable workflows"]
end

subgraph group_integrations["Integrations"]
  node_integrations["Integrations<br/>external adapters"]
  node_webhook["Webhooks<br/>delivery layer"]
end

subgraph group_ops["Ops"]
  node_email_pdf["Email & PDF<br/>support services"]
  node_config_ops["Config & Ops<br/>runtime config"]
end

node_main -->|"starts"| node_server_cmd
node_server_cmd -->|"boots"| node_router
node_router -->|"routes to"| node_api_v1
node_api_v1 -->|"maps"| node_api_dto
node_api_v1 -->|"uses"| node_middleware
node_api_v1 -->|"calls"| node_services
node_services -->|"orchestrates"| node_domain_billing
node_services -->|"computes"| node_domain_proration
node_services -->|"processes"| node_domain_events
node_services -->|"schedules"| node_domain_task
node_services -->|"persists"| node_ent_repo
node_services -->|"queries"| node_clickhouse_repo
node_services -->|"publishes"| node_pubsub
node_pubsub -->|"backed by"| node_kafka
node_pubsub -->|"dispatches to"| node_temporal
node_temporal -->|"invokes"| node_services
node_temporal -->|"syncs"| node_integrations
node_integrations -->|"receives/emits"| node_webhook
node_services -->|"produces"| node_email_pdf
node_config_ops -->|"configures"| node_server_cmd
node_config_ops -->|"supports"| node_migrate_cmd

click node_main "https://github.com/vidinfra/flexprice-v1/blob/main/main.go"
click node_server_cmd "https://github.com/vidinfra/flexprice-v1/blob/main/cmd/server/main.go"
click node_migrate_cmd "https://github.com/vidinfra/flexprice-v1/blob/main/cmd/migrate/main.go"
click node_router "https://github.com/vidinfra/flexprice-v1/blob/main/internal/api/router.go"
click node_api_v1 "https://github.com/vidinfra/flexprice-v1/tree/main/internal/api/v1"
click node_api_dto "https://github.com/vidinfra/flexprice-v1/tree/main/internal/api/dto"
click node_middleware "https://github.com/vidinfra/flexprice-v1/tree/main/internal/rest/middleware"
click node_services "https://github.com/vidinfra/flexprice-v1/tree/main/internal/service"
click node_domain_billing "https://github.com/vidinfra/flexprice-v1/tree/main/internal/domain"
click node_domain_proration "https://github.com/vidinfra/flexprice-v1/tree/main/internal/domain/proration"
click node_domain_events "https://github.com/vidinfra/flexprice-v1/tree/main/internal/domain/events"
click node_domain_task "https://github.com/vidinfra/flexprice-v1/tree/main/internal/domain/task"
click node_ent_repo "https://github.com/vidinfra/flexprice-v1/tree/main/internal/repository/ent"
click node_clickhouse_repo "https://github.com/vidinfra/flexprice-v1/tree/main/internal/repository/clickhouse"
click node_pubsub "https://github.com/vidinfra/flexprice-v1/tree/main/internal/pubsub"
click node_kafka "https://github.com/vidinfra/flexprice-v1/tree/main/internal/kafka"
click node_temporal "https://github.com/vidinfra/flexprice-v1/tree/main/internal/temporal"
click node_integrations "https://github.com/vidinfra/flexprice-v1/tree/main/internal/integration"
click node_webhook "https://github.com/vidinfra/flexprice-v1/tree/main/internal/webhook"
click node_email_pdf "https://github.com/vidinfra/flexprice-v1/tree/main/internal/email"
click node_config_ops "https://github.com/vidinfra/flexprice-v1/tree/main/internal/config"

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_main,node_server_cmd,node_migrate_cmd,node_email_pdf,node_config_ops toneBlue
class node_router,node_api_v1,node_api_dto,node_middleware toneAmber
class node_services,node_domain_billing,node_domain_proration,node_domain_events,node_domain_task toneMint
class node_ent_repo,node_clickhouse_repo toneRose
class node_pubsub,node_kafka,node_temporal toneIndigo
class node_integrations,node_webhook toneTeal
```

## Components

### Runtime

Process entrypoints and bootstrap

- [Main](https://github.com/vidinfra/flexprice-v1/blob/main/main.go): bootstrap · Root entrypoint that delegates to the server runtime · `main.go`
- [Server](https://github.com/vidinfra/flexprice-v1/blob/main/cmd/server/main.go): api service · Primary HTTP/API process entrypoint · `cmd/server/main.go`
- [Migrate](https://github.com/vidinfra/flexprice-v1/blob/main/cmd/migrate/main.go): db migrator · Database migration entrypoint · `cmd/migrate/main.go`

### API Layer

HTTP surface, DTOs, and middleware

- [Router](https://github.com/vidinfra/flexprice-v1/blob/main/internal/api/router.go): http router · Wires API routes and middleware · `internal/api/router.go`
- [v1 API](https://github.com/vidinfra/flexprice-v1/tree/main/internal/api/v1): handlers · Versioned HTTP handlers for billing capabilities · `internal/api/v1`
- [DTOs](https://github.com/vidinfra/flexprice-v1/tree/main/internal/api/dto): contracts · Request and response models for API boundaries · `internal/api/dto`
- [Middleware](https://github.com/vidinfra/flexprice-v1/tree/main/internal/rest/middleware): cross-cutting · Auth, permissions, CORS, errors, tracing, and request context · `internal/rest/middleware`

### Core Billing

Application services and domain model

- [Services](https://github.com/vidinfra/flexprice-v1/tree/main/internal/service): application layer · Business orchestration across billing workflows · `internal/service`
- [Billing](https://github.com/vidinfra/flexprice-v1/tree/main/internal/domain): domain suite · Invoices, subscriptions, payments, pricing, plans, taxes, wallets, and credits · `internal/domain`
- [Proration](https://github.com/vidinfra/flexprice-v1/tree/main/internal/domain/proration): domain logic · Proration and billing-period calculations · `internal/domain/proration`
- [Events](https://github.com/vidinfra/flexprice-v1/tree/main/internal/domain/events): analytics domain · Usage aggregation and event modeling · `internal/domain/events`
- [Tasks](https://github.com/vidinfra/flexprice-v1/tree/main/internal/domain/task): workflow domain · Scheduled and asynchronous task models and processing · `internal/domain/task`

### Persistence

Operational and analytical storage adapters

- [Ent Repos](https://github.com/vidinfra/flexprice-v1/tree/main/internal/repository/ent): postgres adapters · Ent-backed repositories for operational billing data · `internal/repository/ent`
- [ClickHouse](https://github.com/vidinfra/flexprice-v1/tree/main/internal/repository/clickhouse): analytics adapters · Usage, cost, and event aggregations · `internal/repository/clickhouse`

### Async Backbone

PubSub, Kafka, and Temporal workflows

- [PubSub](https://github.com/vidinfra/flexprice-v1/tree/main/internal/pubsub): event bus · Kafka and in-memory pubsub implementations · `internal/pubsub`
- [Kafka](https://github.com/vidinfra/flexprice-v1/tree/main/internal/kafka): streaming · Producer, consumer, and monitoring helpers · `internal/kafka`
- [Temporal](https://github.com/vidinfra/flexprice-v1/tree/main/internal/temporal): durable workflows · Workers, workflows, activities, and workflow models · `internal/temporal`

### Integrations

External provider adapters and webhooks

- [Integrations](https://github.com/vidinfra/flexprice-v1/tree/main/internal/integration): external adapters · Provider-specific billing, CRM, accounting, payment, and storage adapters · `internal/integration`
- [Webhooks](https://github.com/vidinfra/flexprice-v1/tree/main/internal/webhook): delivery layer · Outbound webhook payloads and handlers · `internal/webhook`

### Ops

Deployment and support tooling

- [Email & PDF](https://github.com/vidinfra/flexprice-v1/tree/main/internal/email): support services · Notification and invoice artifact generation · `internal/email`
- [Config & Ops](https://github.com/vidinfra/flexprice-v1/tree/main/internal/config): runtime config · Configuration, deployment, and operational scripts · `internal/config`

## Connections

- Main → Server: starts · Root entrypoint launches the API server
- Server → Router: boots · Server initializes HTTP routing
- Router → v1 API: routes to · Versioned handlers implement the HTTP surface
- v1 API → DTOs: maps · Handlers convert to and from DTOs
- v1 API → Middleware: uses · Requests pass through shared middleware
- v1 API → Services: calls · Handlers delegate business logic to services
- Services → Billing: orchestrates · Services coordinate core billing state and rules
- Services → Proration: computes · Services rely on proration logic for billing changes
- Services → Events: processes · Services ingest and transform usage/event data
- Services → Tasks: schedules · Services create and execute asynchronous tasks
- Services → Ent Repos: persists · Operational state is stored through Ent repositories
- Services → ClickHouse: queries · Analytics and usage reporting read from ClickHouse
- Services → PubSub: publishes · Services emit events to the async backbone
- PubSub → Kafka: backed by · Kafka is the primary streaming implementation
- PubSub → Temporal: dispatches to · Async jobs and durable workflows are coordinated here
- Temporal → Services: invokes · Workflows call service methods and domain actions
- Temporal → Integrations: syncs · Durable jobs handle provider sync and reconciliation
- Integrations → Webhooks: receives/emits · Provider webhooks and outbound notifications are handled separately
- Services → Email & PDF: produces · Services generate notifications and invoice artifacts
- Config & Ops → Server: configures · Runtime settings and deployment inputs shape the server
- Config & Ops → Migrate: supports · Operational config also feeds migration runs
