# savazar01/wedplanai architecture

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

- Interactive diagram: https://gitdiagram.com/savazar01/wedplanai
- Repository: https://github.com/savazar01/wedplanai

## Overview

1. **Overall shape**
   - This is a **single Next.js 16 full-stack monolith**: the same repo serves public pages, authenticated dashboard pages, server actions, and the auth API.
   - There is no separate backend service layer; business logic is split across **App Router pages**, **server actions**, and a **Drizzle/PostgreSQL** data layer.

2. **Primary runtime boundary**
   - The app runs as a **Node.js web container** connected to a **PostgreSQL database**.
   - Deployment is designed around **Docker Compose**: one container for the web app and one for Postgres, with migrations applied during startup.

3. **Public-facing entry points**
   - `src/app/page.tsx` is the landing page.
   - `src/app/login`, `src/app/signup`, and `src/app/wizard` handle unauthenticated onboarding and account creation.
   - `src/app/wedding/[id]/page.tsx` is the **public wedding showcase page**, which exposes wedding-specific content such as countdown, itinerary, and RSVP entry.

4. **Authenticated application shell**
   - `src/app/dashboard/layout.tsx` wraps the main private area with the dashboard shell.
   - Components like `SidebarShell`, `DashboardHeader`, and `WeddingSwitcher` indicate a **workspace-centric UI** where the current wedding is the main context.
   - The dashboard is divided into functional sections: **calendar, guests, kanban, timeline, settings, users, and vendors**.

5. **Authentication and session flow**
   - Authentication is handled through **Better Auth**.
   - `src/app/api/auth/[...all]/route.ts` is the auth API entry point.
   - `src/lib/auth-client.ts`, `src/lib/auth-server.ts`, and `src/lib/auth.ts` provide client/server auth helpers.
   - `src/proxy.ts` and the presence of protected dashboard routes imply **route-level access control** for authenticated areas.

6. **Core domain model: weddings as the tenant**
   - The repo is organized around a **wedding workspace** concept rather than a generic project board.
   - `src/app/wedding/[id]`, `src/components/dashboard/WeddingSwitcher.tsx`, and `src/lib/wedding-helper.ts` suggest that nearly all app data is scoped to a selected wedding.
   - The dashboard supports switching between weddings, which is the main multi-tenant boundary in the product.

7. **Guest management flow**
   - Guest management lives in `src/app/dashboard/guests` with supporting components in `src/components/guests`.
   - Server actions in `src/app/actions/guests.ts` likely handle create/update/import operations.
   - `src/components/guests/csv-upload.tsx` and `public/sample-guests.csv` show an import pipeline for bulk guest onboarding.
   - The public RSVP form in `src/components/wedding/public-rsvp-form.tsx` closes the loop from public invite page back into the guest database.

8. **Planning and execution views**
   - `src/app/dashboard/kanban` and `src/components/kanban/board.tsx` implement the planning board for task/status tracking.
   - `src/app/dashboard/calendar` plus `src/components/calendar/MonthCalendarOnly.tsx`, `TimelineOnly.tsx`, and `coordinator.tsx` provide the date-oriented planning views.
   - These views are separate UI surfaces but likely share wedding-scoped data from the same database.

9. **Vendors and budget tracking**
   - `src/app/dashboard/vendors` and `src/components/vendors` manage vendor records and budget values.
   - The README indicates contract value, paid amount, and currency handling, so this is a distinct financial subdomain rather than just a contact list.

10. **Administration and settings**
   - `src/app/dashboard/users` and its `actions.ts` file handle **role-based user management** for admins inviting collaborators.
   - `src/app/dashboard/settings` plus `ChangePasswordForm.tsx` cover account/workspace settings and password changes.
   - This is the boundary for administrative operations versus day-to-day wedding planning.

11. **Data layer and persistence**
   - `src/db/schema.ts` is the canonical schema definition; `src/db/migrations/*` are the generated SQL migrations.
   - `src/db/client.ts` is the database access point, while `src/db/migrate.ts` and `src/db/reset.ts` support lifecycle operations.
   - `src/lib/seed-sample-wedding.ts` suggests the app can bootstrap demo data for onboarding or local development.

12. **Server action architecture**
   - The `src/app/actions/*` directory centralizes mutation logic by domain: `auth`, `calendar`, `guests`, `kanban`, `vendors`, `wedding`, and `wizard`.
   - This creates a clear split: **UI components collect input**, **server actions mutate state**, and **Drizzle/Postgres persists it**.
   - For an architecture diagram, these actions are the main write-path boundary between client interactions and the database.

13. **Operational concerns**
   - `docker-compose.yml`, `Dockerfile`, `.env.example`, and the README deployment notes show that the app expects explicit environment configuration for auth and DB access.
   - `src/instrumentation.ts` indicates runtime instrumentation hooks, likely for observability or startup logging.
   - `src/app/globals.css`, Tailwind/shadcn UI components, and the public assets folder support the presentation layer but do not define core architecture.

Main entry points: [`src/app/actions`](https://github.com/savazar01/wedplanai/tree/master/src/app/actions) (Server actions), [`src/app/dashboard/layout.tsx`](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/layout.tsx) (Dashboard shell), [`src/db/client.ts`](https://github.com/savazar01/wedplanai/blob/master/src/db/client.ts) (DB client), [`src/app/page.tsx`](https://github.com/savazar01/wedplanai/blob/master/src/app/page.tsx) (Landing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public app"]
  node_landing["Landing<br/>next page<br/>[page.tsx]"]
  node_login["Login<br/>auth page<br/>[page.tsx]"]
  node_signup["Signup<br/>auth page<br/>[page.tsx]"]
  node_wizard["Wizard<br/>onboarding page<br/>[page.tsx]"]
  node_public_wedding["Wedding page<br/>public showcase<br/>[page.tsx]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_shell["Dashboard shell<br/>private layout<br/>[layout.tsx]"]
  node_dashboard_home["Dashboard home<br/>overview page<br/>[page.tsx]"]
  node_calendar_view["Calendar<br/>planning view<br/>[page.tsx]"]
  node_guests_view["Guests<br/>guest module<br/>[page.tsx]"]
  node_kanban_view["Kanban<br/>planning board<br/>[page.tsx]"]
  node_timeline_view["Timeline<br/>planning view<br/>[page.tsx]"]
  node_vendors_view["Vendors<br/>vendor module<br/>[page.tsx]"]
  node_settings_view["Settings<br/>[page.tsx]"]
  node_users_view["Users<br/>admin management<br/>[page.tsx]"]
end

subgraph group_server["Server logic"]
  node_auth_api["Auth API<br/>better auth route<br/>[route.ts]"]
  node_server_actions["Server actions<br/>mutation layer"]
  node_auth_helpers["Auth helpers<br/>auth client/server<br/>[auth.ts]"]
  node_route_guard["Route guard<br/>access control<br/>[proxy.ts]"]
  node_wedding_helper["Wedding helper<br/>tenant helper<br/>[wedding-helper.ts]"]
end

subgraph group_data["Data layer"]
  node_db_client[("DB client<br/>drizzle access<br/>[client.ts]")]
  node_schema["Schema<br/>[schema.ts]"]
  node_migrations["Migrations"]
  node_db_lifecycle["DB lifecycle<br/>ops scripts<br/>[migrate.ts]"]
  node_seed_data["Sample seed<br/>bootstrap script"]
end

node_landing -->|"start"| node_login
node_landing -->|"create account"| node_signup
node_landing -->|"onboard"| node_wizard
node_signup -->|"next"| node_wizard
node_dashboard_shell -->|"wraps"| node_dashboard_home
node_dashboard_shell -->|"contains"| node_calendar_view
node_dashboard_shell -->|"contains"| node_guests_view
node_dashboard_shell -->|"contains"| node_kanban_view
node_dashboard_shell -->|"contains"| node_timeline_view
node_dashboard_shell -->|"contains"| node_vendors_view
node_dashboard_shell -->|"contains"| node_settings_view
node_dashboard_shell -->|"contains"| node_users_view
node_public_wedding -->|"rsvp/update"| node_server_actions
node_auth_api -->|"uses"| node_auth_helpers
node_route_guard -->|"checks session"| node_auth_helpers
node_server_actions -->|"auth"| node_auth_helpers
node_server_actions -->|"scope"| node_wedding_helper
node_server_actions -->|"persist"| node_db_client
node_wedding_helper -->|"load context"| node_db_client
node_db_client -->|"maps to"| node_schema
node_schema -->|"materializes"| node_migrations
node_db_lifecycle -->|"runs"| node_migrations
node_seed_data -->|"seeds"| node_db_client
node_dashboard_home -->|"context"| node_wedding_helper
node_calendar_view -->|"mutations"| node_server_actions
node_guests_view -->|"mutations"| node_server_actions
node_kanban_view -->|"mutations"| node_server_actions
node_vendors_view -->|"mutations"| node_server_actions
node_users_view -->|"admin writes"| node_server_actions
node_settings_view -->|"updates"| node_server_actions
node_auth_api -->|"sessions"| node_db_client
node_route_guard -->|"protects"| node_dashboard_shell

click node_landing "https://github.com/savazar01/wedplanai/blob/master/src/app/page.tsx"
click node_login "https://github.com/savazar01/wedplanai/blob/master/src/app/login/page.tsx"
click node_signup "https://github.com/savazar01/wedplanai/blob/master/src/app/signup/page.tsx"
click node_wizard "https://github.com/savazar01/wedplanai/blob/master/src/app/wizard/page.tsx"
click node_public_wedding "https://github.com/savazar01/wedplanai/blob/master/src/app/wedding/[id]/page.tsx"
click node_dashboard_shell "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/layout.tsx"
click node_dashboard_home "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/page.tsx"
click node_calendar_view "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/calendar/page.tsx"
click node_guests_view "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/guests/page.tsx"
click node_kanban_view "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/kanban/page.tsx"
click node_timeline_view "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/timeline/page.tsx"
click node_vendors_view "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/vendors/page.tsx"
click node_settings_view "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/settings/page.tsx"
click node_users_view "https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/users/page.tsx"
click node_auth_api "https://github.com/savazar01/wedplanai/blob/master/src/app/api/auth/[...all]/route.ts"
click node_server_actions "https://github.com/savazar01/wedplanai/tree/master/src/app/actions"
click node_auth_helpers "https://github.com/savazar01/wedplanai/blob/master/src/lib/auth.ts"
click node_route_guard "https://github.com/savazar01/wedplanai/blob/master/src/proxy.ts"
click node_wedding_helper "https://github.com/savazar01/wedplanai/blob/master/src/lib/wedding-helper.ts"
click node_db_client "https://github.com/savazar01/wedplanai/blob/master/src/db/client.ts"
click node_schema "https://github.com/savazar01/wedplanai/blob/master/src/db/schema.ts"
click node_migrations "https://github.com/savazar01/wedplanai/blob/master/src/db/migrations/0003_round_alex_wilder.sql"
click node_db_lifecycle "https://github.com/savazar01/wedplanai/blob/master/src/db/migrate.ts"
click node_seed_data "https://github.com/savazar01/wedplanai/blob/master/src/lib/seed-sample-wedding.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_landing,node_login,node_signup,node_wizard,node_public_wedding toneBlue
class node_dashboard_shell,node_dashboard_home,node_calendar_view,node_guests_view,node_kanban_view,node_timeline_view,node_vendors_view,node_settings_view,node_users_view toneAmber
class node_auth_api,node_server_actions,node_auth_helpers,node_route_guard,node_wedding_helper toneMint
class node_db_client,node_schema,node_migrations,node_db_lifecycle,node_seed_data toneRose
```

## Components

### Public app

Unauthenticated entry points and wedding showcase pages.

- [Landing](https://github.com/savazar01/wedplanai/blob/master/src/app/page.tsx): next page · Public homepage. · `src/app/page.tsx`
- [Login](https://github.com/savazar01/wedplanai/blob/master/src/app/login/page.tsx): auth page · Sign-in entry. · `src/app/login/page.tsx`
- [Signup](https://github.com/savazar01/wedplanai/blob/master/src/app/signup/page.tsx): auth page · Account creation entry. · `src/app/signup/page.tsx`
- [Wizard](https://github.com/savazar01/wedplanai/blob/master/src/app/wizard/page.tsx): onboarding page · New wedding setup flow. · `src/app/wizard/page.tsx`
- [Wedding page](https://github.com/savazar01/wedplanai/blob/master/src/app/wedding/[id]/page.tsx): public showcase · Public wedding details, countdown, itinerary, and RSVP. · `src/app/wedding/[id]/page.tsx`

### Dashboard

Authenticated workspace shell and feature areas scoped to a wedding.

- [Dashboard shell](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/layout.tsx): private layout · Authenticated workspace layout wrapper. · `src/app/dashboard/layout.tsx`
- [Dashboard home](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/page.tsx): overview page · Private landing page for the workspace. · `src/app/dashboard/page.tsx`
- [Calendar](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/calendar/page.tsx): planning view · Date-oriented planning surface. · `src/app/dashboard/calendar/page.tsx`
- [Guests](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/guests/page.tsx): guest module · Guest management workspace. · `src/app/dashboard/guests/page.tsx`
- [Kanban](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/kanban/page.tsx): planning board · Task and status tracking board. · `src/app/dashboard/kanban/page.tsx`
- [Timeline](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/timeline/page.tsx): planning view · Schedule and milestone view. · `src/app/dashboard/timeline/page.tsx`
- [Vendors](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/vendors/page.tsx): vendor module · Vendor and budget management. · `src/app/dashboard/vendors/page.tsx`
- [Settings](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/settings/page.tsx): account settings · Workspace and password settings. · `src/app/dashboard/settings/page.tsx`
- [Users](https://github.com/savazar01/wedplanai/blob/master/src/app/dashboard/users/page.tsx): admin management · Collaborator and role administration. · `src/app/dashboard/users/page.tsx`

### Server logic

Auth, access control, and mutation paths.

- [Auth API](https://github.com/savazar01/wedplanai/blob/master/src/app/api/auth/[...all]/route.ts): better auth route · Authentication endpoint surface. · `src/app/api/auth/[...all]/route.ts`
- [Server actions](https://github.com/savazar01/wedplanai/tree/master/src/app/actions): mutation layer · Domain write-paths for auth, planning, guests, vendors, and onboarding. · `src/app/actions`
- [Auth helpers](https://github.com/savazar01/wedplanai/blob/master/src/lib/auth.ts): auth client/server · Shared Better Auth client and server utilities. · `src/lib/auth.ts`
- [Route guard](https://github.com/savazar01/wedplanai/blob/master/src/proxy.ts): access control · Middleware-like protection for authenticated routes. · `src/proxy.ts`
- [Wedding helper](https://github.com/savazar01/wedplanai/blob/master/src/lib/wedding-helper.ts): tenant helper · Wedding-scoped context and selection logic. · `src/lib/wedding-helper.ts`

### Data layer

Persistence, schema, and operational lifecycle.

- [DB client](https://github.com/savazar01/wedplanai/blob/master/src/db/client.ts): drizzle access · Database connection and query entry point. · `src/db/client.ts`
- [Schema](https://github.com/savazar01/wedplanai/blob/master/src/db/schema.ts): drizzle schema · Canonical Postgres schema definitions. · `src/db/schema.ts`
- [Migrations](https://github.com/savazar01/wedplanai/blob/master/src/db/migrations/0003_round_alex_wilder.sql): sql migrations · Generated database migrations. · `src/db/migrations/0003_round_alex_wilder.sql`
- [DB lifecycle](https://github.com/savazar01/wedplanai/blob/master/src/db/migrate.ts): ops scripts · Migration and reset helpers for local and startup workflows. · `src/db/migrate.ts`
- [Sample seed](https://github.com/savazar01/wedplanai/blob/master/src/lib/seed-sample-wedding.ts): bootstrap script · Demo wedding data bootstrap. · `src/lib/seed-sample-wedding.ts`

## Connections

- Landing → Login: start · Public users can move to sign-in.
- Landing → Signup: create account · Public users can create an account.
- Landing → Wizard: onboard · New users can enter the setup flow.
- Signup → Wizard: next · Account creation leads into workspace setup.
- Dashboard shell → Dashboard home: wraps · Private shell frames the dashboard home.
- Dashboard shell → Calendar: contains · Shell hosts planning sections.
- Dashboard shell → Guests: contains · Shell hosts planning sections.
- Dashboard shell → Kanban: contains · Shell hosts planning sections.
- Dashboard shell → Timeline: contains · Shell hosts planning sections.
- Dashboard shell → Vendors: contains · Shell hosts planning sections.
- Dashboard shell → Settings: contains · Shell hosts account controls.
- Dashboard shell → Users: contains · Shell hosts admin controls.
- Wedding page → Server actions: rsvp/update · Public wedding interactions can submit mutations.
- Auth API → Auth helpers: uses · Auth route is backed by shared auth utilities.
- Route guard → Auth helpers: checks session · Protected routes rely on auth state helpers.
- Server actions → Auth helpers: auth · Mutations validate identity and session context.
- Server actions → Wedding helper: scope · Write operations are scoped to a selected wedding.
- Server actions → DB client: persist · Server actions write through the database client.
- Wedding helper → DB client: load context · Wedding context is resolved from persisted data.
- DB client → Schema: maps to · Client queries follow the schema contract.
- Schema → Migrations: materializes · Schema is applied through generated migrations.
- DB lifecycle → Migrations: runs · Lifecycle scripts apply database changes.
- Sample seed → DB client: seeds · Demo data bootstrap writes into the database.
- Dashboard home → Wedding helper: context · Dashboard home depends on the active wedding.
- Calendar → Server actions: mutations · Calendar UI saves changes through actions.
- Guests → Server actions: mutations · Guest management uses server actions.
- Kanban → Server actions: mutations · Kanban updates go through server actions.
- Vendors → Server actions: mutations · Vendor updates go through server actions.
- Users → Server actions: admin writes · User administration uses server-side mutations.
- Settings → Server actions: updates · Settings changes are persisted through actions.
- Auth API → DB client: sessions · Auth state ultimately persists in the database.
- Route guard → Dashboard shell: protects · Authenticated dashboard routes are guarded.