System Architecture

ButtrBase is designed as a hierarchical state engine for SaaS applications. It unifies identity, billing, and feature management into a single, cohesive graph.

High-Level Overview

The system is composed of several key pillars that interact to provide a complete backend solution:

1. Identity & RBAC: Manages users, organizations, teams, and their permissions. 2. Billing Engine: Handles subscriptions, one-time payments, and credit-based usage via Stripe and PayPal. 3. Feature Engine: Decouples code deployment from feature release using flags and entitlements. 4. Data Store: A flexible, schema-less store for attaching custom data to any entity.

Integration Flow

A typical integration follows this lifecycle:

1. Initialize: The client SDK connects using an App ID. 2. Authenticate: The user logs in via Password, Social, or Magic Link. 3. Check Entitlements: The app queries ButtrBase to see if the user has access to a specific feature (combining RBAC, Billing, and Flags). 4. Log Usage: The app reports usage events (e.g., "10 API calls") which may deduct credits or trigger billing limits. 5. Fetch Context: The app retrieves user/org specific settings from the Custom Data store.

Architecture Diagram

~~~mermaid graph TD Client[Client App] -->|Auth| ID[Identity Service] Client -->|Check Feature| FE[Feature Engine] Client -->|Log Usage| BE[Billing Engine] Client -->|Get Settings| DS[Data Store] ID -->|User Context| FE ID -->|Org Context| BE BE -->|Payment Status| FE ~~~