# coolmanyt/what2wear architecture

> Architecture diagram of the GitHub repository coolmanyt/what2wear, 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/coolmanyt/what2wear
- Repository: https://github.com/coolmanyt/what2wear

## Overview

1. **Overall shape**
   - This is a **Next.js 16 App Router** application with a mix of public marketing/legal pages, authenticated app pages, and server-side API routes.
   - The app is deployed serverlessly on **Vercel**, with **Supabase** used for persistent user data and **NextAuth v5** for login/session handling.

2. **Primary user experience layer**
   - The main UI lives under `src/app/*` and is split into pages like `dashboard`, `account`, `settings`, `preview`, `login`, `privacy`, `terms`, and `changelog`.
   - Client-heavy interactive pieces are factored into `src/components/*` and `*Client.tsx` files, while page routes stay as server-rendered entry points.

3. **Core product flow: location → weather → outfit recommendation**
   - The central workflow is: the user chooses a location, the app fetches geocoded coordinates and weather, then requests an AI-generated outfit recommendation.
   - That flow is exposed through API routes such as `api/geocode`, `api/weather`, and `api/style`, with the dashboard UI orchestrating the sequence.

4. **Weather aggregation subsystem**
   - Weather is not sourced from a single provider; the README says it aggregates **OpenWeatherMap**, **Open-Meteo**, and **Bureau of Meteorology (Australia)**.
   - The reusable server-side weather logic is in `src/lib/weather.ts`, which likely consolidates provider responses into a single app-facing model.
   - There are also `api/demo/weather` and `api/demo/geocode` routes for limited unauthenticated examples of the same pipeline.

5. **AI recommendation subsystem**
   - AI generation is abstracted in `src/lib/ai.ts` and surfaced through routes like `api/style` and `api/followup`.
   - The app supports **OpenAI GPT-4o** and **Google Gemini**, and also supports a **bring-your-own-key** mode for Pro users.
   - A key architectural boundary is that API keys are handled server-side only and user-provided keys are used for a single request and not stored.

6. **User data and personalization**
   - Persistent user-specific data appears to be stored in **Supabase Postgres** via `src/lib/supabase.ts` and the SQL schema in `supabase/schema.sql`.
   - The main personalization areas are:
     - `closet` for wardrobe items,
     - `settings` for preferences and custom behavior,
     - `account` for profile/plan-related state.
   - `src/lib/sync-user.ts` likely keeps auth identity and database user records aligned.

7. **Authentication and session boundary**
   - Authentication is handled by **NextAuth** through `src/auth.ts` and `src/app/api/auth/[...nextauth]/route.ts`.
   - The README indicates **JWT sessions** are used, with a safe adapter fallback around the database integration.
   - OAuth providers are **GitHub** and **Google**, so the app’s protected routes depend on server-side session verification rather than client trust.

8. **Usage limits, credits, and plan enforcement**
   - The app enforces quota and monetization rules through `src/lib/credits.ts` and `src/lib/daily-usage.ts`, plus API routes like `api/credits` and `api/daily-limits`.
   - This is a major architectural boundary: request handling for AI, follow-ups, closet usage, and source selection depends on the user’s free/pro plan entitlements.
   - The `account` and `settings` pages are the main surfaces where these plan differences are exposed.

9. **Security-sensitive request handling**
   - `src/app/actions.ts` and route handlers perform server-side operations so secrets and validation never leave the backend.
   - The README calls out **SSRF protection** for custom weather source URLs, enforcing HTTPS and rejecting private/internal hosts.
   - `src/proxy.ts` likely provides a request interception layer for auth or routing protection at the app edge.

10. **Content and legal pages**
   - Static/public-facing content is split out cleanly into dedicated routes: `/privacy`, `/terms`, `/changelog`, and the landing page.
   - `changelog.json` plus `api/changelog` suggests release notes are served from a structured source rather than hard-coded in the UI.

11. **UI composition**
   - Reusable UI primitives and product widgets live in `src/components`, including:
     - `LocationPicker` / `DemoLocationPicker` for geocoding entry,
     - `WeatherEffectCard` for weather visualization,
     - `ThemeController` for dark mode,
     - `UpgradePlanModal` and `AccountUpgradeButton` for monetization flows.
   - `Dashboard.tsx` is likely the main composition root for the authenticated experience.

12. **Data/control flow boundaries to capture in a diagram**
   - Browser client components initiate requests to Next.js API routes.
   - API routes call external services: weather providers, AI providers, geocoding services, and Supabase.
   - Server-side libraries centralize business logic: weather aggregation, AI prompting, credits/limits, and auth/user syncing.
   - The result is a clearly layered app: **presentation → route handlers/server logic → external APIs + database**.

Main entry points: [`src/components/Dashboard.tsx`](https://github.com/coolmanyt/what2wear/blob/main/src/components/Dashboard.tsx) (Dashboard UI), [`src/lib/ai.ts`](https://github.com/coolmanyt/what2wear/blob/main/src/lib/ai.ts) (AI Core), [`src/auth.ts`](https://github.com/coolmanyt/what2wear/blob/main/src/auth.ts) (Auth Config), [`src/app/api/geocode/route.ts`](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/geocode/route.ts) (Geocode API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_node_landing["Landing<br/>app route<br/>[page.tsx]"]
  node_node_dashboard_page["Dashboard<br/>app route<br/>[page.tsx]"]
  node_node_dashboard_ui["Dashboard UI<br/>client shell<br/>[Dashboard.tsx]"]
  node_node_location_picker["Location Picker<br/>client widget<br/>[LocationPicker.tsx]"]
  node_node_weather_card["Weather Card<br/>client widget"]
  node_node_upgrade_modal["Upgrade Modal<br/>monetization ui"]
  node_node_login["Login<br/>app route<br/>[page.tsx]"]
  node_node_account["Account<br/>app route<br/>[page.tsx]"]
  node_node_settings["Settings<br/>app route<br/>[page.tsx]"]
  node_node_preview["Preview<br/>app route<br/>[page.tsx]"]
  node_node_privacy["Privacy<br/>legal page<br/>[page.tsx]"]
  node_node_terms["Terms<br/>legal page<br/>[page.tsx]"]
  node_node_changelog_page["Changelog<br/>content page<br/>[page.tsx]"]
end

subgraph group_api["Route Handlers"]
  node_node_auth_route["Auth API<br/>nextauth route<br/>[route.ts]"]
  node_node_geocode_api["Geocode API<br/>route handler<br/>[route.ts]"]
  node_node_weather_api["Weather API<br/>route handler<br/>[route.ts]"]
  node_node_style_api["Style API<br/>route handler<br/>[route.ts]"]
  node_node_followup_api["Followup API<br/>route handler<br/>[route.ts]"]
  node_node_credits_api["Credits API<br/>route handler<br/>[route.ts]"]
  node_node_limits_api["Limits API<br/>route handler<br/>[route.ts]"]
  node_node_closet_api["Closet API<br/>route handler<br/>[route.ts]"]
  node_node_settings_api["Settings API<br/>route handler<br/>[route.ts]"]
  node_node_demo_geocode["Demo Geocode<br/>demo route<br/>[route.ts]"]
  node_node_demo_weather["Demo Weather<br/>demo route<br/>[route.ts]"]
  node_node_actions["Server Actions<br/>[actions.ts]"]
  node_node_proxy["Edge Proxy<br/>request proxy<br/>[proxy.ts]"]
end

subgraph group_core["Core Logic"]
  node_node_weather_lib["Weather Core<br/>weather service<br/>[weather.ts]"]
  node_node_ai_lib["AI Core<br/>ai service<br/>[ai.ts]"]
  node_node_credits_lib["Credits Logic<br/>policy engine<br/>[credits.ts]"]
  node_node_daily_lib["Usage Logic<br/>usage tracker<br/>[daily-usage.ts]"]
  node_node_supabase_lib[("Supabase Client<br/>db client<br/>[supabase.ts]")]
  node_node_sync_user["User Sync<br/>sync service<br/>[sync-user.ts]"]
  node_node_auth_config["Auth Config<br/>[auth.ts]"]
end

subgraph group_data["Data & Services"]
  node_node_weather_providers(("Weather Providers<br/>external apis"))
end

node_node_landing -->|"entry"| node_node_login
node_node_dashboard_page -->|"renders"| node_node_dashboard_ui
node_node_dashboard_ui -->|"selects"| node_node_location_picker
node_node_dashboard_ui -->|"shows"| node_node_weather_card
node_node_dashboard_ui -->|"upsell"| node_node_upgrade_modal
node_node_location_picker -->|"requests"| node_node_geocode_api
node_node_geocode_api -->|"uses"| node_node_weather_lib
node_node_demo_geocode -.->|"example"| node_node_geocode_api
node_node_weather_card -->|"requests"| node_node_weather_api
node_node_weather_api -->|"uses"| node_node_weather_lib
node_node_weather_lib -->|"fetches"| node_node_weather_providers
node_node_demo_weather -.->|"example"| node_node_weather_api
node_node_dashboard_ui -->|"asks"| node_node_style_api
node_node_style_api -->|"uses"| node_node_ai_lib
node_node_followup_api -->|"uses"| node_node_ai_lib
node_node_ai_lib -->|"checks"| node_node_credits_lib
node_node_ai_lib -->|"tracks"| node_node_daily_lib
node_node_credits_api -->|"exposes"| node_node_credits_lib
node_node_limits_api -->|"exposes"| node_node_daily_lib
node_node_closet_api -->|"persists"| node_node_supabase_lib
node_node_settings_api -->|"persists"| node_node_supabase_lib
node_node_actions -->|"mutates"| node_node_sync_user
node_node_auth_route -->|"configures"| node_node_auth_config
node_node_auth_config -->|"syncs"| node_node_sync_user
node_node_auth_config -->|"adapts"| node_node_supabase_lib
node_node_proxy -->|"guards"| node_node_auth_route
node_node_account -->|"views"| node_node_credits_api
node_node_account -->|"manages"| node_node_closet_api
node_node_settings -->|"saves"| node_node_settings_api
node_node_changelog_page -.-> node_node_changelog_page
node_node_privacy -.-> node_node_terms

click node_node_landing "https://github.com/coolmanyt/what2wear/blob/main/src/app/page.tsx"
click node_node_dashboard_page "https://github.com/coolmanyt/what2wear/blob/main/src/app/dashboard/page.tsx"
click node_node_dashboard_ui "https://github.com/coolmanyt/what2wear/blob/main/src/components/Dashboard.tsx"
click node_node_location_picker "https://github.com/coolmanyt/what2wear/blob/main/src/components/LocationPicker.tsx"
click node_node_weather_card "https://github.com/coolmanyt/what2wear/blob/main/src/components/WeatherEffectCard.tsx"
click node_node_upgrade_modal "https://github.com/coolmanyt/what2wear/blob/main/src/components/UpgradePlanModal.tsx"
click node_node_login "https://github.com/coolmanyt/what2wear/blob/main/src/app/login/page.tsx"
click node_node_account "https://github.com/coolmanyt/what2wear/blob/main/src/app/account/page.tsx"
click node_node_settings "https://github.com/coolmanyt/what2wear/blob/main/src/app/settings/page.tsx"
click node_node_preview "https://github.com/coolmanyt/what2wear/blob/main/src/app/preview/page.tsx"
click node_node_privacy "https://github.com/coolmanyt/what2wear/blob/main/src/app/privacy/page.tsx"
click node_node_terms "https://github.com/coolmanyt/what2wear/blob/main/src/app/terms/page.tsx"
click node_node_changelog_page "https://github.com/coolmanyt/what2wear/blob/main/src/app/changelog/page.tsx"
click node_node_auth_route "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/auth/[...nextauth]/route.ts"
click node_node_geocode_api "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/geocode/route.ts"
click node_node_weather_api "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/weather/route.ts"
click node_node_style_api "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/style/route.ts"
click node_node_followup_api "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/followup/route.ts"
click node_node_credits_api "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/credits/route.ts"
click node_node_limits_api "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/daily-limits/route.ts"
click node_node_closet_api "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/closet/route.ts"
click node_node_settings_api "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/settings/route.ts"
click node_node_demo_geocode "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/demo/geocode/route.ts"
click node_node_demo_weather "https://github.com/coolmanyt/what2wear/blob/main/src/app/api/demo/weather/route.ts"
click node_node_actions "https://github.com/coolmanyt/what2wear/blob/main/src/app/actions.ts"
click node_node_proxy "https://github.com/coolmanyt/what2wear/blob/main/src/proxy.ts"
click node_node_weather_lib "https://github.com/coolmanyt/what2wear/blob/main/src/lib/weather.ts"
click node_node_ai_lib "https://github.com/coolmanyt/what2wear/blob/main/src/lib/ai.ts"
click node_node_credits_lib "https://github.com/coolmanyt/what2wear/blob/main/src/lib/credits.ts"
click node_node_daily_lib "https://github.com/coolmanyt/what2wear/blob/main/src/lib/daily-usage.ts"
click node_node_supabase_lib "https://github.com/coolmanyt/what2wear/blob/main/src/lib/supabase.ts"
click node_node_sync_user "https://github.com/coolmanyt/what2wear/blob/main/src/lib/sync-user.ts"
click node_node_auth_config "https://github.com/coolmanyt/what2wear/blob/main/src/auth.ts"

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_node_landing,node_node_dashboard_page,node_node_dashboard_ui,node_node_location_picker,node_node_weather_card,node_node_upgrade_modal,node_node_login,node_node_account,node_node_settings,node_node_preview,node_node_privacy,node_node_terms,node_node_changelog_page toneBlue
class node_node_auth_route,node_node_geocode_api,node_node_weather_api,node_node_style_api,node_node_followup_api,node_node_credits_api,node_node_limits_api,node_node_closet_api,node_node_settings_api,node_node_demo_geocode,node_node_demo_weather,node_node_actions,node_node_proxy toneAmber
class node_node_weather_lib,node_node_ai_lib,node_node_credits_lib,node_node_daily_lib,node_node_supabase_lib,node_node_sync_user,node_node_auth_config toneMint
class node_node_weather_providers toneRose
```

## Components

### Presentation

App routes and client-facing UI composition.

- [Landing](https://github.com/coolmanyt/what2wear/blob/main/src/app/page.tsx): app route · Public home page entry point. · `src/app/page.tsx`
- [Dashboard](https://github.com/coolmanyt/what2wear/blob/main/src/app/dashboard/page.tsx): app route · Authenticated product entry point. · `src/app/dashboard/page.tsx`
- [Dashboard UI](https://github.com/coolmanyt/what2wear/blob/main/src/components/Dashboard.tsx): client shell · Main authenticated experience composition. · `src/components/Dashboard.tsx`
- [Location Picker](https://github.com/coolmanyt/what2wear/blob/main/src/components/LocationPicker.tsx): client widget · Location selection and geocoding trigger. · `src/components/LocationPicker.tsx`
- [Weather Card](https://github.com/coolmanyt/what2wear/blob/main/src/components/WeatherEffectCard.tsx): client widget · Weather display and visual feedback. · `src/components/WeatherEffectCard.tsx`
- [Upgrade Modal](https://github.com/coolmanyt/what2wear/blob/main/src/components/UpgradePlanModal.tsx): monetization ui · Plan upgrade and paywall surface. · `src/components/UpgradePlanModal.tsx`
- [Login](https://github.com/coolmanyt/what2wear/blob/main/src/app/login/page.tsx): app route · Authentication entry page. · `src/app/login/page.tsx`
- [Account](https://github.com/coolmanyt/what2wear/blob/main/src/app/account/page.tsx): app route · Profile and plan management page. · `src/app/account/page.tsx`
- [Settings](https://github.com/coolmanyt/what2wear/blob/main/src/app/settings/page.tsx): app route · User preferences and customization page. · `src/app/settings/page.tsx`
- [Preview](https://github.com/coolmanyt/what2wear/blob/main/src/app/preview/page.tsx): app route · Preview-oriented app page. · `src/app/preview/page.tsx`
- [Privacy](https://github.com/coolmanyt/what2wear/blob/main/src/app/privacy/page.tsx): legal page · Public privacy policy page. · `src/app/privacy/page.tsx`
- [Terms](https://github.com/coolmanyt/what2wear/blob/main/src/app/terms/page.tsx): legal page · Public terms page. · `src/app/terms/page.tsx`
- [Changelog](https://github.com/coolmanyt/what2wear/blob/main/src/app/changelog/page.tsx): content page · Release notes page. · `src/app/changelog/page.tsx`

### Route Handlers

Next.js API routes and server actions that handle requests.

- [Auth API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/auth/[...nextauth]/route.ts): nextauth route · NextAuth handler for login and sessions. · `src/app/api/auth/[...nextauth]/route.ts`
- [Geocode API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/geocode/route.ts): route handler · Converts locations into coordinates. · `src/app/api/geocode/route.ts`
- [Weather API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/weather/route.ts): route handler · Serves normalized weather data. · `src/app/api/weather/route.ts`
- [Style API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/style/route.ts): route handler · Generates outfit recommendations. · `src/app/api/style/route.ts`
- [Followup API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/followup/route.ts): route handler · Handles iterative AI follow-up requests. · `src/app/api/followup/route.ts`
- [Credits API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/credits/route.ts): route handler · Exposes quota and credit state. · `src/app/api/credits/route.ts`
- [Limits API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/daily-limits/route.ts): route handler · Exposes daily usage limits. · `src/app/api/daily-limits/route.ts`
- [Closet API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/closet/route.ts): route handler · Manages wardrobe data. · `src/app/api/closet/route.ts`
- [Settings API](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/settings/route.ts): route handler · Persists user settings. · `src/app/api/settings/route.ts`
- [Demo Geocode](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/demo/geocode/route.ts): demo route · Unauthenticated geocode example. · `src/app/api/demo/geocode/route.ts`
- [Demo Weather](https://github.com/coolmanyt/what2wear/blob/main/src/app/api/demo/weather/route.ts): demo route · Unauthenticated weather example. · `src/app/api/demo/weather/route.ts`
- [Server Actions](https://github.com/coolmanyt/what2wear/blob/main/src/app/actions.ts): server actions · Backend mutations invoked from the app. · `src/app/actions.ts`
- [Edge Proxy](https://github.com/coolmanyt/what2wear/blob/main/src/proxy.ts): request proxy · Edge-level request protection and routing. · `src/proxy.ts`

### Core Logic

Shared business rules for weather, AI, auth, and limits.

- [Weather Core](https://github.com/coolmanyt/what2wear/blob/main/src/lib/weather.ts): weather service · Aggregates and normalizes provider data. · `src/lib/weather.ts`
- [AI Core](https://github.com/coolmanyt/what2wear/blob/main/src/lib/ai.ts): ai service · Abstracts model selection and prompt execution. · `src/lib/ai.ts`
- [Credits Logic](https://github.com/coolmanyt/what2wear/blob/main/src/lib/credits.ts): policy engine · Enforces plan and usage entitlements. · `src/lib/credits.ts`
- [Usage Logic](https://github.com/coolmanyt/what2wear/blob/main/src/lib/daily-usage.ts): usage tracker · Tracks daily request usage. · `src/lib/daily-usage.ts`
- [Supabase Client](https://github.com/coolmanyt/what2wear/blob/main/src/lib/supabase.ts): db client · Database access for persisted user data. · `src/lib/supabase.ts`
- [User Sync](https://github.com/coolmanyt/what2wear/blob/main/src/lib/sync-user.ts): sync service · Keeps auth identity and DB records aligned. · `src/lib/sync-user.ts`
- [Auth Config](https://github.com/coolmanyt/what2wear/blob/main/src/auth.ts): nextauth config · NextAuth provider and session configuration. · `src/auth.ts`

### Data & Services

Persistent storage and external providers used by the app.

- **Weather Providers**: external apis · OpenWeatherMap, Open-Meteo, and BOM.

## Connections

- Landing → Login: entry · Public users move from landing to login.
- Dashboard → Dashboard UI: renders · Dashboard route composes the main client shell.
- Dashboard UI → Location Picker: selects · Users choose a location to start the weather flow.
- Dashboard UI → Weather Card: shows · Dashboard presents weather and outfit output.
- Dashboard UI → Upgrade Modal: upsell · Plan limits surface upgrade prompts.
- Location Picker → Geocode API: requests · Location input triggers geocoding.
- Geocode API → Weather Core: uses · Geocode flow feeds weather-oriented location handling.
- Demo Geocode → Geocode API: example · Demo route mirrors the main geocode flow.
- Weather Card → Weather API: requests · Weather UI pulls normalized forecast data.
- Weather API → Weather Core: uses · Weather route delegates aggregation and normalization.
- Weather Core → Weather Providers: fetches · Weather core queries multiple upstream providers.
- Demo Weather → Weather API: example · Demo route mirrors the main weather flow.
- Dashboard UI → Style API: asks · Dashboard requests outfit recommendations.
- Style API → AI Core: uses · Style route delegates to AI orchestration.
- Followup API → AI Core: uses · Follow-up chat style requests reuse the AI core.
- AI Core → Credits Logic: checks · AI usage depends on entitlement rules.
- AI Core → Usage Logic: tracks · AI requests contribute to daily usage accounting.
- Credits API → Credits Logic: exposes · Credits route surfaces entitlement state.
- Limits API → Usage Logic: exposes · Daily limits route surfaces usage totals.
- Closet API → Supabase Client: persists · Closet data is stored in Supabase.
- Settings API → Supabase Client: persists · Settings are stored in Supabase.
- Server Actions → User Sync: mutates · Server actions coordinate authenticated backend changes.
- Auth API → Auth Config: configures · NextAuth route uses the shared auth config.
- Auth Config → User Sync: syncs · Auth lifecycle keeps DB user records aligned.
- Auth Config → Supabase Client: adapts · Auth integrates with the database layer.
- Edge Proxy → Auth API: guards · Edge proxy protects authenticated app areas.
- Account → Credits API: views · Account page exposes plan and credit state.
- Account → Closet API: manages · Account flows can interact with wardrobe data.
- Settings → Settings API: saves · Settings page persists user preferences.
- Changelog → Changelog: Static changelog content is rendered from structured source.
- Privacy → Terms: Legal pages sit alongside each other as public content.
