# charry07/lavaca-app architecture

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

- Interactive diagram: https://gitdiagram.com/charry07/lavaca-app
- Repository: https://github.com/charry07/lavaca-app

## Overview

1. **Repository shape**
This is a pnpm monorepo with three runtime areas: `frontend/` for the Expo mobile app, `packages/` for shared TypeScript code, and `supabase/` for backend schema/functions. There is no standalone Express/API server; the client talks directly to Supabase services.

2. **Client application boundary**
`frontend/` is the main user-facing app, built with React Native + Expo SDK 54 and organized around Expo Router. The top-level routes map to product flows: tabs for home/feed/groups/history/profile, plus dedicated screens for create, join, login, group detail, and live session detail.

3. **App shell and cross-cutting state**
The client bootstraps shared concerns through contexts such as `AuthContext`, `ThemeContext`, and `I18nContext`. These provide session state, dark/light styling, and localization across the routed screens.

4. **Feature-oriented UI layer**
Reusable UI is split by domain rather than by generic atoms: `components/brand` for QR/logo/roulette visuals, `components/payments` for payment-account and debt instructions, `components/feedback` for error/empty/toast states, and `components/ui` for cards, avatars, skeletons, and status pills. This makes the visual language consistent across session, feed, and payment flows.

5. **Domain flows in the app**
The main product flow is “create a payment session, share via code/QR, join, split, track status, and close.” Supporting flows include group management, payment account setup, participant history, and a social feed of session activity.

6. **Data access boundary**
`frontend/src/services/api.ts` is the central client-side integration point for Supabase-backed data operations. The shared `packages/api` package exposes a reusable Supabase client layer, while `packages/types` holds the canonical domain types and utilities used by both app and backend-adjacent code.

7. **Realtime synchronization**
Live session updates are driven by Supabase Realtime rather than polling. The hooks `useSocket` and `useSessionSocket` subscribe to session and related table changes so the UI can reflect participant status, joins, approvals, and feed events as they happen.

8. **Backend architecture**
Backend state lives in Supabase Postgres, with schema changes tracked in `supabase/migrations/` and initial data in `supabase/seed.sql`. The schema includes sessions, participants, groups, payment accounts, feed events, and push-token related tables/fields, with access controlled by Supabase Auth and RLS policies.

9. **Edge-function layer**
Supabase Edge Functions provide the few server-side behaviors that cannot be handled purely from the client. The notable function is `send-notification`, which uses a shared CORS helper, and the README also describes an AI copilot flow that calls GitHub Models (`gpt-4o-mini`) through an edge function.

10. **AI and notification integration**
AI is an optional product feature, not a core runtime dependency; it suggests split modes and generates payment reminders when enabled. Notifications are similarly backend-mediated, with the frontend holding push-token-related client code and the Supabase function handling delivery.

11. **Platform and device-specific concerns**
The app includes mobile-native capabilities such as camera permissions, QR scanning, and local/native storage utilities. These are isolated in `utils/`, keeping device APIs out of the domain and backend layers.

12. **Operational/tooling boundary**
The repo includes Expo and Supabase configuration, a GitHub Actions CI workflow, and helper scripts for environment loading and project checks. The `.agents`, `.claude`, `.codebuddy`, and `.continue` trees are assistant skill metadata, not part of the runtime architecture.

13. **How data moves through the system**
A typical flow is: user authenticates via Supabase Auth, the app reads/writes session data in Postgres through the shared client, and Realtime pushes updates back into the active screen. If the user triggers AI-assisted actions or notifications, those requests are routed through Supabase Edge Functions instead of the mobile client directly calling third-party services.

Main entry points: [`frontend/app/_layout.tsx`](https://github.com/charry07/lavaca-app/blob/main/frontend/app/_layout.tsx) (App shell), [`frontend/src/services/api.ts`](https://github.com/charry07/lavaca-app/blob/main/frontend/src/services/api.ts) (Client API), [`frontend/app/(tabs)/_layout.tsx`](https://github.com/charry07/lavaca-app/blob/main/frontend/app/(tabs)/_layout.tsx) (Main tabs), [`packages/api/src/client.ts`](https://github.com/charry07/lavaca-app/blob/main/packages/api/src/client.ts) (Supabase client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
end

subgraph group_frontend["Mobile app"]
  node_frontend_app_shell["App shell<br/>Expo Router shell<br/>[_layout.tsx]"]
  node_frontend_tabs["Main tabs<br/>tab routes<br/>[_layout.tsx]"]
  node_frontend_flow_screens["Flow screens<br/>route screens"]
  node_frontend_auth["Auth context<br/>session state<br/>[AuthContext.tsx]"]
  node_frontend_theme["Theme context<br/>appearance state<br/>[ThemeContext.tsx]"]
  node_frontend_i18n["I18n context<br/>localization state<br/>[I18nContext.tsx]"]
  node_frontend_brand_ui["Brand visuals<br/>visual components<br/>[QRCode.tsx]"]
  node_frontend_payments_ui["Payment UI<br/>domain components"]
  node_frontend_feedback_ui["Feedback UI<br/>status components<br/>[ErrorState.tsx]"]
  node_frontend_ui_kit["UI kit<br/>shared primitives<br/>[GlassCard.tsx]"]
  node_frontend_api["Client API<br/>Supabase access<br/>[api.ts]"]
  node_frontend_realtime["Realtime hooks<br/>live sync"]
  node_frontend_device["Device utils<br/>native helpers"]
end

subgraph group_shared["Shared code"]
  node_shared_client["Supabase client<br/>shared client<br/>[client.ts]"]
  node_shared_types["Domain types<br/>type models<br/>[types.ts]"]
end

subgraph group_backend["Supabase backend"]
  node_backend_schema[("Schema migrations<br/>postgres schema")]
  node_backend_seed["Seed data<br/>fixture data<br/>[seed.sql]"]
  node_backend_edge["Edge functions<br/>serverless functions<br/>[index.ts]"]
  node_backend_cors["CORS helper<br/>shared edge util<br/>[cors.ts]"]
end

subgraph group_tooling["Tooling"]
  node_tooling_scripts["Scripts<br/>repo automation<br/>[load-env.sh]"]
  node_tooling_ci["CI workflow<br/>automation<br/>[ci.yml]"]
end

node_frontend_app_shell -->|"mounts"| node_frontend_tabs
node_frontend_app_shell -->|"routes"| node_frontend_flow_screens
node_frontend_app_shell -->|"provides"| node_frontend_auth
node_frontend_app_shell -->|"provides"| node_frontend_theme
node_frontend_app_shell -->|"provides"| node_frontend_i18n
node_frontend_tabs -->|"uses"| node_frontend_brand_ui
node_frontend_tabs -->|"uses"| node_frontend_payments_ui
node_frontend_tabs -->|"uses"| node_frontend_feedback_ui
node_frontend_tabs -->|"uses"| node_frontend_ui_kit
node_frontend_flow_screens -->|"reads/writes"| node_frontend_api
node_frontend_realtime -->|"subscribes via"| node_frontend_api
node_frontend_api -->|"built on"| node_shared_client
node_frontend_api -->|"types from"| node_shared_types
node_frontend_realtime -->|"emits typed updates"| node_shared_types
node_frontend_device -->|"supports"| node_frontend_api
node_shared_client -->|"targets"| node_backend_schema
node_backend_schema -->|"seeded by"| node_backend_seed
node_backend_edge -->|"uses"| node_backend_cors
node_frontend_api -->|"invokes"| node_backend_edge
node_tooling_ci -->|"checks"| node_frontend_app_shell
node_tooling_ci -->|"checks"| node_backend_schema
node_tooling_scripts -->|"configures"| node_shared_client

click node_frontend_app_shell "https://github.com/charry07/lavaca-app/blob/main/frontend/app/_layout.tsx"
click node_frontend_tabs "https://github.com/charry07/lavaca-app/blob/main/frontend/app/(tabs)/_layout.tsx"
click node_frontend_auth "https://github.com/charry07/lavaca-app/blob/main/frontend/src/auth/AuthContext.tsx"
click node_frontend_theme "https://github.com/charry07/lavaca-app/blob/main/frontend/src/theme/ThemeContext.tsx"
click node_frontend_i18n "https://github.com/charry07/lavaca-app/blob/main/frontend/src/i18n/I18nContext.tsx"
click node_frontend_brand_ui "https://github.com/charry07/lavaca-app/blob/main/frontend/src/components/brand/QRCode.tsx"
click node_frontend_payments_ui "https://github.com/charry07/lavaca-app/blob/main/frontend/src/components/payments/PaymentAccountForm.tsx"
click node_frontend_feedback_ui "https://github.com/charry07/lavaca-app/blob/main/frontend/src/components/feedback/ErrorState.tsx"
click node_frontend_ui_kit "https://github.com/charry07/lavaca-app/blob/main/frontend/src/components/ui/GlassCard.tsx"
click node_frontend_api "https://github.com/charry07/lavaca-app/blob/main/frontend/src/services/api.ts"
click node_frontend_realtime "https://github.com/charry07/lavaca-app/blob/main/frontend/src/hooks/useSessionSocket.ts"
click node_frontend_device "https://github.com/charry07/lavaca-app/blob/main/frontend/src/utils/cameraPermission.ts"
click node_shared_client "https://github.com/charry07/lavaca-app/blob/main/packages/api/src/client.ts"
click node_shared_types "https://github.com/charry07/lavaca-app/blob/main/packages/types/src/types.ts"
click node_backend_schema "https://github.com/charry07/lavaca-app/blob/main/supabase/migrations/202603050001_initial_schema.sql"
click node_backend_seed "https://github.com/charry07/lavaca-app/blob/main/supabase/seed.sql"
click node_backend_edge "https://github.com/charry07/lavaca-app/blob/main/supabase/functions/send-notification/index.ts"
click node_backend_cors "https://github.com/charry07/lavaca-app/blob/main/supabase/functions/_shared/cors.ts"
click node_tooling_scripts "https://github.com/charry07/lavaca-app/blob/main/scripts/load-env.sh"
click node_tooling_ci "https://github.com/charry07/lavaca-app/blob/main/.github/workflows/ci.yml"

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_frontend_app_shell,node_frontend_tabs,node_frontend_flow_screens,node_frontend_auth,node_frontend_theme,node_frontend_i18n,node_frontend_brand_ui,node_frontend_payments_ui,node_frontend_feedback_ui,node_frontend_ui_kit,node_frontend_api,node_frontend_realtime,node_frontend_device toneAmber
class node_shared_client,node_shared_types toneMint
class node_backend_schema,node_backend_seed,node_backend_edge,node_backend_cors toneRose
class node_tooling_scripts,node_tooling_ci toneIndigo
```

## Components

### Mobile app

Expo React Native app with routed product flows and shared UI/state.

- [App shell](https://github.com/charry07/lavaca-app/blob/main/frontend/app/_layout.tsx): Expo Router shell · Bootstraps the mobile app, route tree, and global providers. · `frontend/app/_layout.tsx`
- [Main tabs](https://github.com/charry07/lavaca-app/blob/main/frontend/app/(tabs)/_layout.tsx): tab routes · Primary product navigation across home, feed, groups, history, and profile. · `frontend/app/(tabs)/_layout.tsx`
- **Flow screens**: route screens · Dedicated create, join, login, group, and live session screens.
- [Auth context](https://github.com/charry07/lavaca-app/blob/main/frontend/src/auth/AuthContext.tsx): session state · Holds user/session state for the app. · `frontend/src/auth/AuthContext.tsx`
- [Theme context](https://github.com/charry07/lavaca-app/blob/main/frontend/src/theme/ThemeContext.tsx): appearance state · Coordinates light/dark styling across the UI. · `frontend/src/theme/ThemeContext.tsx`
- [I18n context](https://github.com/charry07/lavaca-app/blob/main/frontend/src/i18n/I18nContext.tsx): localization state · Provides translations and language-aware text rendering. · `frontend/src/i18n/I18nContext.tsx`
- [Brand visuals](https://github.com/charry07/lavaca-app/blob/main/frontend/src/components/brand/QRCode.tsx): visual components · QR, logo, and roulette-style branded visuals. · `frontend/src/components/brand/QRCode.tsx`
- [Payment UI](https://github.com/charry07/lavaca-app/blob/main/frontend/src/components/payments/PaymentAccountForm.tsx): domain components · Payment account forms, account cards, and debt instructions. · `frontend/src/components/payments/PaymentAccountForm.tsx`
- [Feedback UI](https://github.com/charry07/lavaca-app/blob/main/frontend/src/components/feedback/ErrorState.tsx): status components · Error, empty, toast, and error-boundary surfaces. · `frontend/src/components/feedback/ErrorState.tsx`
- [UI kit](https://github.com/charry07/lavaca-app/blob/main/frontend/src/components/ui/GlassCard.tsx): shared primitives · Reusable cards, avatars, skeletons, split bars, and pills. · `frontend/src/components/ui/GlassCard.tsx`
- [Client API](https://github.com/charry07/lavaca-app/blob/main/frontend/src/services/api.ts): Supabase access · Central frontend integration point for data operations. · `frontend/src/services/api.ts`
- [Realtime hooks](https://github.com/charry07/lavaca-app/blob/main/frontend/src/hooks/useSessionSocket.ts): live sync · Subscribes to session and table changes for live UI updates. · `frontend/src/hooks/useSessionSocket.ts`
- [Device utils](https://github.com/charry07/lavaca-app/blob/main/frontend/src/utils/cameraPermission.ts): native helpers · Camera permissions, storage, and other mobile-only utilities. · `frontend/src/utils/cameraPermission.ts`

### Shared code

Reusable TypeScript client and domain types used across the workspace.

- [Supabase client](https://github.com/charry07/lavaca-app/blob/main/packages/api/src/client.ts): shared client · Reusable Supabase client layer for the workspace. · `packages/api/src/client.ts`
- [Domain types](https://github.com/charry07/lavaca-app/blob/main/packages/types/src/types.ts): type models · Canonical domain types and utilities shared across app-adjacent code. · `packages/types/src/types.ts`

### Supabase backend

Postgres schema, seed data, auth policies, realtime state, and edge functions.

- [Schema migrations](https://github.com/charry07/lavaca-app/blob/main/supabase/migrations/202603050001_initial_schema.sql): postgres schema · Versioned database schema for sessions, participants, groups, accounts, and tokens. · `supabase/migrations/202603050001_initial_schema.sql`
- [Seed data](https://github.com/charry07/lavaca-app/blob/main/supabase/seed.sql): fixture data · Initial database records used for local development and review. · `supabase/seed.sql`
- [Edge functions](https://github.com/charry07/lavaca-app/blob/main/supabase/functions/send-notification/index.ts): serverless functions · Supabase edge logic for notifications and AI-adjacent server work. · `supabase/functions/send-notification/index.ts`
- [CORS helper](https://github.com/charry07/lavaca-app/blob/main/supabase/functions/_shared/cors.ts): shared edge util · Common CORS handling used by edge functions. · `supabase/functions/_shared/cors.ts`

### Tooling

Repository automation, scripts, and assistant metadata.

- [Scripts](https://github.com/charry07/lavaca-app/blob/main/scripts/load-env.sh): repo automation · Environment loading and project check scripts. · `scripts/load-env.sh`
- [CI workflow](https://github.com/charry07/lavaca-app/blob/main/.github/workflows/ci.yml): automation · GitHub Actions pipeline for validation and checks. · `.github/workflows/ci.yml`

## Connections

- App shell → Main tabs: mounts · The root app layout hosts the tab navigator.
- App shell → Flow screens: routes · The app shell also routes to standalone flow screens.
- App shell → Auth context: provides · Global auth state is initialized at the top of the app.
- App shell → Theme context: provides · Theme state is made available across routed screens.
- App shell → I18n context: provides · Localization context is injected into the app tree.
- Main tabs → Brand visuals: uses · Tab and flow screens reuse branded visuals.
- Main tabs → Payment UI: uses · Payments-specific screens use the payment UI kit.
- Main tabs → Feedback UI: uses · Empty/error/toast states are shared across flows.
- Main tabs → UI kit: uses · Core visual primitives support the tabbed experience.
- Flow screens → Client API: reads/writes · Screens perform session, group, and participant operations through the client API.
- Realtime hooks → Client API: subscribes via · Realtime hooks attach to the same Supabase-backed client layer.
- Client API → Supabase client: built on · The frontend API wrapper uses the shared Supabase client.
- Client API → Domain types: types from · Client requests and responses are typed with shared domain models.
- Realtime hooks → Domain types: emits typed updates · Live updates use shared session and participant shapes.
- Device utils → Client API: supports · Mobile utilities feed camera, storage, and notification-related flows.
- Supabase client → Schema migrations: targets · The client layer reads and writes the Postgres schema.
- Schema migrations → Seed data: seeded by · Seed data populates the schema for local/project setup.
- Edge functions → CORS helper: uses · Edge functions share CORS handling.
- Client API → Edge functions: invokes · Client-initiated notification or AI-assisted actions go through edge functions.
- CI workflow → App shell: checks · CI validates the mobile app and workspace state.
- CI workflow → Schema migrations: checks · CI also covers backend schema and migration integrity.
- Scripts → Supabase client: configures · Scripts help load environment values for client integration.
