# impulse-event-app/impulse-monorepo architecture

> Architecture diagram of the GitHub repository impulse-event-app/impulse-monorepo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/impulse-event-app/impulse-monorepo
- Repository: https://github.com/impulse-event-app/impulse-monorepo

## Overview

Impulse is a venue-discovery and group-booking product with a mobile client, a venue-management dashboard, and a FastAPI backend. The user flow is to discover deals, form a solo or shared booking (or vote in a Huddle), collect participant payments, and redeem the booking; venue operators manage deals, bookings, payouts, and merchant onboarding. The backend centralizes booking rules and payment processing. The graph reflects only relationships evidenced by excerpts or the source index; the README is empty, and some dashboard and mobile feature links are therefore not asserted.

Main entry points: [`backend/main.py`](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/main.py) (FastAPI app), [`backend/booking_flow.py`](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/booking_flow.py) (Booking engine), [`mobile-sdk54/src/auth.ts`](https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/auth.ts) (Mobile auth), [`mobile-sdk54/app/(user)`](https://github.com/impulse-event-app/impulse-monorepo/tree/main/mobile-sdk54/app/(user)) (Mobile screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_mobile_ui["Mobile screens"]
  node_app_state["App state<br/>[theme.tsx]"]
  node_mobile_auth["Mobile auth<br/>[auth.ts]"]
  node_mobile_api["API client<br/>[api.ts]"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
  node_mobile_data["Deals and plans<br/>[data.ts]"]
  node_mobile_components["Shared components<br/>[components.tsx]"]
end

subgraph group_api["API and bookings"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_booking_routes["Booking routes<br/>[bookings.py]"]
  node_booking_flow["Booking engine<br/>[booking_flow.py]"]
  node_booking_logic["Booking rules<br/>[booking_logic.py]"]
  node_domain_routes["Domain routes"]
  node_webhooks["Payment webhooks<br/>[webhooks.py]"]
  node_models["Domain models<br/>[models.py]"]
end

subgraph group_venue["Venue operations"]
  node_venue_dashboard["Venue dashboard"]
  node_merchant_onboarding["Merchant onboarding<br/>[merchants.py]"]
end

subgraph group_infra["Auth and payments"]
  node_database[("SQL database<br/>[database.py]")]
  node_identity["Supabase Auth"]
  node_pinch_client["Pinch client<br/>[pinch_client.py]"]
end

node_customer(("Customer"))
node_operator(("Venue operator"))
node_pinch["Pinch Payments"]

node_customer -.->|"uses"| node_mobile_ui
node_mobile_ui -.->|"reads state"| node_app_state
node_mobile_ui -.->|"renders"| node_mobile_components
node_app_state -->|"loads bookings"| node_mobile_api
node_app_state -->|"maps deals"| node_mobile_data
node_mobile_auth -->|"calls profile API"| node_mobile_api
node_mobile_auth -->|"authenticates"| node_supabase_client
node_mobile_api -->|"uses client"| node_supabase_client
node_api_app -->|"registers"| node_booking_routes
node_api_app -->|"registers"| node_domain_routes
node_api_app -->|"sweeps deadlines"| node_booking_flow
node_booking_routes -->|"delegates booking"| node_booking_flow
node_booking_flow -->|"uses rules"| node_booking_logic
node_booking_flow -->|"updates bookings"| node_models
node_models -->|"maps tables"| node_database
node_domain_routes -.->|"accesses data"| node_database
node_booking_routes -.->|"loads records"| node_database
node_operator -.->|"manages venue"| node_venue_dashboard
node_api_app -->|"registers"| node_webhooks
node_webhooks -->|"queries transfers"| node_pinch_client
node_merchant_onboarding -->|"onboards merchant"| node_pinch_client
node_pinch_client -->|"sends requests"| node_pinch
node_mobile_auth -.->|"signs in"| node_identity

click node_mobile_ui "https://github.com/impulse-event-app/impulse-monorepo/tree/main/mobile-sdk54/app/(user)"
click node_app_state "https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/theme.tsx"
click node_mobile_auth "https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/auth.ts"
click node_mobile_api "https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/api.ts"
click node_supabase_client "https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/supabase.ts"
click node_mobile_data "https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/data.ts"
click node_mobile_components "https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/components.tsx"
click node_api_app "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/main.py"
click node_booking_routes "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/routers/bookings.py"
click node_booking_flow "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/booking_flow.py"
click node_booking_logic "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/booking_logic.py"
click node_domain_routes "https://github.com/impulse-event-app/impulse-monorepo/tree/main/backend/routers"
click node_webhooks "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/routers/webhooks.py"
click node_models "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/models.py"
click node_database "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/database.py"
click node_venue_dashboard "https://github.com/impulse-event-app/impulse-monorepo/tree/main/venue-web/src/app/dashboard"
click node_merchant_onboarding "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/routers/merchants.py"
click node_pinch_client "https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/pinch_client.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_mobile_ui,node_app_state,node_mobile_auth,node_mobile_api,node_supabase_client,node_mobile_data,node_mobile_components toneBlue
class node_api_app,node_booking_routes,node_booking_flow,node_booking_logic,node_domain_routes,node_webhooks,node_models toneAmber
class node_venue_dashboard,node_merchant_onboarding toneMint
class node_database,node_identity,node_pinch_client toneRose
class node_customer,node_operator,node_pinch toneIndigo
```

## Components

### Mobile app

- [Mobile screens](https://github.com/impulse-event-app/impulse-monorepo/tree/main/mobile-sdk54/app/(user)): `mobile-sdk54/app/(user)`
- [App state](https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/theme.tsx): `mobile-sdk54/src/theme.tsx`
- [Mobile auth](https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/auth.ts): `mobile-sdk54/src/auth.ts`
- [API client](https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/api.ts): `mobile-sdk54/src/api.ts`
- [Supabase client](https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/supabase.ts): `mobile-sdk54/src/supabase.ts`
- [Deals and plans](https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/data.ts): `mobile-sdk54/src/data.ts`
- [Shared components](https://github.com/impulse-event-app/impulse-monorepo/blob/main/mobile-sdk54/src/components.tsx): `mobile-sdk54/src/components.tsx`

### API and bookings

- [FastAPI app](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/main.py): `backend/main.py`
- [Booking routes](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/routers/bookings.py): `backend/routers/bookings.py`
- [Booking engine](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/booking_flow.py): `backend/booking_flow.py`
- [Booking rules](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/booking_logic.py): `backend/booking_logic.py`
- [Domain routes](https://github.com/impulse-event-app/impulse-monorepo/tree/main/backend/routers): `backend/routers`
- [Payment webhooks](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/routers/webhooks.py): `backend/routers/webhooks.py`
- [Domain models](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/models.py): `backend/models.py`

### Venue operations

- [Venue dashboard](https://github.com/impulse-event-app/impulse-monorepo/tree/main/venue-web/src/app/dashboard): `venue-web/src/app/dashboard`
- [Merchant onboarding](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/routers/merchants.py): `backend/routers/merchants.py`

### Auth and payments

- [SQL database](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/database.py): `backend/database.py`
- **Supabase Auth**
- [Pinch client](https://github.com/impulse-event-app/impulse-monorepo/blob/main/backend/pinch_client.py): `backend/pinch_client.py`

### Other components

- **Customer**
- **Venue operator**
- **Pinch Payments**

## Connections

- Customer → Mobile screens: uses
- Mobile screens → App state: reads state (evidence: `mobile-sdk54/app/(user)/sign-in.tsx`)
- Mobile screens → Shared components: renders (evidence: `mobile-sdk54/app/(user)/sign-in.tsx`)
- App state → API client: loads bookings (evidence: `mobile-sdk54/src/theme.tsx`)
- App state → Deals and plans: maps deals (evidence: `mobile-sdk54/src/theme.tsx`)
- Mobile auth → API client: calls profile API (evidence: `mobile-sdk54/src/auth.ts`)
- Mobile auth → Supabase client: authenticates (evidence: `mobile-sdk54/src/auth.ts`)
- API client → Supabase client: uses client (evidence: `mobile-sdk54/src/api.ts`)
- FastAPI app → Booking routes: registers (evidence: `backend/main.py`)
- FastAPI app → Domain routes: registers (evidence: `backend/main.py`)
- FastAPI app → Booking engine: sweeps deadlines (evidence: `backend/main.py`)
- Booking routes → Booking engine: delegates booking (evidence: `backend/routers/bookings.py`)
- Booking engine → Booking rules: uses rules (evidence: `backend/booking_flow.py`)
- Booking engine → Domain models: updates bookings (evidence: `backend/booking_flow.py`)
- Domain models → SQL database: maps tables (evidence: `backend/models.py`)
- Domain routes → SQL database: accesses data (evidence: `backend/routers/webhooks.py`)
- Booking routes → SQL database: loads records (evidence: `backend/routers/bookings.py`)
- Venue operator → Venue dashboard: manages venue
- FastAPI app → Payment webhooks: registers (evidence: `backend/main.py`)
- Payment webhooks → Pinch client: queries transfers (evidence: `backend/routers/webhooks.py`)
- Merchant onboarding → Pinch client: onboards merchant (evidence: `backend/routers/merchants.py`)
- Pinch client → Pinch Payments: sends requests (evidence: `backend/pinch_client.py`)
- Mobile auth → Supabase Auth: signs in
