# soupgorn/wangmai architecture

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

- Interactive diagram: https://gitdiagram.com/soupgorn/wangmai
- Repository: https://github.com/soupgorn/wangmai

## Overview

Wangmai is a personal scheduling and availability-sharing application. Users sign in with Google, manage recurring or dated schedule blocks and timezone preferences, then—if they opt in—can appear in authenticated availability searches; sharing is private by default and the public preview is fictional and independent. The frontend talks to a Hono API backed by PostgreSQL, with Better Auth handling sessions and shared schedule logic. The graph emphasizes documented capabilities and sampled wiring; several frontend page-to-feature and browser-to-API connections are not shown in the excerpts, so they are omitted or marked unverified.

Main entry points: [`backend/src/modules/schedule/routes.ts`](https://github.com/soupgorn/wangmai/blob/main/backend/src/modules/schedule/routes.ts) (Schedule endpoints), [`backend/src/auth/auth.ts`](https://github.com/soupgorn/wangmai/blob/main/backend/src/auth/auth.ts) (Google authentication), [`backend/src/db/client.ts`](https://github.com/soupgorn/wangmai/blob/main/backend/src/db/client.ts) (Database client), [`backend/src/app.ts`](https://github.com/soupgorn/wangmai/blob/main/backend/src/app.ts) (Hono API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_login["Google login<br/>[page.tsx]"]
  node_workspace["Schedule workspace"]
  node_schedule_ui["Schedule editing<br/>[schedule-page.tsx]"]
  node_settings_ui["Sharing settings<br/>[settings-page.tsx]"]
  node_finder_ui["Availability finder"]
  node_preview["Fictional preview"]
  node_repo["Schedule repository"]
  node_api_client["API client<br/>[api-client.ts]"]
  node_preview_pages["Preview pages"]
end

subgraph group_identity["Identity and API"]
  node_api["Hono API<br/>[app.ts]"]
  node_auth["Google authentication<br/>[auth.ts]"]
  node_backend_start["Backend startup<br/>[index.ts]"]
  node_env["Runtime configuration<br/>[env.ts]"]
end

subgraph group_scheduling["Schedule and discovery"]
  node_schedule_routes["Schedule endpoints<br/>[routes.ts]"]
  node_availability_routes["Availability search<br/>[routes.ts]"]
end

subgraph group_persistence["Persistence"]
  node_db_client["Database client<br/>[client.ts]"]
  node_schema["Relational schema<br/>[schema.ts]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_shared["Shared domain"]
  node_schedule_logic["Schedule rules<br/>[schedule.ts]"]
  node_availability_logic["Availability rules<br/>[availability.ts]"]
end

node_user(("Workspace user"))

node_user -->|"signs in"| node_login
node_user -.->|"manages schedule"| node_workspace
node_workspace -.->|"loads and saves"| node_repo
node_repo -.->|"requests schedule API"| node_api
node_api -->|"routes auth requests"| node_auth
node_api -->|"mounts schedule routes"| node_schedule_routes
node_api -->|"mounts finder routes"| node_availability_routes
node_schedule_routes -->|"validates sessions"| node_auth
node_availability_routes -->|"validates sessions"| node_auth
node_schedule_routes -->|"reads and writes"| node_db_client
node_availability_routes -->|"queries schedules"| node_db_client
node_schedule_routes -->|"validates blocks"| node_schedule_logic
node_availability_routes -->|"classifies availability"| node_availability_logic
node_availability_logic -->|"uses schedule rules"| node_schedule_logic
node_db_client -->|"configures ORM"| node_schema
node_db_client -->|"connects"| node_postgres
node_auth -->|"uses database"| node_db_client
node_auth -->|"adapts tables"| node_schema
node_backend_start -->|"starts server"| node_api
node_backend_start -->|"creates auth"| node_auth
node_backend_start -->|"creates database"| node_db_client
node_backend_start -->|"loads configuration"| node_env
node_preview_pages -.->|"presents preview"| node_preview
node_finder_ui -.->|"searches availability"| node_availability_routes
node_schedule_ui -.->|"edits schedule"| node_schedule_routes
node_settings_ui -.->|"updates preferences"| node_schedule_routes

click node_login "https://github.com/soupgorn/wangmai/blob/main/frontend/src/app/login/page.tsx"
click node_workspace "https://github.com/soupgorn/wangmai/tree/main/frontend/src/features/core"
click node_schedule_ui "https://github.com/soupgorn/wangmai/blob/main/frontend/src/features/core/schedule-page.tsx"
click node_settings_ui "https://github.com/soupgorn/wangmai/blob/main/frontend/src/features/core/settings-page.tsx"
click node_finder_ui "https://github.com/soupgorn/wangmai/blob/main/frontend/src/features/core/availability-page.tsx"
click node_preview "https://github.com/soupgorn/wangmai/blob/main/frontend/src/components/marketing/availability-preview.tsx"
click node_repo "https://github.com/soupgorn/wangmai/blob/main/frontend/src/features/core/database-repository.ts"
click node_api_client "https://github.com/soupgorn/wangmai/blob/main/frontend/src/lib/api-client.ts"
click node_api "https://github.com/soupgorn/wangmai/blob/main/backend/src/app.ts"
click node_auth "https://github.com/soupgorn/wangmai/blob/main/backend/src/auth/auth.ts"
click node_schedule_routes "https://github.com/soupgorn/wangmai/blob/main/backend/src/modules/schedule/routes.ts"
click node_availability_routes "https://github.com/soupgorn/wangmai/blob/main/backend/src/modules/availability/routes.ts"
click node_schedule_logic "https://github.com/soupgorn/wangmai/blob/main/packages/shared/src/schedule.ts"
click node_availability_logic "https://github.com/soupgorn/wangmai/blob/main/packages/shared/src/availability.ts"
click node_db_client "https://github.com/soupgorn/wangmai/blob/main/backend/src/db/client.ts"
click node_schema "https://github.com/soupgorn/wangmai/blob/main/backend/src/db/schema.ts"
click node_backend_start "https://github.com/soupgorn/wangmai/blob/main/backend/src/index.ts"
click node_env "https://github.com/soupgorn/wangmai/blob/main/backend/src/config/env.ts"
click node_preview_pages "https://github.com/soupgorn/wangmai/tree/main/frontend/src/app/preview"

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_login,node_workspace,node_schedule_ui,node_settings_ui,node_finder_ui,node_preview,node_repo,node_api_client,node_preview_pages,node_user toneBlue
class node_api,node_auth,node_backend_start,node_env toneAmber
class node_schedule_routes,node_availability_routes toneMint
class node_db_client,node_schema,node_postgres toneRose
class node_schedule_logic,node_availability_logic toneIndigo
```

## Components

### Web experience

- [Google login](https://github.com/soupgorn/wangmai/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Schedule workspace](https://github.com/soupgorn/wangmai/tree/main/frontend/src/features/core): `frontend/src/features/core`
- [Schedule editing](https://github.com/soupgorn/wangmai/blob/main/frontend/src/features/core/schedule-page.tsx): `frontend/src/features/core/schedule-page.tsx`
- [Sharing settings](https://github.com/soupgorn/wangmai/blob/main/frontend/src/features/core/settings-page.tsx): `frontend/src/features/core/settings-page.tsx`
- [Availability finder](https://github.com/soupgorn/wangmai/blob/main/frontend/src/features/core/availability-page.tsx): `frontend/src/features/core/availability-page.tsx`
- [Fictional preview](https://github.com/soupgorn/wangmai/blob/main/frontend/src/components/marketing/availability-preview.tsx): `frontend/src/components/marketing/availability-preview.tsx`
- [Schedule repository](https://github.com/soupgorn/wangmai/blob/main/frontend/src/features/core/database-repository.ts): `frontend/src/features/core/database-repository.ts`
- [API client](https://github.com/soupgorn/wangmai/blob/main/frontend/src/lib/api-client.ts): `frontend/src/lib/api-client.ts`
- [Preview pages](https://github.com/soupgorn/wangmai/tree/main/frontend/src/app/preview): `frontend/src/app/preview`

### Identity and API

- [Hono API](https://github.com/soupgorn/wangmai/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Google authentication](https://github.com/soupgorn/wangmai/blob/main/backend/src/auth/auth.ts): `backend/src/auth/auth.ts`
- [Backend startup](https://github.com/soupgorn/wangmai/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Runtime configuration](https://github.com/soupgorn/wangmai/blob/main/backend/src/config/env.ts): `backend/src/config/env.ts`

### Schedule and discovery

- [Schedule endpoints](https://github.com/soupgorn/wangmai/blob/main/backend/src/modules/schedule/routes.ts): `backend/src/modules/schedule/routes.ts`
- [Availability search](https://github.com/soupgorn/wangmai/blob/main/backend/src/modules/availability/routes.ts): `backend/src/modules/availability/routes.ts`

### Persistence

- [Database client](https://github.com/soupgorn/wangmai/blob/main/backend/src/db/client.ts): `backend/src/db/client.ts`
- [Relational schema](https://github.com/soupgorn/wangmai/blob/main/backend/src/db/schema.ts): `backend/src/db/schema.ts`
- **PostgreSQL**

### Shared domain

- [Schedule rules](https://github.com/soupgorn/wangmai/blob/main/packages/shared/src/schedule.ts): `packages/shared/src/schedule.ts`
- [Availability rules](https://github.com/soupgorn/wangmai/blob/main/packages/shared/src/availability.ts): `packages/shared/src/availability.ts`

### Other components

- **Workspace user**

## Connections

- Workspace user → Google login: signs in (evidence: `README.md`)
- Workspace user → Schedule workspace: manages schedule
- Schedule workspace → Schedule repository: loads and saves (evidence: `frontend/src/features/core/availability-client.ts`)
- Schedule repository → Hono API: requests schedule API
- Hono API → Google authentication: routes auth requests (evidence: `backend/src/app.ts`)
- Hono API → Schedule endpoints: mounts schedule routes (evidence: `backend/src/app.ts`)
- Hono API → Availability search: mounts finder routes (evidence: `backend/src/app.ts`)
- Schedule endpoints → Google authentication: validates sessions (evidence: `backend/src/modules/schedule/routes.ts`)
- Availability search → Google authentication: validates sessions (evidence: `backend/src/modules/availability/routes.ts`)
- Schedule endpoints → Database client: reads and writes (evidence: `backend/src/modules/schedule/routes.ts`)
- Availability search → Database client: queries schedules (evidence: `backend/src/modules/availability/routes.ts`)
- Schedule endpoints → Schedule rules: validates blocks (evidence: `backend/src/modules/schedule/routes.ts`)
- Availability search → Availability rules: classifies availability (evidence: `backend/src/modules/availability/routes.ts`)
- Availability rules → Schedule rules: uses schedule rules (evidence: `packages/shared/src/availability.ts`)
- Database client → Relational schema: configures ORM (evidence: `backend/src/db/client.ts`)
- Database client → PostgreSQL: connects (evidence: `backend/src/db/client.ts`)
- Google authentication → Database client: uses database (evidence: `backend/src/auth/auth.ts`)
- Google authentication → Relational schema: adapts tables (evidence: `backend/src/auth/auth.ts`)
- Backend startup → Hono API: starts server (evidence: `backend/src/index.ts`)
- Backend startup → Google authentication: creates auth (evidence: `backend/src/index.ts`)
- Backend startup → Database client: creates database (evidence: `backend/src/index.ts`)
- Backend startup → Runtime configuration: loads configuration (evidence: `backend/src/index.ts`)
- Preview pages → Fictional preview: presents preview
- Availability finder → Availability search: searches availability
- Schedule editing → Schedule endpoints: edits schedule
- Sharing settings → Schedule endpoints: updates preferences