How charry07/lavaca-app works
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: app/_layout.tsx App shell · api.ts Client API · (tabs)/_layout.tsx Main tabs · client.ts Supabase client
Components 21
Mobile app
Expo React Native app with routed product flows and shared UI/state.
- App shell · Bootstraps the mobile app, route tree, and global providers.
frontend/app/_layout.tsx - Main tabs · Primary product navigation across home, feed, groups, history, and profile.
frontend/app/(tabs)/_layout.tsx - Flow screens · Dedicated create, join, login, group, and live session screens.
- Auth context · Holds user/session state for the app.
frontend/src/auth/AuthContext.tsx - Theme context · Coordinates light/dark styling across the UI.
frontend/src/theme/ThemeContext.tsx - I18n context · Provides translations and language-aware text rendering.
frontend/src/i18n/I18nContext.tsx - Brand visuals · QR, logo, and roulette-style branded visuals.
frontend/src/components/brand/QRCode.tsx - Payment UI · Payment account forms, account cards, and debt instructions.
frontend/src/components/payments/PaymentAccountForm.tsx - Feedback UI · Error, empty, toast, and error-boundary surfaces.
frontend/src/components/feedback/ErrorState.tsx - UI kit · Reusable cards, avatars, skeletons, split bars, and pills.
frontend/src/components/ui/GlassCard.tsx - Client API · Central frontend integration point for data operations.
frontend/src/services/api.ts - Realtime hooks · Subscribes to session and table changes for live UI updates.
frontend/src/hooks/useSessionSocket.ts - Device utils · 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 · Reusable Supabase client layer for the workspace.
packages/api/src/client.ts - Domain types · 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 · Versioned database schema for sessions, participants, groups, accounts, and tokens.
supabase/migrations/202603050001_initial_schema.sql - Seed data · Initial database records used for local development and review.
supabase/seed.sql - Edge functions · Supabase edge logic for notifications and AI-adjacent server work.
supabase/functions/send-notification/index.ts - CORS helper · Common CORS handling used by edge functions.
supabase/functions/_shared/cors.ts
Tooling
Repository automation, scripts, and assistant metadata.
- Scripts · Environment loading and project check scripts.
scripts/load-env.sh - CI workflow · GitHub Actions pipeline for validation and checks.
.github/workflows/ci.yml
Connections 22
- 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.