# rahul1015s/gen-notes architecture

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

- Interactive diagram: https://gitdiagram.com/rahul1015s/gen-notes
- Repository: https://github.com/rahul1015s/gen-notes

## Overview

1. **Overall shape**
   Gen-Notes is a two-tier monorepo: a **React/Vite frontend** in `Frontend/` and a **Node.js/Express backend** in `Backend/`, with **MongoDB** as the shared persistence layer. The architecture is centered on authenticated user-owned note data, with additional subsystems for folders, tags, locks, reminders, push, and offline sync.

2. **Frontend boundary**
   The frontend is the user interaction layer. `src/App.jsx`, `routes.jsx`, and `pages/` define page-level navigation, while `context/AuthContext.jsx` holds the auth session state. `components/` contains reusable UI pieces such as the editor, dashboard shell, login/signup flows, lock screens, and reminder/tag/folder widgets.

3. **Frontend feature organization**
   The UI is split into feature-oriented modules: `features/folders`, `features/search`, and `features/tags`, plus dashboard-specific components under `components/dashboard`. This suggests a modular client where each major note-management capability is isolated from the app shell and shared widgets.

4. **Client-side API and domain services**
   The frontend does not talk to the backend directly from components only; instead, it uses service modules in `src/services/` and helpers in `src/lib/`. These wrappers cover notes, folders, tags, reminders, locks, push, offline sync, and auth-related flows, with `axios` used as the main HTTP client.

5. **Offline/PWA layer**
   The app is PWA-enabled. `src/sw.js`, `src/services/offlineSyncService.js`, `src/services/backgroundSync.js`, `src/hooks/useOfflineSync.js`, and the manifest/public PWA files indicate local offline operation, queued synchronization, and service-worker-based installability. This is an important architectural boundary because note changes can be staged locally and later reconciled with the server.

6. **Backend HTTP/API layer**
   The backend is organized as an Express API with route modules in `routes/` and controller modules in `controllers/`. Each route domain maps cleanly to a controller: auth, notes, folders, tags, users, reminders, push, lock, sync, and WebAuthn. This is a classic request/response architecture with thin routing and domain logic concentrated in controllers and services.

7. **Backend domain model**
   MongoDB collections are represented by Mongoose models in `models/`: `user`, `note`, `folder`, `tag`, `reminder`, `noteLock`, `pushSubscription`, and `schedulerState`. This model set shows the app is more than a plain notes CRUD system; it includes access control/locking, scheduled tasks, notification delivery, and user personalization.

8. **Security and access control**
   Authentication is enforced through `middlewares/auth.middleware.js`, and the backend also includes rate limiting and centralized error handling. The presence of `webauthn.controller.js` and `services/webauthn.service.js` means the app supports stronger authentication than passwords alone, likely for passkeys/biometrics. Note data is private per user, so auth is the boundary protecting every data-facing API.

9. **Locking and collaboration constraints**
   The `noteLock` model, `lock.routes.js`, and lock-related frontend components (`PinLockModal`, `GestureLock`, `PatternLock`, `BiometricPrompt`, `NoteLockSettings`) indicate a dedicated protection layer for sensitive notes. This is distinct from login auth: it is a per-note access or unlocking mechanism enforced across client UI and backend state.

10. **Reminders, email, and push delivery**
   Reminder functionality is split between API controllers/models and backend services. `services/reminderScheduler.js`, `services/mail.js`, `services/push.service.js`, and email templates support time-based notifications, email delivery, and web push. `pushSubscription` persistence shows the backend stores browser push endpoints for later delivery.

11. **Synchronization and background jobs**
   `controllers/sync.controller.js` plus `services/dailySyncScheduler.js` and `models/schedulerState.model.js` indicate periodic backend processing in addition to user-triggered API calls. This layer likely handles reconciliation, reminder execution, or maintenance tasks that keep offline edits and scheduled actions consistent.

12. **Runtime and deployment boundaries**
   `Backend/startServer.js` and `Backend/app.js` define the server bootstrap, while `Frontend/main.jsx` is the browser entry point. Both sides have `vercel.json`, suggesting deployment to Vercel-compatible environments, but the core runtime remains a browser SPA talking to an Express API backed by MongoDB. The main diagram boundary should therefore show: browser client → HTTP API → database, with side channels for push, email, WebAuthn, and background schedulers.

Main entry points: [`Backend/controllers`](https://github.com/rahul1015s/gen-notes/tree/main/Backend/controllers) (Controllers), [`Frontend/src/services`](https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/services) (Client services), [`Frontend/src/App.jsx`](https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/App.jsx) (App shell), [`Backend/services`](https://github.com/rahul1015s/gen-notes/tree/main/Backend/services) (Background services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>react spa<br/>[App.jsx]"]
  node_frontend_pages["Pages<br/>views"]
  node_frontend_components["UI components<br/>ui kit"]
  node_frontend_features["Feature modules<br/>feature ui"]
  node_frontend_services["Client services<br/>api client"]
  node_frontend_offline["Offline layer<br/>pwa sync<br/>[sw.js]"]
  node_frontend_auth(("Auth state<br/>session context<br/>[AuthContext.jsx]"))
  node_frontend_webauthn["Passkey client<br/>webauthn client<br/>[webauthn.js]"]
end

subgraph group_backend["Backend"]
  node_backend_server["Server app<br/>express bootstrap<br/>[app.js]"]
  node_backend_routes["API routes<br/>routing"]
  node_backend_controllers["Controllers<br/>request handlers"]
  node_backend_middleware["Middleware<br/>cross-cutting"]
  node_backend_models[("Data models<br/>mongoose models")]
  node_backend_services["Background services<br/>jobs and integrations"]
  node_backend_db[("MongoDB<br/>database<br/>[mongodb.js]")]
end

subgraph group_shared["Shared infra"]
  node_shared_sync{{"Sync pipeline<br/>offline reconciliation<br/>[sync.controller.js]"}}
  node_shared_security{{"Access control<br/>auth and locks<br/>[auth.middleware.js]"}}
  node_shared_notifications{{"Notifications<br/>delivery pipeline"}}
end

node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"composes"| node_frontend_components
node_frontend_app -->|"reads session"| node_frontend_auth
node_frontend_pages -->|"uses"| node_frontend_services
node_frontend_components -->|"calls"| node_frontend_services
node_frontend_features -->|"uses"| node_frontend_services
node_frontend_offline -->|"queues sync"| node_frontend_services
node_frontend_webauthn -->|"supports"| node_shared_security
node_frontend_services -->|"HTTP API"| node_backend_server
node_backend_server -->|"mounts"| node_backend_routes
node_backend_routes -->|"dispatches"| node_backend_controllers
node_backend_controllers -->|"persists"| node_backend_models
node_backend_models -->|"stored in"| node_backend_db
node_backend_controllers -->|"protected by"| node_backend_middleware
node_backend_controllers -->|"delegates to"| node_backend_services
node_backend_services -->|"drives"| node_shared_notifications
node_backend_controllers -->|"coordinates"| node_shared_sync
node_backend_middleware -->|"enforces"| node_shared_security
node_backend_services -->|"integrates"| node_shared_security

click node_frontend_app "https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/App.jsx"
click node_frontend_pages "https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/pages"
click node_frontend_components "https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/components"
click node_frontend_features "https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/features"
click node_frontend_services "https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/services"
click node_frontend_offline "https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/sw.js"
click node_frontend_auth "https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/context/AuthContext.jsx"
click node_frontend_webauthn "https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/lib/webauthn.js"
click node_backend_server "https://github.com/rahul1015s/gen-notes/blob/main/Backend/app.js"
click node_backend_routes "https://github.com/rahul1015s/gen-notes/tree/main/Backend/routes"
click node_backend_controllers "https://github.com/rahul1015s/gen-notes/tree/main/Backend/controllers"
click node_backend_middleware "https://github.com/rahul1015s/gen-notes/tree/main/Backend/middlewares"
click node_backend_models "https://github.com/rahul1015s/gen-notes/tree/main/Backend/models"
click node_backend_services "https://github.com/rahul1015s/gen-notes/tree/main/Backend/services"
click node_backend_db "https://github.com/rahul1015s/gen-notes/blob/main/Backend/database/mongodb.js"
click node_shared_sync "https://github.com/rahul1015s/gen-notes/blob/main/Backend/controllers/sync.controller.js"
click node_shared_security "https://github.com/rahul1015s/gen-notes/blob/main/Backend/middlewares/auth.middleware.js"
click node_shared_notifications "https://github.com/rahul1015s/gen-notes/blob/main/Backend/services/reminderScheduler.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_frontend_app,node_frontend_pages,node_frontend_components,node_frontend_features,node_frontend_services,node_frontend_offline,node_frontend_auth,node_frontend_webauthn toneBlue
class node_backend_server,node_backend_routes,node_backend_controllers,node_backend_middleware,node_backend_models,node_backend_services,node_backend_db toneAmber
class node_shared_sync,node_shared_security,node_shared_notifications toneMint
```

## Components

### Frontend

React/Vite client, UI shell, and offline-capable note workflows.

- [App shell](https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/App.jsx): react spa · Browser entry, routing, and global auth/session wiring. · `Frontend/src/App.jsx`
- [Pages](https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/pages): views · Top-level screens for notes, folders, settings, and auth flows. · `Frontend/src/pages`
- [UI components](https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/components): ui kit · Reusable editor, dashboard, lock, login, and note widgets. · `Frontend/src/components`
- [Feature modules](https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/features): feature ui · Focused client modules for folders, search, and tags. · `Frontend/src/features`
- [Client services](https://github.com/rahul1015s/gen-notes/tree/main/Frontend/src/services): api client · Axios-backed service layer for notes, locks, reminders, push, sync, and auth flows. · `Frontend/src/services`
- [Offline layer](https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/sw.js): pwa sync · Service worker and background sync for queued offline edits and reconciliation. · `Frontend/src/sw.js`
- [Auth state](https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/context/AuthContext.jsx): session context · Client-side authenticated user session and access gating. · `Frontend/src/context/AuthContext.jsx`
- [Passkey client](https://github.com/rahul1015s/gen-notes/blob/main/Frontend/src/lib/webauthn.js): webauthn client · Browser-side helpers for WebAuthn and stronger sign-in flows. · `Frontend/src/lib/webauthn.js`

### Backend

Express API, domain controllers, and MongoDB persistence.

- [Server app](https://github.com/rahul1015s/gen-notes/blob/main/Backend/app.js): express bootstrap · Backend application bootstrap and HTTP server startup. · `Backend/app.js`
- [API routes](https://github.com/rahul1015s/gen-notes/tree/main/Backend/routes): routing · Endpoint mapping for auth, notes, folders, tags, users, reminders, push, lock, sync, and WebAuthn. · `Backend/routes`
- [Controllers](https://github.com/rahul1015s/gen-notes/tree/main/Backend/controllers): request handlers · Domain logic for note management, auth, locking, reminders, sync, and push. · `Backend/controllers`
- [Middleware](https://github.com/rahul1015s/gen-notes/tree/main/Backend/middlewares): cross-cutting · Auth protection, rate limiting, and centralized error handling. · `Backend/middlewares`
- [Data models](https://github.com/rahul1015s/gen-notes/tree/main/Backend/models): mongoose models · MongoDB collections for users, notes, folders, tags, reminders, locks, push subscriptions, and scheduler state. · `Backend/models`
- [Background services](https://github.com/rahul1015s/gen-notes/tree/main/Backend/services): jobs and integrations · Mail, push, reminder scheduling, daily sync, and WebAuthn support services. · `Backend/services`
- [MongoDB](https://github.com/rahul1015s/gen-notes/blob/main/Backend/database/mongodb.js): database · Shared persistence for user-owned notes and related state. · `Backend/database/mongodb.js`

### Shared infra

Cross-cutting deployment and runtime boundaries.

- [Sync pipeline](https://github.com/rahul1015s/gen-notes/blob/main/Backend/controllers/sync.controller.js): offline reconciliation · Server-side sync endpoints and schedulers that reconcile client edits with persistent state. · `Backend/controllers/sync.controller.js`
- [Access control](https://github.com/rahul1015s/gen-notes/blob/main/Backend/middlewares/auth.middleware.js): auth and locks · Authentication, WebAuthn, and per-note lock boundaries protecting private content. · `Backend/middlewares/auth.middleware.js`
- [Notifications](https://github.com/rahul1015s/gen-notes/blob/main/Backend/services/reminderScheduler.js): delivery pipeline · Reminder execution, email delivery, and web push dispatch. · `Backend/services/reminderScheduler.js`

## Connections

- App shell → Pages: renders · App shell routes users into page-level screens.
- App shell → UI components: composes · The app shell is built from reusable UI components.
- App shell → Auth state: reads session · Route access and UI state depend on auth context.
- Pages → Client services: uses · Pages call client services for data and actions.
- UI components → Client services: calls · Interactive widgets invoke service-layer APIs.
- Feature modules → Client services: uses · Feature modules are backed by dedicated client services.
- Offline layer → Client services: queues sync · Offline edits are staged and later pushed through service flows.
- Passkey client → Access control: supports · Client WebAuthn helpers participate in stronger authentication.
- Client services → Server app: HTTP API · Client services communicate with the Express backend.
- Server app → API routes: mounts · The server bootstraps route modules.
- API routes → Controllers: dispatches · Routes forward requests into domain controllers.
- Controllers → Data models: persists · Controllers read and write MongoDB-backed models.
- Data models → MongoDB: stored in · Mongoose models are backed by MongoDB connections.
- Controllers → Middleware: protected by · Request handlers rely on auth, rate limiting, and error middleware.
- Controllers → Background services: delegates to · Controllers invoke mail, push, sync, and WebAuthn services.
- Background services → Notifications: drives · Schedulers and delivery services execute reminder and notification flows.
- Controllers → Sync pipeline: coordinates · Sync controller and schedulers reconcile offline and server state.
- Middleware → Access control: enforces · Middleware forms the access-control boundary for private note data.
- Background services → Access control: integrates · WebAuthn service and lock-related flows reinforce secure access.
