Open-source B2B usage metering, entitlements, and billing platform.
Meterplex is the backend that powers a SaaS or AI API company. It defines plans and entitlements, decides whether a tenant can use a feature, tracks usage events, enforces quotas and rate limits, calculates billable usage, handles payments and webhooks, and provides auditability with replay and reconciliation. Every mutation is recorded to an immutable audit log for compliance and forensics.
Modular monolith - one deployable unit with strict module boundaries. Each domain (tenants, billing, usage, payments) is a self-contained NestJS module that can be extracted into a microservice when scale demands it.
┌─────────────────────────────────────────────────────┐
│ NestJS App │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Tenants │ │ Usage │ │ Billing │ ...more │
│ │ Module │ │ Module │ │ Module │ modules │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ┌────▼─────────────▼────────────▼─────┐ │
│ │ Prisma (PostgreSQL) │ │
│ └─────────────────────────────────────┘ │
│ │ │ │ │
│ ┌────▼──┐ ┌─────▼───┐ ┌────▼──┐ │
│ │ Redis │ │ Kafka │ │ Cron │ │
│ └───────┘ └─────────┘ └───────┘ │
└─────────────────────────────────────────────────────┘
| Domain | Technology | Purpose |
|---|---|---|
| Backend | NestJS 11 | Modular backend architecture |
| Language | TypeScript 6.0 | Type-safe development |
| Database | PostgreSQL 18 + Prisma 7 | Persistent storage & ORM |
| Messaging | Apache Kafka 4.2 | Event-driven async processing |
| Caching | Redis 8 | Distributed caching & rate limiting |
| DevOps | GitHub Actions, Renovate | 2027-standard security & automation |
| Automation | Chitrank Action | Centralized, hardened bot-driven governance |
| Quality | Vitest, Lefthook | Unit testing & high-performance git hooks |
| Docs | MkDocs Material | Technical documentation & changelog |
| API Tools | Bruno, Swagger, Scalar | API testing & documentation |
Prerequisites: Node.js >= 24, pnpm >= 9, Docker
# 1. Clone the repository
git clone https://github.com/chitrank2050/meterplex.git
# 2. Enter the project
cd meterplex
# 3. One-command setup (installs deps, starts docker, seeds DB)
pnpm dev:init| Command | Description |
|---|---|
pnpm dev:init |
Interactive Wizard: Multi-select setup, maintenance, and deep clean |
pnpm setup:all |
Standard setup: install deps + start infrastructure + seed DB |
pnpm setup:fresh |
Hard Reset: Wipes all data/deps and performs a fresh setup |
pnpm start:dev |
Starts the NestJS application in watch mode |
pnpm test |
Runs the full test suite via Vitest |
pnpm docker:up |
Starts Postgres, Kafka, and Redis in the background |
pnpm db:studio |
Opens Prisma Studio to visualize your database |
pnpm lint |
Runs TypeScript, Markdown, and GitHub Action linters |
The app runs at http://localhost:3000. API docs at http://localhost:3000/api/docs. Health check at http://localhost:3000/health.
meterplex/
├── .github/ # GitHub Actions workflows & templates
│ ├── workflows/ # CI/CD, Security, & Maintenance pipelines
│ └── ISSUE_TEMPLATE/ # Standardized issue templates
├── src/
│ ├── common/ # Cross-cutting concerns
│ │ ├── constants/ # Error codes, app constants
│ │ ├── decorators/ # @CurrentUser, @TenantId, @Roles
│ │ ├── dto/ # Shared DTOs (error response, pagination)
│ │ ├── filters/ # Global exception filter
│ │ ├── guards/ # TenantGuard, RolesGuard
│ │ ├── interceptors/ # (Phase 2) Audit log interceptor
│ │ ├── middleware/ # Correlation ID, request logging
│ │ ├── pipes/ # (future) Custom validation pipes
│ │ ├── interfaces/ # (future) Shared TypeScript types
│ │ └── utils/ # Prisma error helpers
│ ├── config/ # Environment validation and ConfigModule
│ ├── prisma/ # PrismaService and PrismaModule
│ ├── health/ # Health check endpoint
│ └── modules/
│ ├── tenants/ # Tenant CRUD, tenant-scoped queries
│ ├── users/ # User management, tenant membership
│ ├── auth/ # JWT, Passport, refresh tokens, password reset
│ └── api-keys/ # Server-to-server key management + auth guard
├── prisma/
│ ├── schema.prisma # Database schema (single source of truth)
│ ├── seed.ts # Development seed data
│ └── migrations/ # Prisma migration history
├── bruno/ # API testing collections
├── docs/ # MkDocs documentation source
├── assets/ # Logos and static assets
├── lefthook.yml # High-performance Git hooks
├── cliff.toml # Automated changelog configuration
├── package.json # Scripts & dependencies
├── pnpm-lock.yaml # Deterministic lockfile
└── docker-compose.yml # Postgres, Kafka, Redis
| Script | Description |
|---|---|
pnpm start:dev |
Start with hot reload |
pnpm start:prod |
Start production build |
pnpm build |
Compile TypeScript |
pnpm test |
Run unit tests |
pnpm test:e2e |
Run end-to-end tests |
pnpm lint |
Lint and fix code |
pnpm db:generate |
Regenerate Prisma client |
pnpm db:migrate:dev |
Create and apply migration |
pnpm db:migrate:deploy |
Apply migrations (CI/prod) |
pnpm db:seed |
Seed development data |
pnpm db:studio |
Open Prisma data browser |
pnpm docker:up |
Start Docker containers |
pnpm docker:down |
Stop containers and remove volumes |
pnpm docker:logs |
Tail container logs |
| Method | Path | Description |
|---|---|---|
| GET | /health |
Infrastructure health check |
| - | /api/docs |
Swagger UI (development only) |
More endpoints are added with each phase.
🚀 Live Docs: chitrank2050.github.io/meterplex
Detailed documentation is available in the docs/ folder and on GitHub Pages:
- Architecture - System design, module boundaries, data flow
- Development - Setup guide, conventions, workflow
- API - API design decisions, versioning, error format
- Phases - Build log for each development phase
| Phase | Focus | Status |
|---|---|---|
| 0 | Project setup, infrastructure, foundations | ✅ Complete |
| 1 | Auth, tenants, users, plans, subscriptions | ✅ Complete |
| 2 | Entitlements and usage tracking | 🔜 Next |
| 3 | Billing, invoices, payments | - |
| 4 | Kafka event pipeline, async processing | - |
| 5 | Observability, rate limiting, hardening | - |
MIT - see LICENSE for details.
If you use Meterplex in your project, a star or credit is appreciated.
❤️ Developed by Chitrank Agnihotri
