# v-par23/waterloo-budget architecture

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

- Interactive diagram: https://gitdiagram.com/v-par23/waterloo-budget
- Repository: https://github.com/v-par23/waterloo-budget
- Video tour (about a minute): https://gitdiagram.com/v-par23/waterloo-budget/video

## Overview

#### Overview

This is a Next.js App Router application. The route and module names indicate a workspace/travel planning product centered on spots, maps, schedules, transport, budgets, saved items, teams, reviews, and AI-assisted recommendations. The README documents only the Next.js scaffold, so detailed business behavior is inferred from repository organization rather than confirmed source logic.

#### Public entry points

- Browser pages include `/`, `/discover`, `/map`, `/planner`, `/schedule`, `/transport`, `/budget`, `/saved`, `/ask`, `/suggest`, `/workspots`, and team routes under `/teams`.

- Authentication pages are organized under `src/app/(auth)`, including login, signup, password recovery, and reset flows. `/auth/callback` provides an authentication callback endpoint.

- HTTP API surfaces are organized under `src/app/api`: AI insights and recommendations, reviews, and schedule parsing.

#### Core components

- **App Router screens — `src/app`:** Owns page-level entry points, authentication pages, the shared layout, and route-specific UI.

- **API route handlers — `src/app/api`:** Defines server-facing HTTP boundaries for AI, reviews, and schedule parsing. These are separate from the browser page routes.

- **Feature UI — `src/components/features`:** Contains map views, route planning, spot lists, AI insights, comparisons, and team expense interfaces.

- **Application shell and controls — `src/components/layout`:** Provides navigation-oriented layout elements such as the sidebar and mobile header.

- **Client state providers — `src/components/AuthProvider.tsx`:** Establishes shared client-side state boundaries; parallel providers cover budgets, saved spots, and schedules.

- **Persistence adapters — `src/lib/supabase/server.ts`:** Provides server-side Supabase integration, with companion client and type modules. `supabase-schema.sql` and the budget/team migration files define the repository’s documented database artifacts.

- **AI integration area — `src/lib/ai`:** Groups AI configuration and embedding-related implementation used by the AI route surface.

- **Domain utilities and hooks — `src/lib/hooks`:** Groups reusable concerns for route plans, speech, reviews, and user location; related domain modules cover budgets, schedules, geography, Yelp, and static spot data.

#### Relationships

Browser requests enter page routes in `src/app`, which can share layout, feature, UI, provider, hook, and domain modules. API requests enter the handlers under `src/app/api`; the AI, schedule, review, geography, and persistence areas provide supporting ownership boundaries rather than a proven fixed execution sequence. Supabase adapters correspond to the SQL schema and migrations, forming the persistence boundary. The browser/user and any configured external services are actors outside this repository; Yelp and AI-related modules indicate optional integration areas, not guaranteed runtime call order.

Main entry points: [`src/app`](https://github.com/v-par23/waterloo-budget/tree/main/src/app) (App Router screens), [`src/app/api`](https://github.com/v-par23/waterloo-budget/tree/main/src/app/api) (API route handlers), [`src/lib/supabase/server.ts`](https://github.com/v-par23/waterloo-budget/blob/main/src/lib/supabase/server.ts) (Persistence adapters), [`src/lib/hooks`](https://github.com/v-par23/waterloo-budget/tree/main/src/lib/hooks) (Domain utilities and hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application surfaces"]
  node_app["App Router screens<br/>Next.js routes"]
  node_api["API route handlers<br/>HTTP API"]
  node_features["Feature UI<br/>React feature components"]
  node_layout["Application shell<br/>layout components"]
end

subgraph group_support["Supporting modules"]
  node_providers["Client state providers<br/>React providers<br/>[AuthProvider.tsx]"]
  node_domain["Domain utilities and hooks<br/>application modules"]
  node_ai["AI integration<br/>AI modules"]
  node_persistence[("Persistence adapters<br/>Supabase adapter<br/>[server.ts]")]
  node_schema["Database schema<br/>SQL artifact"]
end

node_browser(("Browser / user<br/>external actor"))
node_supabase[("Supabase<br/>external database service")]

node_browser -->|"requests pages"| node_app
node_browser -->|"requests API"| node_api
node_app -->|"uses"| node_layout
node_app -->|"uses"| node_features
node_app -->|"shares state through"| node_providers
node_app -->|"uses"| node_domain
node_api -->|"uses"| node_ai
node_api -->|"uses"| node_domain
node_persistence -->|"corresponds to"| node_schema
node_persistence -->|"integrates with"| node_supabase

click node_app "https://github.com/v-par23/waterloo-budget/tree/main/src/app"
click node_api "https://github.com/v-par23/waterloo-budget/tree/main/src/app/api"
click node_features "https://github.com/v-par23/waterloo-budget/tree/main/src/components/features"
click node_layout "https://github.com/v-par23/waterloo-budget/tree/main/src/components/layout"
click node_providers "https://github.com/v-par23/waterloo-budget/blob/main/src/components/AuthProvider.tsx"
click node_domain "https://github.com/v-par23/waterloo-budget/tree/main/src/lib/hooks"
click node_ai "https://github.com/v-par23/waterloo-budget/tree/main/src/lib/ai"
click node_persistence "https://github.com/v-par23/waterloo-budget/blob/main/src/lib/supabase/server.ts"
click node_schema "https://github.com/v-par23/waterloo-budget/blob/main/supabase-schema.sql"

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_app,node_api,node_features,node_layout toneBlue
class node_providers,node_domain,node_ai,node_persistence,node_schema toneAmber
class node_browser,node_supabase toneNeutral
```

## Components

### Application surfaces

- [App Router screens](https://github.com/v-par23/waterloo-budget/tree/main/src/app): Next.js routes · Owns browser pages, authentication pages, shared layout, and route UI. · `src/app`
- [API route handlers](https://github.com/v-par23/waterloo-budget/tree/main/src/app/api): HTTP API · Defines server-facing boundaries for AI, reviews, and schedule parsing. · `src/app/api`
- [Feature UI](https://github.com/v-par23/waterloo-budget/tree/main/src/components/features): React feature components · `src/components/features`
- [Application shell](https://github.com/v-par23/waterloo-budget/tree/main/src/components/layout): layout components · `src/components/layout`

### Supporting modules

- [Client state providers](https://github.com/v-par23/waterloo-budget/blob/main/src/components/AuthProvider.tsx): React providers · Provides shared client-side state for authentication and domain features. · `src/components/AuthProvider.tsx`
- [Domain utilities and hooks](https://github.com/v-par23/waterloo-budget/tree/main/src/lib/hooks): application modules · `src/lib/hooks`
- [AI integration](https://github.com/v-par23/waterloo-budget/tree/main/src/lib/ai): AI modules · Provides AI configuration and embedding-related implementation. · `src/lib/ai`
- [Persistence adapters](https://github.com/v-par23/waterloo-budget/blob/main/src/lib/supabase/server.ts): Supabase adapter · Provides server-side persistence integration and database types. · `src/lib/supabase/server.ts`
- [Database schema](https://github.com/v-par23/waterloo-budget/blob/main/supabase-schema.sql): SQL artifact · `supabase-schema.sql`

### Other components

- **Browser / user**: external actor
- **Supabase**: external database service

## Connections

- Browser / user → App Router screens: requests pages
- Browser / user → API route handlers: requests API
- App Router screens → Application shell: uses
- App Router screens → Feature UI: uses
- App Router screens → Client state providers: shares state through
- App Router screens → Domain utilities and hooks: uses
- API route handlers → AI integration: uses
- API route handlers → Domain utilities and hooks: uses
- Persistence adapters → Database schema: corresponds to
- Persistence adapters → Supabase: integrates with
