Skip to main content

Introduction

BSSentinel is a multi-tenant billing and BSS platform for telecom-style usage billing. core-api is its API service - a FastAPI application backed by PostgreSQL that exposes tenants, accounts, customers, subscribers, plans, rates, balances and usage lines over a REST API, and acts as its own identity provider (local users, roles, sessions and API keys). BSSentinel is expected to grow more services alongside core-api, which is why the two names are distinct. This documentation site covers core-api only.

Both BSSentinel (the project name) and core-api (this service's name) are configurable via the PROJECT_NAME and SERVICE_NAME environment variables in app/core/config.py rather than hardcoded. Domain terminology follows the BillRun documentation (docs.bill.run); see Definitions.

Scope​

core-api covers the telecom billing domain - usage lines (CDR-style records), rating against a rate catalog, plans, balances and prepaid includes - on a stack chosen for type safety, async I/O, and a relational data model: Python 3.13+, FastAPI, Pydantic v2, SQLAlchemy 2.0 (async), Alembic, and PostgreSQL.

Current status​

core-api serves the tenant, account, subscriber, plan, rate, balance and usage-line domains, its own identity provider (users, roles, sessions, API keys), connectors with scheduled syncs, support tickets, the shared mailbox and quick search; see Architecture and Reference. Services, discounts, charges, tax and billing cycles are out of scope (Current feature scope).

Stack​

  • Python 3.13+, managed via mise
  • FastAPI + Pydantic v2 - REST API and validation, with interactive OpenAPI/Swagger docs served at /docs on the running API
  • SQLAlchemy 2.0 (async) + Alembic
    • ORM and schema migrations against PostgreSQL
  • uv - dependency management and script running
  • Docker Compose - local API + PostgreSQL + Meilisearch stack

Where to go next​