---
title: Concepts
path: concepts
status: published
---

# Concepts

Background and mental models for ScaiControl. Read these to understand WHY the system is shaped this way — the reference pages will then make sense as a description of the result rather than a list of facts.

| Page | What it covers |
|---|---|
| [Architecture](./concepts/architecture) | Components, data flow, the position of ScaiControl in the ScaiLabs network |
| [Multi-tenancy](./concepts/multi-tenancy) | Partner → Tenant → User hierarchy, ORM-layer auto-filtering, JWT-driven tenant context |
| [Authentication & RBAC](./concepts/authentication-and-rbac) | ScaiKey JWTs, scopes, roles, `require_permission`, service-to-service tokens |
| [Subscriptions](./concepts/subscriptions) | State machine, lifecycle endpoints, reaper + trial-monitor workers, pack subs |
| [Service packs](./concepts/service-packs) | Bundled subscriptions, parent–child model, pack-pricing modes |
| [Plans & pricing](./concepts/plans-and-pricing) | Plan schema, tier conventions, MRR normalisation, usage pricing |
| [Billing profiles](./concepts/billing-profiles) | Buyer/seller data, snapshot at finalize, template resolution chain |
| [Invoice lifecycle](./concepts/invoice-lifecycle) | State machine, numbering, finalize flow, credit notes, immutability |
| [VAT & reverse charge](./concepts/vat-and-reverse-charge) | The 4 VAT rules, country rates, UNCL categories, legal notes |
| [Templates](./concepts/templates) | `(name, document_type, language)` triple, Jinja-as-HTML encoding, WeasyPrint quirks |
| [Webhooks](./concepts/webhooks) | 14 topics, envelope, dispatcher fan-out pattern, delivery semantics |

When you're ready for action, jump to the [Reference](./reference) section.