How kaioh17/maison-core works
Maison is a multi-tenant backend for premium ground-transport operators. Riders and operators use role-scoped API routes to manage tenant-branded fleets and bookings; booking operations cover creation, cancellation, approval, and confirmation, with Mapbox supplying routing/pricing inputs and Stripe supporting ride payments and separate SaaS subscriptions. Drivers and tenants manage ride and fleet operations, while analytics, email, PWA branding, and tenant configuration provide supporting capabilities. The excerpts show selected service and persistence behavior; edges for unsampled subsystems are included only where the README or route documentation establishes the capability.
Main entry points: booking_services.py Booking lifecycle and pricing · main.py FastAPI application · database.py Tenant-scoped DB sessions · stripe_tier_service.py Stripe checkout and plans
Components 28
API and identity
- FastAPI application
backend/app/main.py - Authentication routes
backend/app/api/routers/auth.py - Token and login logic
backend/app/api/services/auth_service.py - JWT and authorization
backend/app/api/core/security.py
Tenant operations
- Tenant routes
backend/app/api/routers/tenants.py - Tenant and fleet operations
backend/app/api/services/tenants_service.py - Tenant configuration routes
backend/app/api/routers/tenant_settings.py - Tenant configuration logic
backend/app/api/services/tenant_settings_service.py - Driver portal routes
backend/app/api/routers/drivers.py - Analytics routes
backend/app/api/routers/analytics.py
Ride lifecycle
- Booking routes
backend/app/api/routers/bookings.py - Booking lifecycle and pricing
backend/app/api/services/booking_services.py - Booking and ride data
backend/app/models/booking.py
Payments and billing
- Stripe checkout and plans
backend/app/api/services/stripe_services/stripe_tier_service.py - Stripe webhook routes
backend/app/api/routers/webhooks.py - Webhook processing
backend/app/api/services/stripe_services/webhooks.py - Tenant plan context
backend/app/api/services/service_context.py
Data and integrations
- Transactional email
backend/app/api/services/email_services/email_services.py - White-label PWA routes
backend/app/api/routers/pwa.py - Tenant-scoped DB sessions
backend/app/db/database.py
Other components
- Rider
- Tenant operator
- Driver
- Mapbox
- Stripe
- Resend
- PostgreSQL
- Redis rate limits
Connections 27
- FastAPI application → Authentication routes: mounts
- FastAPI application → Tenant routes: mounts
- FastAPI application → Redis rate limits: rate limits
- Rider → FastAPI application: uses API
- Tenant operator → FastAPI application: uses API
- Driver → FastAPI application: uses API
- Authentication routes → Token and login logic: handles login
- Token and login logic → JWT and authorization: creates tokens
- Tenant routes → Tenant and fleet operations: handles operations
- Tenant configuration routes → Tenant configuration logic: handles settings
- Driver portal routes → Tenant and fleet operations: driver operations
- Analytics routes → Booking lifecycle and pricing: ride analytics
- Booking routes → Booking lifecycle and pricing: handles bookings
- Booking lifecycle and pricing → Booking and ride data: persists rides
- Booking lifecycle and pricing → Mapbox: uses routing inputs
- Booking lifecycle and pricing → Stripe checkout and plans: starts checkout
- Stripe checkout and plans → Stripe: creates sessions
- Stripe webhook routes → Webhook processing: dispatches events
- Webhook processing → Stripe: verifies events
- Webhook processing → Tenant-scoped DB sessions: updates billing
- Stripe checkout and plans → Tenant-scoped DB sessions: reads plan state
- Tenant plan context → Tenant-scoped DB sessions: resolves tenant plan
- Transactional email → Resend: sends email
- White-label PWA routes → Tenant configuration logic: resolves branding
- Booking lifecycle and pricing → Tenant-scoped DB sessions: reads and writes
- Tenant and fleet operations → Tenant-scoped DB sessions: reads and writes
- Tenant-scoped DB sessions → PostgreSQL: opens sessions