# brajbhujel/event-planner architecture

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

- Interactive diagram: https://gitdiagram.com/brajbhujel/event-planner
- Repository: https://github.com/brajbhujel/event-planner

## Overview

Event Planner is a split Next.js UI and Express REST API for account-secured event creation, discovery, invitations, and RSVP. The main user journey is authenticate, browse or manage events, then inspect details or RSVP; the API validates and applies visibility rules before serving event and dashboard data. The README documents OTP email verification, optional TOTP, cookie-based JWT sessions, normalized tags/invitations, and cached UI lists. Some frontend implementation links and event-service internals are unsampled, so those relationships are shown only where documented or evidenced by the index.

Main entry points: [`backend/src/services/auth.ts`](https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/auth.ts) (Account and session logic), [`backend/src/config/db.ts`](https://github.com/brajbhujel/event-planner/blob/main/backend/src/config/db.ts) (Knex database access), [`backend/src/controllers/auth.controller.ts`](https://github.com/brajbhujel/event-planner/blob/main/backend/src/controllers/auth.controller.ts) (Auth controller), [`backend/src/app.ts`](https://github.com/brajbhujel/event-planner/blob/main/backend/src/app.ts) (Express API app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js workspace"]
  node_auth_ui["Sign-in and signup<br/>[auth-form.tsx]"]
  node_workspace_ui["Workspace pages<br/>[dashboard-page.tsx]"]
  node_event_ui["Event management<br/>[event-form.tsx]"]
  node_event_detail["Event details and RSVP"]
  node_profile_ui["Profile and 2FA settings<br/>[profile-page.tsx]"]
  node_ui_auth_service["Auth API client<br/>[auth.service.ts]"]
  node_ui_event_service["Event API client<br/>[events.service.ts]"]
  node_workspace_cache["Workspace cache<br/>[workspace-store.ts]"]
end

subgraph group_api["REST API"]
  node_api_app["Express API app<br/>[app.ts]"]
  node_auth_routes["Auth routes<br/>[auth.ts]"]
  node_event_routes["Event routes<br/>[events.ts]"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_event_controller["Event controller"]
end

subgraph group_domain["Application services"]
  node_auth_service["Account and session logic<br/>[auth.ts]"]
  node_event_service["Event visibility and operations<br/>[events.ts]"]
  node_validation["Request validation<br/>[index.ts]"]
  node_otp_service["Email OTP<br/>[otp.ts]"]
  node_totp_service["TOTP and backup codes<br/>[two-factor.ts]"]
end

subgraph group_infra["State and security"]
  node_token_service["JWT issuance<br/>[tokens.ts]"]
  node_auth_middleware["Session authentication<br/>[auth.ts]"]
  node_cookie_session["HttpOnly cookies<br/>[cookies.ts]"]
  node_db_config["Knex database access<br/>[db.ts]"]
end

node_user(("Event planner"))
node_postgres[("PostgreSQL")]

node_user -.->|"signs in"| node_auth_ui
node_user -.->|"plans events"| node_workspace_ui
node_auth_ui -.->|"submits auth"| node_ui_auth_service
node_workspace_ui -.->|"uses cache"| node_workspace_cache
node_event_ui -.->|"submits changes"| node_ui_event_service
node_event_detail -.->|"loads details"| node_ui_event_service
node_profile_ui -.->|"updates account"| node_ui_auth_service
node_ui_auth_service -->|"calls REST API"| node_api_app
node_ui_event_service -->|"calls REST API"| node_api_app
node_api_app -->|"mounts routes"| node_auth_routes
node_api_app -->|"mounts routes"| node_event_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_event_routes -->|"dispatches"| node_event_controller
node_auth_controller -->|"calls auth logic"| node_auth_service
node_event_controller -->|"calls event logic"| node_event_service
node_auth_controller -->|"validates input"| node_validation
node_event_controller -->|"validates input"| node_validation
node_auth_service -->|"issues and checks OTP"| node_otp_service
node_auth_service -->|"delegates 2FA"| node_totp_service
node_auth_service -->|"issues sessions"| node_token_service
node_auth_controller -->|"sets session cookies"| node_cookie_session
node_auth_middleware -->|"verifies access token"| node_token_service
node_auth_middleware -->|"reads session cookie"| node_cookie_session
node_auth_routes -->|"guards account routes"| node_auth_middleware
node_auth_service -->|"reads and writes users"| node_db_config
node_event_service -->|"reads and writes events"| node_db_config
node_otp_service -->|"stores OTP state"| node_db_config
node_totp_service -->|"stores 2FA state"| node_db_config
node_db_config -->|"connects"| node_postgres

click node_auth_ui "https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/auth/auth-form.tsx"
click node_workspace_ui "https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/workspace/dashboard-page.tsx"
click node_event_ui "https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/workspace/event-form.tsx"
click node_event_detail "https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/workspace/event-detail-page.tsx"
click node_profile_ui "https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/workspace/profile-page.tsx"
click node_ui_auth_service "https://github.com/brajbhujel/event-planner/blob/main/frontend/src/services/auth.service.ts"
click node_ui_event_service "https://github.com/brajbhujel/event-planner/blob/main/frontend/src/services/events.service.ts"
click node_workspace_cache "https://github.com/brajbhujel/event-planner/blob/main/frontend/src/stores/workspace-store.ts"
click node_api_app "https://github.com/brajbhujel/event-planner/blob/main/backend/src/app.ts"
click node_auth_routes "https://github.com/brajbhujel/event-planner/blob/main/backend/src/routes/auth.ts"
click node_event_routes "https://github.com/brajbhujel/event-planner/blob/main/backend/src/routes/events.ts"
click node_auth_controller "https://github.com/brajbhujel/event-planner/blob/main/backend/src/controllers/auth.controller.ts"
click node_event_controller "https://github.com/brajbhujel/event-planner/blob/main/backend/src/controllers/events.controller.ts"
click node_auth_service "https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/auth.ts"
click node_event_service "https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/events.ts"
click node_validation "https://github.com/brajbhujel/event-planner/blob/main/backend/src/validations/index.ts"
click node_otp_service "https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/otp.ts"
click node_totp_service "https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/two-factor.ts"
click node_token_service "https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/tokens.ts"
click node_auth_middleware "https://github.com/brajbhujel/event-planner/blob/main/backend/src/middleware/auth.ts"
click node_cookie_session "https://github.com/brajbhujel/event-planner/blob/main/backend/src/utils/cookies.ts"
click node_db_config "https://github.com/brajbhujel/event-planner/blob/main/backend/src/config/db.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_auth_ui,node_workspace_ui,node_event_ui,node_event_detail,node_profile_ui,node_ui_auth_service,node_ui_event_service,node_workspace_cache toneBlue
class node_api_app,node_auth_routes,node_event_routes,node_auth_controller,node_event_controller,node_postgres toneAmber
class node_auth_service,node_event_service,node_validation,node_otp_service,node_totp_service toneMint
class node_token_service,node_auth_middleware,node_cookie_session,node_db_config toneRose
class node_user toneIndigo
```

## Components

### Next.js workspace

- [Sign-in and signup](https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/auth/auth-form.tsx): `frontend/src/components/auth/auth-form.tsx`
- [Workspace pages](https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/workspace/dashboard-page.tsx): `frontend/src/components/workspace/dashboard-page.tsx`
- [Event management](https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/workspace/event-form.tsx): `frontend/src/components/workspace/event-form.tsx`
- [Event details and RSVP](https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/workspace/event-detail-page.tsx): `frontend/src/components/workspace/event-detail-page.tsx`
- [Profile and 2FA settings](https://github.com/brajbhujel/event-planner/blob/main/frontend/src/components/workspace/profile-page.tsx): `frontend/src/components/workspace/profile-page.tsx`
- [Auth API client](https://github.com/brajbhujel/event-planner/blob/main/frontend/src/services/auth.service.ts): `frontend/src/services/auth.service.ts`
- [Event API client](https://github.com/brajbhujel/event-planner/blob/main/frontend/src/services/events.service.ts): `frontend/src/services/events.service.ts`
- [Workspace cache](https://github.com/brajbhujel/event-planner/blob/main/frontend/src/stores/workspace-store.ts): `frontend/src/stores/workspace-store.ts`

### REST API

- [Express API app](https://github.com/brajbhujel/event-planner/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Auth routes](https://github.com/brajbhujel/event-planner/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Event routes](https://github.com/brajbhujel/event-planner/blob/main/backend/src/routes/events.ts): `backend/src/routes/events.ts`
- [Auth controller](https://github.com/brajbhujel/event-planner/blob/main/backend/src/controllers/auth.controller.ts): `backend/src/controllers/auth.controller.ts`
- [Event controller](https://github.com/brajbhujel/event-planner/blob/main/backend/src/controllers/events.controller.ts): `backend/src/controllers/events.controller.ts`

### Application services

- [Account and session logic](https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/auth.ts): `backend/src/services/auth.ts`
- [Event visibility and operations](https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/events.ts): `backend/src/services/events.ts`
- [Request validation](https://github.com/brajbhujel/event-planner/blob/main/backend/src/validations/index.ts): `backend/src/validations/index.ts`
- [Email OTP](https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/otp.ts): `backend/src/services/otp.ts`
- [TOTP and backup codes](https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/two-factor.ts): `backend/src/services/two-factor.ts`

### State and security

- [JWT issuance](https://github.com/brajbhujel/event-planner/blob/main/backend/src/services/tokens.ts): `backend/src/services/tokens.ts`
- [Session authentication](https://github.com/brajbhujel/event-planner/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`
- [HttpOnly cookies](https://github.com/brajbhujel/event-planner/blob/main/backend/src/utils/cookies.ts): `backend/src/utils/cookies.ts`
- [Knex database access](https://github.com/brajbhujel/event-planner/blob/main/backend/src/config/db.ts): `backend/src/config/db.ts`

### Other components

- **Event planner**
- **PostgreSQL**

## Connections

- Event planner → Sign-in and signup: signs in
- Event planner → Workspace pages: plans events
- Sign-in and signup → Auth API client: submits auth
- Workspace pages → Workspace cache: uses cache
- Event management → Event API client: submits changes
- Event details and RSVP → Event API client: loads details
- Profile and 2FA settings → Auth API client: updates account
- Auth API client → Express API app: calls REST API (evidence: `README.md`)
- Event API client → Express API app: calls REST API (evidence: `README.md`)
- Express API app → Auth routes: mounts routes (evidence: `backend/src/app.ts`)
- Express API app → Event routes: mounts routes (evidence: `backend/src/app.ts`)
- Auth routes → Auth controller: dispatches (evidence: `backend/src/routes/auth.ts`)
- Event routes → Event controller: dispatches (evidence: `backend/src/routes/events.ts`)
- Auth controller → Account and session logic: calls auth logic (evidence: `backend/src/controllers/auth.controller.ts`)
- Event controller → Event visibility and operations: calls event logic (evidence: `backend/src/controllers/events.controller.ts`)
- Auth controller → Request validation: validates input (evidence: `backend/src/controllers/auth.controller.ts`)
- Event controller → Request validation: validates input (evidence: `backend/src/controllers/events.controller.ts`)
- Account and session logic → Email OTP: issues and checks OTP (evidence: `backend/src/services/auth.ts`)
- Account and session logic → TOTP and backup codes: delegates 2FA (evidence: `backend/src/services/auth.ts`)
- Account and session logic → JWT issuance: issues sessions (evidence: `backend/src/services/auth.ts`)
- Auth controller → HttpOnly cookies: sets session cookies (evidence: `backend/src/controllers/auth.controller.ts`)
- Session authentication → JWT issuance: verifies access token (evidence: `backend/src/middleware/auth.ts`)
- Session authentication → HttpOnly cookies: reads session cookie (evidence: `backend/src/middleware/auth.ts`)
- Auth routes → Session authentication: guards account routes (evidence: `backend/src/routes/auth.ts`)
- Account and session logic → Knex database access: reads and writes users (evidence: `backend/src/services/auth.ts`)
- Event visibility and operations → Knex database access: reads and writes events (evidence: `backend/src/services/events.ts`)
- Email OTP → Knex database access: stores OTP state (evidence: `backend/src/services/otp.ts`)
- TOTP and backup codes → Knex database access: stores 2FA state (evidence: `backend/src/services/two-factor.ts`)
- Knex database access → PostgreSQL: connects (evidence: `backend/src/config/db.ts`)
