SaaS Platform Development

The hardest part of SaaS is not building features. It is keeping boundaries intact while the product grows. A platform can ship dashboards, teams, billing, settings, reports, and APIs quickly — then quietly accumulate risk because tenant isolation, entitlement logic, subscription state, and internal admin actions are scattered across the codebase.

This case study documents how Brivox approached SaaS platform development around explicit architectural boundaries: tenant-scoped authorization, billing as a dedicated domain, runtime entitlement enforcement, safe progressive rollout, observability, and security-by-design for multi-tenant production systems.

The objective was not only to launch a SaaS product. The objective was to create a foundation that could evolve safely as customers, plans, permissions, integrations, and operational needs became more complex.

Executive Summary

Brivox engineered a SaaS foundation where core platform responsibilities were separated into clear domains: identity and authorization, tenant boundaries, billing and subscriptions, entitlements, feature delivery, observability, and internal operations. The architecture reduced entitlement drift, protected tenant data boundaries, and made platform evolution more predictable.

The work focused on four outcomes:

• Tenant boundary clarity. Every tenant-owned resource had explicit scoping rules and access checks.
• Runtime entitlement enforcement. Plan rules were enforced by backend policies, not just UI visibility.
• Billing isolation. Subscription state, invoices, provider events, and access state were modeled as a dedicated domain.
• Safe platform evolution. Feature flags, rollout controls, observability, and audit trails supported controlled growth.

Project Context

The platform needed to support customers with different plans, roles, usage limits, subscription states, and feature access. It also needed to support internal teams managing customer accounts, debugging billing issues, observing tenant-specific behavior, and rolling out new capabilities safely.

These requirements introduced architectural pressure:

• Users may belong to multiple tenants with different roles.
• Tenants may have different plans, add-ons, limits, and billing states.
• Features may be released to specific cohorts before general availability.
• Billing provider events may arrive asynchronously and must update internal access state.
• Internal admin tools must help customers without bypassing tenant boundaries.
• Observability must show platform health globally and per tenant where needed.

The product could not rely on frontend checks or informal role rules. The platform needed a coherent architecture for deciding who can do what, inside which tenant, under which plan, and under which billing condition.

The Challenge

The central challenge was preventing boundary drift. Boundary drift happens when the product initially enforces rules correctly, but over time, new features implement their own permission checks, billing checks, plan checks, and admin bypasses. Eventually no one can prove what a tenant is allowed to access.

The risk areas were practical:

• Entitlement drift. Billing state changes but runtime access does not update consistently.
• Tenant-scoping mistakes. Queries, jobs, caches, or files accidentally omit tenant context.
• Feature rollout risk. New features reach the wrong plan, tenant, or cohort.
• Authorization inconsistency. APIs, UI, admin tools, and background jobs check access differently.
• Audit gaps. Sensitive actions happen without enough evidence for support, security, or compliance review.
• Billing coupling. Provider-specific billing logic leaks into unrelated product code.

Project Objectives

The objectives were defined around platform correctness and long-term maintainability.

Risk Areas

The project focused on the risks that commonly break SaaS platforms as they grow:

1. Cross-tenant leakage. Data from one tenant exposed to another through query, cache, file, or job mistakes.
2. Plan bypass. Users call APIs for features not included in their plan because only the UI hides them.
3. Billing drift. Payment provider state differs from internal subscription and entitlement state.
4. Unsafe admin operations. Internal support tools bypass the same policies users are subject to.
5. Uncontrolled rollout. New features affect all tenants before reliability or commercial rules are validated.
6. Observability blind spots. Global health looks normal while a specific tenant, plan, or rollout cohort is failing.

Architecture Overview

The platform architecture separated SaaS responsibilities into explicit domains.

Identity & Sessions
  ↓
Tenant Resolution
  ↓
Membership / Roles
  ↓
Authorization Policies
  ↓               ↘
Tenant-Scoped Data   Entitlement Service
  ↓                    ↓
Product Domains      Billing Domain
  ↓                    ↓
Feature Rollouts / Observability / Audit

The major architecture layers were:

1. Identity & Sessions. Authenticated users, service accounts, sessions, and API keys.
2. Tenant Resolution. Active tenant selected through workspace, domain, route, token, or API key.
3. Membership & Roles. User relationship to tenant and allowed role scope.
4. Authorization Policies. Central decisions for actions across APIs, jobs, and internal tools.
5. Entitlement Service. Runtime capabilities derived from plan, billing state, add-ons, limits, and overrides.
6. Billing Domain. Subscriptions, invoices, usage, provider webhooks, and reconciliation.
7. Feature Delivery. Flags, cohorts, progressive rollouts, and kill switches.
8. Audit & Observability. Security events, billing events, tenant dimensions, and operational dashboards.

Implementation Approach

The implementation started by defining boundaries before building features on top. The goal was to create reusable platform primitives: tenant context, scoped repositories, policy checks, entitlement evaluation, billing events, and audit logs.

1. Tenant context as a first-class object

Every protected request resolved a trusted tenant context before accessing tenant-owned data.

{
  "tenantId": "ten_acme",
  "actorId": "usr_42",
  "membershipRole": "admin",
  "permissions": ["projects:read", "billing:update"],
  "planCode": "business",
  "billingStatus": "active",
  "entitlements": ["exports.csv", "team_members", "advanced_reports"]
}

This context traveled through controllers, services, repositories, jobs, telemetry, and audit events. It prevented each layer from guessing tenant identity independently.

2. Tenant-scoped data access

Data access patterns required tenant context by construction. Tenant-owned resources were loaded through scoped repositories instead of raw global queries.

const repo = createTenantRepo(context);
const project = await repo.projects.findById(projectId);

if (!project) {
  return notFound();
}

This reduced accidental cross-tenant reads and made reviews easier because scope was enforced at the repository boundary.

3. Policy-first authorization

Actions were authorized through named policies rather than scattered role checks.

const decision = await policies.billing.updatePaymentMethod({
  actor: context,
  tenant,
  source: 'dashboard'
});

if (!decision.allow) {
  audit.warn('billing_update_denied', {
    tenantId: context.tenantId,
    actorId: context.actorId,
    reason: decision.reason
  });
  return forbidden();
}

Policy decisions included reasons so product UX, support workflows, and audit trails could distinguish missing permissions from plan limits or billing suspension.

Tenant Boundaries

Tenant boundaries were enforced across more than database records. The platform treated tenant context as mandatory for:

• Database queries.
• Cache keys.
• File storage paths.
• Signed URLs.
• Background job payloads.
• API keys and service tokens.
• Metrics and logs.
• Admin support actions.

// Cache key includes tenant and feature context
const cacheKey = [
  'tenant', context.tenantId,
  'dashboard',
  'summary',
  'plan', context.planCode
].join(':');

This prevented a common SaaS failure: correct database scoping but unsafe cache, file, or job behavior.

Entitlement Enforcement

The entitlement system defined what each tenant could use at runtime. Entitlements were derived from plan, add-ons, billing status, trial state, usage limits, manual overrides, and feature rollout rules.

The platform separated related but different concepts:

async function canCreateTeamMember(context) {
  if (!context.permissions.includes('members.invite')) return deny('missing_permission');
  if (!context.entitlements.includes('team_members')) return deny('not_in_plan');
  if (context.billingStatus === 'suspended') return deny('billing_suspended');

  const usage = await usage.current(context.tenantId, 'members.active');
  if (usage >= context.limits.members) return deny('limit_reached');

  return allow();
}

This model prevented feature access from drifting away from billing and plan rules.

Billing Domain

Billing was modeled as a dedicated domain instead of being scattered across product controllers. The payment provider remained responsible for payment collection, but the platform owned the internal subscription and entitlement model.

The billing domain included:

• Plans and pricing codes.
• Subscriptions and billing status.
• Invoices and provider references.
• Usage meters and limits.
• Add-ons and overrides.
• Provider webhook events.
• Entitlement recalculation.
• Billing audit events.

billing_event:
  type: subscription.updated
  tenant_id: ten_acme
  provider: stripe
  provider_event_id: evt_9f12
  previous_status: trialing
  next_status: active
  recalculated_entitlements: true

This gave the platform a local source of truth for runtime access while still syncing with provider events through verified webhooks and reconciliation.

Progressive Feature Rollouts

New features were delivered through rollout controls instead of all-at-once exposure. This helped reduce platform risk and separate deployment from release.

Rollout rules could target:

• Internal tenants.
• Beta customers.
• Specific plans.
• Enterprise cohorts.
• Percentage buckets.
• Regions or industries.
• Manual allowlists.

feature: advanced_reports_v2
status: enabled
required_entitlement: advanced_reports
rollout:
  internal: true
  beta_tenants: true
  percentage: 15
kill_switch: true

Feature flags were treated as temporary operational controls, not permanent architecture. Each flag needed an owner and cleanup path.

Observability & Audit

SaaS observability needed to answer platform-level and tenant-level questions. A service can appear healthy globally while a specific tenant, plan, or rollout cohort experiences failure.

Signals included:

• Request rate, latency, and errors by service.
• Tenant-safe dimensions for investigation.
• Entitlement denials and reasons.
• Billing webhook processing status.
• Feature rollout exposure and related errors.
• Admin actions with tenant, actor, reason, and result.
• Usage-limit warnings and hard blocks.

{
  "event": "entitlement_denied",
  "tenant_id": "ten_acme",
  "actor_id": "usr_42",
  "entitlement": "exports.csv",
  "reason": "not_in_plan",
  "plan_code": "starter",
  "request_id": "req_91f"
}

Audit logs were especially important for billing changes, role changes, owner transfers, support access, exports, API key actions, and manual overrides.

Security & Reliability Decisions

The SaaS platform was hardened around multi-tenant risk. Security controls focused on protecting boundaries, reducing internal bypasses, and making sensitive actions traceable.

• Tenant-scoped authorization. Policies checked tenant, role, permission, entitlement, and object state.
• API key scoping. API keys belonged to tenants and carried explicit scopes.
• Admin tool guardrails. Internal actions required tenant selection, permission, reason, and audit record.
• Webhook verification. Billing provider events were signed, stored, deduplicated, and processed asynchronously.
• Runtime entitlement checks. Backend APIs enforced plan rules, not just frontend UI.
• Cross-tenant tests. Automated tests attempted access between tenants for critical resources.

Outcome

The resulting platform foundation gave the product a stronger base for growth. Tenant access, billing state, and feature availability were no longer treated as separate one-off checks. They became part of a shared platform model.

The outcome can be summarized in four improvements:

• Tenant boundaries became clearer. Data access, jobs, caches, and audit events carried tenant context.
• Entitlement behavior became consistent. Plan rules were enforced at runtime across API and product flows.
• Billing became more reliable. Provider events updated local billing state and recalculated entitlements.
• Feature rollout became safer. New capabilities could be exposed progressively with kill switches and observability.

Engineering Notes

The project reinforced several important SaaS architecture lessons:

1. Resolve tenant context once and propagate it deliberately.
2. Never rely on UI-only plan enforcement.
3. Keep billing as a domain, not a payment-provider afterthought.
4. Design internal admin tools as privileged product surfaces.
5. Test cross-tenant access continuously.
6. Keep feature flags owned and temporary.

What This Proves

This case study proves that SaaS scalability is not only about handling more users. It is about preserving correctness as customers, plans, features, teams, and internal operations multiply.

A SaaS platform becomes trustworthy when every layer agrees on the same boundaries: who the actor is, which tenant they belong to, what the tenant is entitled to use, what billing state allows, what rollout rules expose, and what audit trail records the action.

That is the difference between a product that merely sells subscriptions and a platform that can scale with confidence.