---
source_url: "https://flexprice.mintlify.app/docs/contributing-guide/architechture?utm_source=openai"
title: Project Architecture - Flexprice
mirrored_at: 2026-08-15T01:02:02.440Z
host: flexprice.mintlify.app
cited_in_42a: true
mirror_canonical: "https://index.42a.ai/flexprice.mintlify.app/docs/contributing-guide/architechture__q__utm_source_openai"
---

> **Original source:** https://flexprice.mintlify.app/docs/contributing-guide/architechture?utm_source=openai

## Overview

Flexprice is a comprehensive **usage-based billing and subscription management platform** built in Go. The system handles the complete billing lifecycle from event ingestion through invoice generation and payment processing, designed for B2B SaaS companies requiring flexible pricing models.

## High-Level Architecture

Flexprice implements a **three-tier layered architecture** with clear separation of concerns, bootstrapped using **Uber FX dependency injection framework**:

### Architecture Layers

## Technology Stack

### Core Technologies

Flexprice uses a modern Go stack with specialized components: **Key Dependencies:**

-   **Gin** - HTTP routing and middleware
-   **Ent** - Type-safe ORM for PostgreSQL
-   **Uber FX** - Dependency injection framework
-   **ClickHouse** - Columnar database for analytics
-   **Kafka (Sarama)** - Event streaming platform
-   **Temporal** - Workflow orchestration engine
-   **Stripe** - Payment processing integration

## Dual-Database Strategy

Flexprice employs a **specialized database strategy** for different workloads:

### PostgreSQL (Transactional Data)

-   **Purpose**: ACID transactions, relational data
-   **Data**: Subscriptions, invoices, customers, plans, prices, wallets
-   **Access Pattern**: Read-write, complex joins, referential integrity
-   **ORM**: Ent for type-safe queries

### ClickHouse (Analytical Data)

-   **Purpose**: High-volume inserts, aggregation queries
-   **Data**: Events (raw), events\_lazy, processed\_events, system\_events
-   **Access Pattern**: Append-only writes, time-series queries
-   **Tables**: Optimized for usage metering and analytics

## Event Processing Pipeline

The core of Flexprice’s usage-based billing is an **asynchronous event processing pipeline** powered by Kafka:

### Pipeline Stages

## Deployment Modes

Flexprice supports **multiple deployment configurations** to separate concerns and scale independently:

### Available Modes

Mode

Components

Purpose

**`local`**

API Server + Router (with event consumption handlers) + Temporal Worker

Full development environment with all services enabled

**`api`**

API Server + Router (event consumption disabled)

Handle HTTP requests with routing but no event processing

**`consumer`**

Router only (with event consumption handlers)

Dedicated event processing without HTTP API

**`temporal_worker`**

Temporal workers only

Background workflows and scheduled tasks execution

### Mode Implementation Details

-   **`local`**: Starts API server, registers all router handlers with event consumption enabled (`true`), starts router, and starts Temporal worker
-   **`api`**: Starts API server, registers router handlers with event consumption disabled (`false`), starts router only
-   **`consumer`**: Requires Kafka consumer, registers all router handlers with event consumption enabled (`true`), starts router without API server
-   **`temporal_worker`**: Starts only Temporal worker service, no API server or router

## Service Layer Architecture

The service layer implements business logic through 30+ domain services organized by domain:

### Core Services

-   **Billing Service**: Handles invoice generation, usage calculations, and billing cycles
-   **Event Service**: Processes incoming usage events and manages event lifecycle
-   **Subscription Service**: Manages customer subscriptions, upgrades, and downgrades
-   **Customer Service**: Customer management and tenant operations
-   **Payment Service**: Payment processing and gateway integrations
-   **Plan Service**: Pricing plan management and feature configuration
-   **Wallet Service**: Prepaid credits and wallet balance management

### Service Factory Pattern

All services are instantiated through factory functions that receive a centralized `ServiceParams` struct containing shared dependencies:

## API Layer & Routing

The API layer uses **Gin framework** with a comprehensive middleware stack for security, logging, and request processing:

### Middleware Stack

1.  **Recovery Middleware**: Panic recovery and graceful error handling
2.  **CORS Middleware**: Cross-origin resource sharing configuration
3.  **Rate Limiting**: Request throttling per API key/tenant
4.  **Authentication**: JWT and API key validation
5.  **Tenant Isolation**: Multi-tenant context enforcement
6.  **Request Logging**: Structured logging for all requests
7.  **Metrics Collection**: Prometheus metrics for observability

Flexprice supports multiple authentication methods:

-   **API Keys**: Tenant-scoped keys for programmatic access
-   **JWT Tokens**: User session tokens with role-based permissions
-   **Webhook Signatures**: HMAC verification for incoming webhooks

### API Endpoints Structure

## Multi-Tenancy Architecture

Flexprice implements **row-level multi-tenancy** with environment isolation enforced at multiple architectural layers:

### Tenant Isolation Strategy

-   **Database Level**: All tables include `tenant_id` and `environment` columns
-   **Middleware Level**: Request context includes tenant/environment validation
-   **Service Level**: All business logic operations are tenant-scoped
-   **Repository Level**: Automatic filtering on all database queries

### Middleware Enforcement

Tenant and environment isolation is enforced through the `AuthenticateMiddleware`, which handles both authentication and tenant context extraction:

### Authentication Methods

API keys are configured with tenant and user association:

-   **Tenant API Keys**: Scoped to specific tenant and environment
-   **User Tokens**: Associated with user permissions within tenant
-   **System Keys**: Cross-tenant access for administrative operations

## Repository Layer

The repository layer provides data access abstraction with automatic tenant/environment filtering:

### Repository Interface

### Automatic Tenant Filtering

All repositories automatically append tenant and environment filters to queries using typed context constants:

All repositories are created through factory functions that receive shared dependencies like database connections, caching layers, and configuration.

## Message Processing with PubSub Router

Flexprice uses **Watermill** for message routing with built-in retry mechanisms and rate limiting:

### Kafka Integration

### Message Processing Features

-   **Dead Letter Queues**: Failed messages are routed to error topics
-   **Retry Logic**: Exponential backoff for transient failures
-   **Rate Limiting**: Configurable processing rates per topic
-   **Metrics**: Built-in monitoring for message processing

## Temporal Workflow Orchestration

Background jobs and scheduled tasks use **Temporal** for reliable execution and workflow management:

### Workflow Types

-   **Billing Workflows**: Monthly/annual invoice generation
-   **Usage Aggregation**: Periodic usage calculations
-   **Payment Processing**: Async payment collection workflows
-   **Data Exports**: Large dataset exports to S3
-   **Webhook Delivery**: Reliable event notifications

### Workflow Registration

### Worker Lifecycle

Workers are deployed separately and can be scaled independently:

## External Integrations

Flexprice uses a factory pattern for external service integrations, supporting multiple providers through specific integration implementations:

### Webhook Delivery

Flexprice has a flexible webhook delivery system with **optional Svix integration**. By default, it uses an internal webhook system with in-memory or Kafka pub/sub:

## Infrastructure Services

### Monitoring & Observability

**Sentry** for error tracking and performance monitoring:

**Pyroscope** for continuous profiling and performance analysis:

### Document Storage

Invoice PDFs are stored in **S3** with presigned URL generation for secure access:

### Caching Layer

Flexprice uses **in-memory caching only** for performance optimization. Caching can be enabled/disabled via configuration:

## Configuration Management

Configuration is loaded from YAML files with environment variable overrides for deployment flexibility:

### Configuration Structure

## Application Lifecycle

The application lifecycle is managed by **Uber FX** with hooks for startup and shutdown:

## Notes

**Key Architectural Decisions:**

1.  **Dual-Database Strategy**: PostgreSQL for transactional consistency, ClickHouse for high-volume analytics
2.  **Event-Driven Architecture**: Kafka enables asynchronous processing, scalability, and fault tolerance
3.  **Microservices-Ready**: Deployment modes allow splitting components into separate services
4.  **Strong Multi-Tenancy**: Enforced at middleware, service, and repository layers
5.  **Workflow Orchestration**: Temporal provides reliable background job execution
6.  **Open Integration**: Factory pattern allows multiple payment gateway implementations

The architecture is designed for **high scalability**, **reliability**, and **flexibility** to support diverse pricing models while maintaining clean separation of concerns across all layers.