How gagan-zeus/zerodesk works
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.js API entry · orgController.js Org controller · auth.js Auth routes · otp.js OTP routes
Components 32
Client
React + Vite frontend handling auth flow, routing, and UI orchestration.
- App shell · Top-level client composition and route wiring.
client/src/App.jsx - Auth state · Holds session, OTP, token, and active organization state.
client/src/context/AuthContext.jsx - Route guards · Enforces guest, authenticated, OTP, and onboarding stages.
client/src/guards/RouteGuards.jsx - API client · Shared HTTP client for backend requests.
client/src/services/api.js - Auth service · Client-side auth and session request helpers.
client/src/services/authService.js - Auth funnel · Login, email auth, OTP, onboarding, and landing entry screens.
client/src/pages/AuthFlow.jsx - OTP page · Handles OTP verification step in the staged login flow.
client/src/pages/OtpPage.jsx - Org onboarding · Organization creation, joining, and selection UI.
client/src/pages/OrgOnboardingPage.jsx - Dashboard · Post-onboarding application home for authenticated users.
client/src/pages/DashboardPage.jsx
Server
Express API handling authentication, onboarding, org isolation, and tasks.
- API entry · Main backend application bootstrap and route mounting.
server/server.js - Auth routes · Login, registration, OAuth, and user session endpoints.
server/routes/auth.js - OTP routes · Send, verify, and resend OTP endpoints.
server/routes/otp.js - Org routes · Organization create, join, list, select, and fetch endpoints.
server/routes/org.js - Task routes · Organization-scoped task CRUD endpoints.
server/routes/tasks.js - Auth controller · Coordinates credentials login, OAuth callbacks, and user lookup.
server/controllers/authController.js - OTP controller · Drives OTP send and verify flows.
server/controllers/otpController.js - Org controller · Implements organization membership and selection actions.
server/controllers/orgController.js - Task controller · Implements org-aware task operations and access checks.
server/controllers/taskController.js - Auth middleware · Enforces JWT, OTP completion, org selection, and role restrictions.
server/middleware/auth.js - Rate limiter · Protects auth and OTP endpoints from abuse.
server/middleware/rateLimiter.js - Validation · Request validation for incoming API payloads.
server/middleware/validate.js - Error handler · Global backend failure normalization.
server/middleware/errorHandler.js - JWT service · Signs and verifies pre-auth and full session tokens.
server/services/jwtService.js - OTP service · Generates, hashes, stores, and checks OTP codes.
server/services/otpService.js - Email service · Sends OTP mail through SMTP.
server/services/emailService.js
Data
MongoDB-backed persistence models for users, organizations, OTPs, and tasks.
- User · Stores credentials, provider metadata, memberships, and active organization.
server/models/User.js - Organization · Stores org metadata, join code, creator, and members.
server/models/Organization.js - OTP · Persists hashed OTP codes with attempts and expiration.
server/models/OTP.js - Task · Persists org-scoped tasks and ownership metadata.
server/models/Task.js
External
Third-party identity and delivery dependencies used by the auth pipeline.
- MongoDB · Primary persistence backend for users, organizations, OTPs, and tasks.
- OAuth providers · Google and GitHub authentication integrations.
- SMTP · External mail delivery used for OTP messages.
Connections 36
- 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.