How vidinfra/flexprice-v1 works
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: service Services · v1 v1 API · pubsub PubSub · temporal Temporal
Components 21
Runtime
Process entrypoints and bootstrap
API Layer
HTTP surface, DTOs, and middleware
- Router · Wires API routes and middleware
internal/api/router.go - v1 API · Versioned HTTP handlers for billing capabilities
internal/api/v1 - DTOs · Request and response models for API boundaries
internal/api/dto - Middleware · Auth, permissions, CORS, errors, tracing, and request context
internal/rest/middleware
Core Billing
Application services and domain model
- Services · Business orchestration across billing workflows
internal/service - Billing · Invoices, subscriptions, payments, pricing, plans, taxes, wallets, and credits
internal/domain - Proration · Proration and billing-period calculations
internal/domain/proration - Events · Usage aggregation and event modeling
internal/domain/events - Tasks · Scheduled and asynchronous task models and processing
internal/domain/task
Persistence
Operational and analytical storage adapters
- Ent Repos · Ent-backed repositories for operational billing data
internal/repository/ent - ClickHouse · Usage, cost, and event aggregations
internal/repository/clickhouse
Async Backbone
PubSub, Kafka, and Temporal workflows
Integrations
External provider adapters and webhooks
- Integrations · Provider-specific billing, CRM, accounting, payment, and storage adapters
internal/integration - Webhooks · Outbound webhook payloads and handlers
internal/webhook
Ops
Deployment and support tooling
- Email & PDF · Notification and invoice artifact generation
internal/email - Config & Ops · Configuration, deployment, and operational scripts
internal/config
Connections 21
- 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