# kaioh17/maison-core architecture

> Architecture diagram of the GitHub repository kaioh17/maison-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaioh17/maison-core
- Repository: https://github.com/kaioh17/maison-core

## Overview

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: [`backend/app/api/services/booking_services.py`](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/booking_services.py) (Booking lifecycle and pricing), [`backend/app/main.py`](https://github.com/kaioh17/maison-core/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/db/database.py`](https://github.com/kaioh17/maison-core/blob/main/backend/app/db/database.py) (Tenant-scoped DB sessions), [`backend/app/api/services/stripe_services/stripe_tier_service.py`](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/stripe_services/stripe_tier_service.py) (Stripe checkout and plans)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_auth_service["Token and login logic<br/>[auth_service.py]"]
  node_auth_core["JWT and authorization<br/>[security.py]"]
end

subgraph group_operations["Tenant operations"]
  node_tenant_routes["Tenant routes<br/>[tenants.py]"]
  node_tenant_service["Tenant and fleet operations<br/>[tenants_service.py]"]
  node_settings_routes["Tenant configuration routes<br/>[tenant_settings.py]"]
  node_settings_service["Tenant configuration logic"]
  node_driver_routes["Driver portal routes<br/>[drivers.py]"]
  node_analytics_routes["Analytics routes<br/>[analytics.py]"]
end

subgraph group_rides["Ride lifecycle"]
  node_booking_routes["Booking routes<br/>[bookings.py]"]
  node_booking_service["Booking lifecycle and pricing"]
  node_booking_models[("Booking and ride data<br/>[booking.py]")]
end

subgraph group_billing["Payments and billing"]
  node_stripe_service["Stripe checkout and plans"]
  node_webhook_routes["Stripe webhook routes<br/>[webhooks.py]"]
  node_webhook_service["Webhook processing<br/>[webhooks.py]"]
  node_service_context["Tenant plan context<br/>[service_context.py]"]
end

subgraph group_platform["Data and integrations"]
  node_email_service["Transactional email<br/>[email_services.py]"]
  node_pwa_routes["White-label PWA routes<br/>[pwa.py]"]
  node_db_session["Tenant-scoped DB sessions<br/>[database.py]"]
end

node_rider(("Rider"))
node_operator(("Tenant operator"))
node_driver_actor(("Driver"))
node_mapbox["Mapbox"]
node_stripe["Stripe"]
node_resend["Resend"]
node_postgres[("PostgreSQL")]
node_redis[("Redis rate limits")]

node_api_app -->|"mounts"| node_auth_routes
node_api_app -->|"mounts"| node_tenant_routes
node_api_app -->|"rate limits"| node_redis
node_rider -->|"uses API"| node_api_app
node_operator -->|"uses API"| node_api_app
node_driver_actor -->|"uses API"| node_api_app
node_auth_routes -->|"handles login"| node_auth_service
node_auth_service -->|"creates tokens"| node_auth_core
node_tenant_routes -->|"handles operations"| node_tenant_service
node_settings_routes -->|"handles settings"| node_settings_service
node_driver_routes -->|"driver operations"| node_tenant_service
node_analytics_routes -.->|"ride analytics"| node_booking_service
node_booking_routes -->|"handles bookings"| node_booking_service
node_booking_service -->|"persists rides"| node_booking_models
node_booking_service -.->|"uses routing inputs"| node_mapbox
node_booking_service -.->|"starts checkout"| node_stripe_service
node_stripe_service -->|"creates sessions"| node_stripe
node_webhook_routes -->|"dispatches events"| node_webhook_service
node_webhook_service -->|"verifies events"| node_stripe
node_webhook_service -->|"updates billing"| node_db_session
node_stripe_service -->|"reads plan state"| node_db_session
node_service_context -->|"resolves tenant plan"| node_db_session
node_email_service -->|"sends email"| node_resend
node_pwa_routes -.->|"resolves branding"| node_settings_service
node_booking_service -->|"reads and writes"| node_db_session
node_tenant_service -->|"reads and writes"| node_db_session
node_db_session -->|"opens sessions"| node_postgres

click node_api_app "https://github.com/kaioh17/maison-core/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/auth.py"
click node_auth_service "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/auth_service.py"
click node_auth_core "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/core/security.py"
click node_tenant_routes "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/tenants.py"
click node_tenant_service "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/tenants_service.py"
click node_settings_routes "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/tenant_settings.py"
click node_settings_service "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/tenant_settings_service.py"
click node_driver_routes "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/drivers.py"
click node_analytics_routes "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/analytics.py"
click node_booking_routes "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/bookings.py"
click node_booking_service "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/booking_services.py"
click node_booking_models "https://github.com/kaioh17/maison-core/blob/main/backend/app/models/booking.py"
click node_stripe_service "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/stripe_services/stripe_tier_service.py"
click node_webhook_routes "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/webhooks.py"
click node_webhook_service "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/stripe_services/webhooks.py"
click node_service_context "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/service_context.py"
click node_email_service "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/email_services/email_services.py"
click node_pwa_routes "https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/pwa.py"
click node_db_session "https://github.com/kaioh17/maison-core/blob/main/backend/app/db/database.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_app,node_auth_routes,node_auth_service,node_auth_core toneBlue
class node_tenant_routes,node_tenant_service,node_settings_routes,node_settings_service,node_driver_routes,node_analytics_routes,node_postgres,node_redis toneAmber
class node_booking_routes,node_booking_service,node_booking_models toneMint
class node_stripe_service,node_webhook_routes,node_webhook_service,node_service_context toneRose
class node_email_service,node_pwa_routes,node_db_session,node_rider,node_operator,node_driver_actor,node_mapbox,node_stripe,node_resend toneIndigo
```

## Components

### API and identity

- [FastAPI application](https://github.com/kaioh17/maison-core/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/auth.py): `backend/app/api/routers/auth.py`
- [Token and login logic](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/auth_service.py): `backend/app/api/services/auth_service.py`
- [JWT and authorization](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/core/security.py): `backend/app/api/core/security.py`

### Tenant operations

- [Tenant routes](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/tenants.py): `backend/app/api/routers/tenants.py`
- [Tenant and fleet operations](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/tenants_service.py): `backend/app/api/services/tenants_service.py`
- [Tenant configuration routes](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/tenant_settings.py): `backend/app/api/routers/tenant_settings.py`
- [Tenant configuration logic](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/tenant_settings_service.py): `backend/app/api/services/tenant_settings_service.py`
- [Driver portal routes](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/drivers.py): `backend/app/api/routers/drivers.py`
- [Analytics routes](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/analytics.py): `backend/app/api/routers/analytics.py`

### Ride lifecycle

- [Booking routes](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/bookings.py): `backend/app/api/routers/bookings.py`
- [Booking lifecycle and pricing](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/booking_services.py): `backend/app/api/services/booking_services.py`
- [Booking and ride data](https://github.com/kaioh17/maison-core/blob/main/backend/app/models/booking.py): `backend/app/models/booking.py`

### Payments and billing

- [Stripe checkout and plans](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/stripe_services/stripe_tier_service.py): `backend/app/api/services/stripe_services/stripe_tier_service.py`
- [Stripe webhook routes](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/webhooks.py): `backend/app/api/routers/webhooks.py`
- [Webhook processing](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/stripe_services/webhooks.py): `backend/app/api/services/stripe_services/webhooks.py`
- [Tenant plan context](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/service_context.py): `backend/app/api/services/service_context.py`

### Data and integrations

- [Transactional email](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/services/email_services/email_services.py): `backend/app/api/services/email_services/email_services.py`
- [White-label PWA routes](https://github.com/kaioh17/maison-core/blob/main/backend/app/api/routers/pwa.py): `backend/app/api/routers/pwa.py`
- [Tenant-scoped DB sessions](https://github.com/kaioh17/maison-core/blob/main/backend/app/db/database.py): `backend/app/db/database.py`

### Other components

- **Rider**
- **Tenant operator**
- **Driver**
- **Mapbox**
- **Stripe**
- **Resend**
- **PostgreSQL**
- **Redis rate limits**

## Connections

- 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