Backend Service (Port 8000)

The backend service is the core API gateway for MQUAD. It handles authentication, user management, tenant administration, RBAC, and Stripe billing.

Database

Database: appdb

Table	Purpose
`users`	User accounts
`tenants`	Multi-tenant organizations
`user_tenants`	User-Tenant associations
`roles`	RBAC role definitions
`permissions`	Permission definitions
`user_passkeys`	WebAuthn/FIDO2 credentials
`user_magic_links`	Magic link tokens for passwordless login
`user_password_resets`	Password reset tokens
`subscription_plans`	Subscription plan definitions
`stripe_settings`	Stripe integration config
`notification_settings`	Notification preferences

Authentication Flow

The backend supports three primary authentication methods:

1. Password-based

Standard email/password login using BCrypt for password hashing.

2. Magic Links (Passwordless)

User enters email at /api/v1/account/login/magic-link.
Backend generates a signed token and creates a user_magic_links record.
Celery task sends an email via notification-service.
User clicks link, which is validated by the backend to issue a JWT.

3. Passkeys (WebAuthn)

Supports FIDO2/WebAuthn for biometric or hardware key authentication.
Credentials stored in user_passkeys linked to the user.

RBAC System

Access Control is strictly permission-based. The standard check involves looking for specific permission strings in the user's JWT payload:

from common.rbac_helpers import is_super_admin, is_host_admin

# Super Admin: has "super:admin" or "full:access"
if is_super_admin(user.permissions):
    # Grant platform-wide access
    pass

# Host Admin: has "host:manage_tenants"
if is_host_admin(user.permissions):
    # Grant tenant management access
    pass

Stripe Integration

Manages the lifecycle of tenant subscriptions:

POST /api/v1/checkout/tenant/subscription — Starts the Stripe Checkout flow.
POST /api/v1/stripe/webhook — Listens for customer.subscription.updated and invoice.paid events to sync local state.

Celery Tasks

Managed via uv run celery:

send_email_task — Dispatches notifications.
post_tenant_creation_task — Sets up default roles/permissions for new tenants.
check_expired_trials — Runs hourly to manage trial access.

Migrations

Uses Alembic for database migrations managed by uv:

uv run alembic upgrade head