# gagan-zeus/zerodesk architecture

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

- Interactive diagram: https://gitdiagram.com/gagan-zeus/zerodesk
- Repository: https://github.com/gagan-zeus/zerodesk

## Overview

1. **Repository shape**
   - This is a two-tier monorepo: a **React + Vite frontend** in `client/` and an **Express.js backend API** in `server/`.
   - The backend is backed by **MongoDB** via Mongoose models.
   - There is also a top-level `api/index.js` plus `vercel.json` files, suggesting the app can be deployed in a serverless-friendly setup, but the core architecture is still client/server.

2. **Frontend boundary**
   - The client is responsible for **routing, auth state, and UI flow orchestration**.
   - Main pieces:
     - `AuthContext.jsx` stores session state such as user, token, OTP status, and active organization.
     - `RouteGuards.jsx` enforces staged access: guest-only, authenticated, OTP-verified, and fully onboarded.
     - `services/api.js` and `authService.js` centralize backend calls.
   - Pages are organized around the auth/onboarding funnel: login, email auth, OTP, org onboarding, then dashboard.

3. **Frontend navigation flow**
   - The user journey is intentionally sequential:
     - `LoginPage` / `UnifiedLanding`
     - `EmailAuthPage` or OAuth-related paths
     - `OtpPage`
     - `OrgOnboardingPage`
     - `DashboardPage`
   - This flow matches the backend’s staged session model: a user is not fully “in” until they have a valid JWT, OTP verification, and an organization selected.

4. **Backend entry and module boundaries**
   - `server/server.js` is the main Express application entry point.
   - Backend logic is separated into:
     - `routes/` for URL grouping
     - `controllers/` for request handling
     - `services/` for reusable auth/OTP/email primitives
     - `middleware/` for security, validation, and error handling
     - `models/` for persistence schemas
   - `config/db.js` handles MongoDB connection, and `config/passport.js` configures OAuth strategies.

5. **Authentication subsystem**
   - The app supports **three auth paths**:
     - email/password
     - Google OAuth
     - GitHub OAuth
   - Auth is split into phases:
     - a **pre-auth session** used to reach OTP verification
     - a **full JWT session** used for protected application access
   - `jwtService.js` manages signing/verifying these tokens, and `authController.js` coordinates login, registration, OAuth callbacks, and user lookup.

6. **OTP verification subsystem**
   - OTP is a first-class security gate, not just a one-time signup step.
   - `otpController.js` and `otpService.js` handle send/verify/resend flows.
   - OTP codes are stored in the `OTP` model using **hashed values**, with **attempt limits** and **TTL-based expiration**.
   - `emailService.js` sends the OTP emails through SMTP, making email delivery an external dependency in the auth chain.

7. **Organization and tenant isolation**
   - Organizations are the main multi-tenant boundary in the system.
   - `Organization` stores org metadata, an auto-generated join code, members, and creator.
   - `User` stores org memberships and the currently active organization.
   - `orgController.js` implements create, join, list, select, and fetch actions.
   - Access to most app functions depends on the user having both OTP verification and an active organization.

8. **Task subsystem**
   - `Task` is scoped by `organizationId`, which is the key data-isolation boundary.
   - `taskController.js` handles CRUD, but every query is expected to be constrained to the active org.
   - Role-based permissions matter here:
     - owners can see/manage all tasks
     - members are limited to their own/assigned tasks, depending on the action
   - This makes the task module an org-aware application layer rather than a global task list.

9. **Persistence model**
   - MongoDB contains four primary collections:
     - `User`
     - `Organization`
     - `OTP`
     - `Task`
   - The schemas encode the app’s security model:
     - hashed passwords for local users
     - provider metadata for OAuth users
     - OTP expiration/attempt tracking
     - org-scoped tasks
   - The data model is designed around multi-organization membership, not a single-account/single-project structure.

10. **Middleware and enforcement**
   - `middleware/auth.js` is a major boundary layer: it enforces JWT validity, OTP completion, organization selection, and owner/member restrictions where needed.
   - `rateLimiter.js` protects auth and OTP endpoints from abuse.
   - `validate.js` adds request validation, likely using `express-validator`.
   - `errorHandler.js` standardizes backend failures into a global response path.

11. **External integrations**
   - **MongoDB** is the core datastore.
   - **Google and GitHub OAuth** are used for external identity.
   - **SMTP email** is required for OTP delivery and possibly auth-related notifications.
   - These integrations are not auxiliary; they are integral to the login and verification architecture.

12. **What an architecture diagram should emphasize**
   - The primary vertical flow is: **client auth screens → backend auth/OTP routes → MongoDB/email/OAuth services → org selection → task CRUD**.
   - The most important boundaries are:
     - public vs authenticated access
     - pre-auth vs fully authenticated JWTs
     - OTP-verified vs unverified sessions
     - organization-selected vs unselected sessions
     - org-scoped data vs global data
   - In other words, the app is structured as a staged identity/onboarding system wrapped around an org-isolated task management core.

Main entry points: [`server/server.js`](https://github.com/gagan-zeus/zerodesk/blob/main/server/server.js) (API entry), [`server/controllers/orgController.js`](https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/orgController.js) (Org controller), [`server/routes/auth.js`](https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/auth.js) (Auth routes), [`server/routes/otp.js`](https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/otp.js) (OTP routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_app["App shell<br/>react entry<br/>[App.jsx]"]
  node_client_auth(("Auth state<br/>context<br/>[AuthContext.jsx]"))
  node_client_guards{{"Route guards<br/>navigation guard<br/>[RouteGuards.jsx]"}}
  node_client_api["API client<br/>[api.js]"]
  node_client_authsvc["Auth service<br/>[authService.js]"]
  node_client_funnel["Auth funnel<br/>pages<br/>[AuthFlow.jsx]"]
  node_client_otp["OTP page<br/>[OtpPage.jsx]"]
  node_client_org["Org onboarding<br/>page"]
  node_client_dash["Dashboard<br/>page<br/>[DashboardPage.jsx]"]
end

subgraph group_server["Server"]
  node_server_app["API entry<br/>express app<br/>[server.js]"]
  node_server_auth["Auth routes<br/>[auth.js]"]
  node_server_otp["OTP routes<br/>[otp.js]"]
  node_server_org["Org routes<br/>[org.js]"]
  node_server_tasks["Task routes<br/>[tasks.js]"]
  node_server_authctl["Auth controller<br/>[authController.js]"]
  node_server_otpct["OTP controller<br/>[otpController.js]"]
  node_server_orgctl["Org controller<br/>[orgController.js]"]
  node_server_taskctl["Task controller<br/>[taskController.js]"]
  node_server_authmw{{"Auth middleware<br/>[auth.js]"}}
  node_server_limit{{"Rate limiter<br/>middleware<br/>[rateLimiter.js]"}}
  node_server_validate{{"Validation<br/>middleware<br/>[validate.js]"}}
  node_server_errors{{"Error handler<br/>middleware<br/>[errorHandler.js]"}}
  node_server_jwt["JWT service<br/>[jwtService.js]"]
  node_server_otpsvc["OTP service<br/>[otpService.js]"]
  node_server_email["Email service<br/>[emailService.js]"]
end

subgraph group_data["Data"]
  node_db_user[("User<br/>mongo model<br/>[User.js]")]
  node_db_org[("Organization<br/>mongo model<br/>[Organization.js]")]
  node_db_otp[("OTP<br/>mongo model<br/>[OTP.js]")]
  node_db_task[("Task<br/>mongo model<br/>[Task.js]")]
end

subgraph group_external["External"]
  node_ext_mongo[("MongoDB<br/>datastore")]
  node_ext_oauth(("OAuth providers<br/>identity providers"))
  node_ext_smtp(("SMTP<br/>email transport"))
end

node_client_app -->|"provides session"| node_client_auth
node_client_app -->|"protects routes"| node_client_guards
node_client_funnel -->|"advances to"| node_client_otp
node_client_otp -->|"next step"| node_client_org
node_client_org -->|"enters"| node_client_dash
node_client_auth -->|"uses"| node_client_api
node_client_authsvc -->|"wraps"| node_client_api
node_client_api -->|"calls API"| node_server_app
node_server_app -->|"mounts"| node_server_auth
node_server_app -->|"mounts"| node_server_otp
node_server_app -->|"mounts"| node_server_org
node_server_app -->|"mounts"| node_server_tasks
node_server_auth -->|"delegates"| node_server_authctl
node_server_otp -->|"delegates"| node_server_otpct
node_server_org -->|"delegates"| node_server_orgctl
node_server_tasks -->|"delegates"| node_server_taskctl
node_server_authctl -->|"issues tokens"| node_server_jwt
node_server_otpct -->|"uses"| node_server_otpsvc
node_server_otpsvc -->|"sends mail"| node_server_email
node_server_authctl -->|"oauth login"| node_ext_oauth
node_server_email -->|"delivers"| node_ext_smtp
node_server_authctl -->|"reads/writes"| node_db_user
node_server_otpsvc -->|"stores"| node_db_otp
node_server_orgctl -->|"reads/writes"| node_db_org
node_server_orgctl -->|"updates"| node_db_user
node_server_taskctl -->|"reads/writes"| node_db_task
node_server_taskctl -->|"protected by"| node_server_authmw
node_server_orgctl -->|"protected by"| node_server_authmw
node_server_auth -->|"rate limited"| node_server_limit
node_server_otp -->|"rate limited"| node_server_limit
node_server_auth -->|"validated by"| node_server_validate
node_server_org -->|"validated by"| node_server_validate
node_server_otp -->|"validated by"| node_server_validate
node_server_app -->|"normalizes errors"| node_server_errors
node_server_authmw -->|"checks session"| node_db_user
node_server_orgctl -->|"enforces tenancy"| node_db_org

click node_client_app "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/App.jsx"
click node_client_auth "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/context/AuthContext.jsx"
click node_client_guards "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/guards/RouteGuards.jsx"
click node_client_api "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/services/api.js"
click node_client_authsvc "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/services/authService.js"
click node_client_funnel "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/pages/AuthFlow.jsx"
click node_client_otp "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/pages/OtpPage.jsx"
click node_client_org "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/pages/OrgOnboardingPage.jsx"
click node_client_dash "https://github.com/gagan-zeus/zerodesk/blob/main/client/src/pages/DashboardPage.jsx"
click node_server_app "https://github.com/gagan-zeus/zerodesk/blob/main/server/server.js"
click node_server_auth "https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/auth.js"
click node_server_otp "https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/otp.js"
click node_server_org "https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/org.js"
click node_server_tasks "https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/tasks.js"
click node_server_authctl "https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/authController.js"
click node_server_otpct "https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/otpController.js"
click node_server_orgctl "https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/orgController.js"
click node_server_taskctl "https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/taskController.js"
click node_server_authmw "https://github.com/gagan-zeus/zerodesk/blob/main/server/middleware/auth.js"
click node_server_limit "https://github.com/gagan-zeus/zerodesk/blob/main/server/middleware/rateLimiter.js"
click node_server_validate "https://github.com/gagan-zeus/zerodesk/blob/main/server/middleware/validate.js"
click node_server_errors "https://github.com/gagan-zeus/zerodesk/blob/main/server/middleware/errorHandler.js"
click node_server_jwt "https://github.com/gagan-zeus/zerodesk/blob/main/server/services/jwtService.js"
click node_server_otpsvc "https://github.com/gagan-zeus/zerodesk/blob/main/server/services/otpService.js"
click node_server_email "https://github.com/gagan-zeus/zerodesk/blob/main/server/services/emailService.js"
click node_db_user "https://github.com/gagan-zeus/zerodesk/blob/main/server/models/User.js"
click node_db_org "https://github.com/gagan-zeus/zerodesk/blob/main/server/models/Organization.js"
click node_db_otp "https://github.com/gagan-zeus/zerodesk/blob/main/server/models/OTP.js"
click node_db_task "https://github.com/gagan-zeus/zerodesk/blob/main/server/models/Task.js"

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_client_app,node_client_auth,node_client_guards,node_client_api,node_client_authsvc,node_client_funnel,node_client_otp,node_client_org,node_client_dash toneBlue
class node_server_app,node_server_auth,node_server_otp,node_server_org,node_server_tasks,node_server_authctl,node_server_otpct,node_server_orgctl,node_server_taskctl,node_server_authmw,node_server_limit,node_server_validate,node_server_errors,node_server_jwt,node_server_otpsvc,node_server_email toneAmber
class node_db_user,node_db_org,node_db_otp,node_db_task toneMint
class node_ext_mongo,node_ext_oauth,node_ext_smtp toneRose
```

## Components

### Client

React + Vite frontend handling auth flow, routing, and UI orchestration.

- [App shell](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/App.jsx): react entry · Top-level client composition and route wiring. · `client/src/App.jsx`
- [Auth state](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/context/AuthContext.jsx): context · Holds session, OTP, token, and active organization state. · `client/src/context/AuthContext.jsx`
- [Route guards](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/guards/RouteGuards.jsx): navigation guard · Enforces guest, authenticated, OTP, and onboarding stages. · `client/src/guards/RouteGuards.jsx`
- [API client](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/services/api.js): service · Shared HTTP client for backend requests. · `client/src/services/api.js`
- [Auth service](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/services/authService.js): service · Client-side auth and session request helpers. · `client/src/services/authService.js`
- [Auth funnel](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/pages/AuthFlow.jsx): pages · Login, email auth, OTP, onboarding, and landing entry screens. · `client/src/pages/AuthFlow.jsx`
- [OTP page](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/pages/OtpPage.jsx): page · Handles OTP verification step in the staged login flow. · `client/src/pages/OtpPage.jsx`
- [Org onboarding](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/pages/OrgOnboardingPage.jsx): page · Organization creation, joining, and selection UI. · `client/src/pages/OrgOnboardingPage.jsx`
- [Dashboard](https://github.com/gagan-zeus/zerodesk/blob/main/client/src/pages/DashboardPage.jsx): page · Post-onboarding application home for authenticated users. · `client/src/pages/DashboardPage.jsx`

### Server

Express API handling authentication, onboarding, org isolation, and tasks.

- [API entry](https://github.com/gagan-zeus/zerodesk/blob/main/server/server.js): express app · Main backend application bootstrap and route mounting. · `server/server.js`
- [Auth routes](https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/auth.js): routes · Login, registration, OAuth, and user session endpoints. · `server/routes/auth.js`
- [OTP routes](https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/otp.js): routes · Send, verify, and resend OTP endpoints. · `server/routes/otp.js`
- [Org routes](https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/org.js): routes · Organization create, join, list, select, and fetch endpoints. · `server/routes/org.js`
- [Task routes](https://github.com/gagan-zeus/zerodesk/blob/main/server/routes/tasks.js): routes · Organization-scoped task CRUD endpoints. · `server/routes/tasks.js`
- [Auth controller](https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/authController.js): controller · Coordinates credentials login, OAuth callbacks, and user lookup. · `server/controllers/authController.js`
- [OTP controller](https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/otpController.js): controller · Drives OTP send and verify flows. · `server/controllers/otpController.js`
- [Org controller](https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/orgController.js): controller · Implements organization membership and selection actions. · `server/controllers/orgController.js`
- [Task controller](https://github.com/gagan-zeus/zerodesk/blob/main/server/controllers/taskController.js): controller · Implements org-aware task operations and access checks. · `server/controllers/taskController.js`
- [Auth middleware](https://github.com/gagan-zeus/zerodesk/blob/main/server/middleware/auth.js): middleware · Enforces JWT, OTP completion, org selection, and role restrictions. · `server/middleware/auth.js`
- [Rate limiter](https://github.com/gagan-zeus/zerodesk/blob/main/server/middleware/rateLimiter.js): middleware · Protects auth and OTP endpoints from abuse. · `server/middleware/rateLimiter.js`
- [Validation](https://github.com/gagan-zeus/zerodesk/blob/main/server/middleware/validate.js): middleware · Request validation for incoming API payloads. · `server/middleware/validate.js`
- [Error handler](https://github.com/gagan-zeus/zerodesk/blob/main/server/middleware/errorHandler.js): middleware · Global backend failure normalization. · `server/middleware/errorHandler.js`
- [JWT service](https://github.com/gagan-zeus/zerodesk/blob/main/server/services/jwtService.js): service · Signs and verifies pre-auth and full session tokens. · `server/services/jwtService.js`
- [OTP service](https://github.com/gagan-zeus/zerodesk/blob/main/server/services/otpService.js): service · Generates, hashes, stores, and checks OTP codes. · `server/services/otpService.js`
- [Email service](https://github.com/gagan-zeus/zerodesk/blob/main/server/services/emailService.js): service · Sends OTP mail through SMTP. · `server/services/emailService.js`

### Data

MongoDB-backed persistence models for users, organizations, OTPs, and tasks.

- [User](https://github.com/gagan-zeus/zerodesk/blob/main/server/models/User.js): mongo model · Stores credentials, provider metadata, memberships, and active organization. · `server/models/User.js`
- [Organization](https://github.com/gagan-zeus/zerodesk/blob/main/server/models/Organization.js): mongo model · Stores org metadata, join code, creator, and members. · `server/models/Organization.js`
- [OTP](https://github.com/gagan-zeus/zerodesk/blob/main/server/models/OTP.js): mongo model · Persists hashed OTP codes with attempts and expiration. · `server/models/OTP.js`
- [Task](https://github.com/gagan-zeus/zerodesk/blob/main/server/models/Task.js): mongo model · Persists org-scoped tasks and ownership metadata. · `server/models/Task.js`

### External

Third-party identity and delivery dependencies used by the auth pipeline.

- **MongoDB**: datastore · Primary persistence backend for users, organizations, OTPs, and tasks.
- **OAuth providers**: identity providers · Google and GitHub authentication integrations.
- **SMTP**: email transport · External mail delivery used for OTP messages.

## Connections

- App shell → Auth state: provides session · App shell wraps the session state provider.
- App shell → Route guards: protects routes · App shell applies route-stage enforcement.
- Auth funnel → OTP page: advances to · Sequential flow moves users into OTP verification.
- OTP page → Org onboarding: next step · Verified users continue to organization onboarding.
- Org onboarding → Dashboard: enters · Selected organization unlocks the dashboard.
- Auth state → API client: uses · Auth state drives backend calls.
- Auth service → API client: wraps · Auth helpers call the shared API client.
- API client → API entry: calls API · Frontend requests hit the backend application.
- API entry → Auth routes: mounts · API entry mounts auth routes.
- API entry → OTP routes: mounts · API entry mounts OTP routes.
- API entry → Org routes: mounts · API entry mounts org routes.
- API entry → Task routes: mounts · API entry mounts task routes.
- Auth routes → Auth controller: delegates · Auth routes hand off to the auth controller.
- OTP routes → OTP controller: delegates · OTP routes hand off to the OTP controller.
- Org routes → Org controller: delegates · Org routes hand off to the organization controller.
- Task routes → Task controller: delegates · Task routes hand off to the task controller.
- Auth controller → JWT service: issues tokens · Auth controller signs and verifies session tokens.
- OTP controller → OTP service: uses · OTP controller relies on OTP service logic.
- OTP service → Email service: sends mail · OTP service delivers codes via email.
- Auth controller → OAuth providers: oauth login · OAuth callbacks depend on external identity providers.
- Email service → SMTP: delivers · Email service sends through SMTP infrastructure.
- Auth controller → User: reads/writes · Auth flow persists and loads user records.
- OTP service → OTP: stores · OTP service persists hashed codes and state.
- Org controller → Organization: reads/writes · Organization actions update org records.
- Org controller → User: updates · Org selection updates the user membership state.
- Task controller → Task: reads/writes · Task operations persist org-scoped tasks.
- Task controller → Auth middleware: protected by · Task endpoints rely on auth and org enforcement.
- Org controller → Auth middleware: protected by · Organization actions require authenticated staged access.
- Auth routes → Rate limiter: rate limited · Auth endpoints are abuse-protected.
- OTP routes → Rate limiter: rate limited · OTP endpoints are abuse-protected.
- Auth routes → Validation: validated by · Auth requests pass through input validation.
- Org routes → Validation: validated by · Org requests pass through input validation.
- OTP routes → Validation: validated by · OTP requests pass through input validation.
- API entry → Error handler: normalizes errors · Global error handling finalizes backend failures.
- Auth middleware → User: checks session · Middleware consults user state for staged access.
- Org controller → Organization: enforces tenancy · Organization boundary is used to isolate data access.
