# deepnotesapp/deepnotes architecture

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

- Interactive diagram: https://gitdiagram.com/deepnotesapp/deepnotes
- Repository: https://github.com/deepnotesapp/deepnotes

## Overview

DeepNotes is an end-to-end encrypted infinite-canvas notes product with nested pages and realtime collaboration. Users work in the client; its realtime client handles subscriptions and notifications, while the app server exposes session, user, group and page APIs plus webhook and websocket endpoints. The collaboration server handles shared page updates and snapshots; separate realtime and scheduler services support live data and cleanup. The README documents the product capabilities, but sampled code does not establish every client-to-service connection, so those links are omitted.

Main entry points: [`apps/app-server/src/trpc/router.ts`](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/router.ts) (tRPC router), [`apps/app-server/src/fastify/server.ts`](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/server.ts) (Fastify server), [`apps/collab-server/src/sockets.ts`](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/collab-server/src/sockets.ts) (Collaboration sockets), [`apps/app-server/src/trpc/api/sessions/login.ts`](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/sessions/login.ts) (Session API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_appui["Application UI<br/>[App.vue]"]
  node_routing["Client routing<br/>[routing.ts]"]
  node_realtimeclient["Realtime client<br/>[client.ts]"]
  node_contexts["Realtime contexts<br/>[context.ts]"]
  node_notifications["Notifications<br/>[notifications.ts]"]
  node_misc["Client utilities<br/>[misc.ts]"]
  node_resolvable["Async resolvable<br/>[resolvable.ts]"]
end

subgraph group_app["Application API"]
  node_fastify["Fastify server<br/>[server.ts]"]
  node_trpc["tRPC router<br/>[router.ts]"]
  node_sessions["Session API<br/>[login.ts]"]
  node_sessionrefresh["Session refresh<br/>[refresh.ts]"]
  node_demologin["Demo sessions<br/>[start-demo.ts]"]
  node_cookies["Session cookies<br/>[cookies.ts]"]
  node_jwt["JWT handling<br/>[jwt.ts]"]
  node_groupsapi["Group API<br/>[index.ts]"]
  node_pagesapi["Page API<br/>[index.ts]"]
  node_pagecreate["Page creation<br/>[create.ts]"]
  node_pagebump["Page updates<br/>[bump.ts]"]
  node_usersapi["User API<br/>[index.ts]"]
  node_stripehook["Stripe webhook<br/>[stripe-webhook.ts]"]
  node_revenuehook["RevenueCat webhook"]
  node_appwebhook["App Store webhook"]
end

subgraph group_collab["Collaboration"]
  node_collabserver["Collaboration sockets<br/>[sockets.ts]"]
  node_rooms["Page rooms"]
  node_buffer["Update buffering"]
  node_redis["Collab Redis<br/>[redis.ts]"]
end

subgraph group_services["Background services"]
  node_realtime["Realtime service<br/>[sockets.ts]"]
  node_scheduler["Retention cleanup<br/>[index.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_appui
node_appui -->|"uses"| node_misc
node_routing -->|"uses"| node_misc
node_realtimeclient -->|"uses"| node_contexts
node_realtimeclient -->|"loads"| node_notifications
node_fastify -->|"registers"| node_trpc
node_fastify -->|"registers"| node_stripehook
node_fastify -->|"registers"| node_revenuehook
node_trpc -->|"routes"| node_groupsapi
node_trpc -->|"routes"| node_pagesapi
node_trpc -->|"routes"| node_sessions
node_trpc -->|"routes"| node_usersapi
node_sessions -->|"includes"| node_sessionrefresh
node_sessions -->|"includes"| node_demologin
node_collabserver -->|"buffers updates"| node_buffer
node_collabserver -->|"uses"| node_redis
node_collabserver -->|"uses"| node_rooms
node_scheduler -->|"deletes expired data"| node_scheduler

click node_appui "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/App.vue"
click node_routing "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/routing.ts"
click node_realtimeclient "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/areas/realtime/client.ts"
click node_contexts "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/areas/realtime/context.ts"
click node_notifications "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/pages/notifications/notifications.ts"
click node_misc "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/utils/misc.ts"
click node_fastify "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/server.ts"
click node_trpc "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/router.ts"
click node_sessions "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/sessions/login.ts"
click node_sessionrefresh "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/sessions/refresh.ts"
click node_demologin "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/sessions/start-demo.ts"
click node_cookies "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/utils/cookies.ts"
click node_jwt "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/utils/jwt.ts"
click node_groupsapi "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/groups/index.ts"
click node_pagesapi "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/pages/index.ts"
click node_pagecreate "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/pages/create.ts"
click node_pagebump "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/pages/bump.ts"
click node_usersapi "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/users/index.ts"
click node_stripehook "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/stripe-webhook.ts"
click node_revenuehook "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/revenuecat-webhook.ts"
click node_appwebhook "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/app-store-webhook.ts"
click node_collabserver "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/collab-server/src/sockets.ts"
click node_rooms "https://github.com/deepnotesapp/deepnotes/tree/dev/apps/collab-server/src"
click node_buffer "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/collab-server/src/data/redis/bufferize-page-update.ts"
click node_redis "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/collab-server/src/data/redis.ts"
click node_realtime "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/realtime-server/src/sockets.ts"
click node_scheduler "https://github.com/deepnotesapp/deepnotes/blob/dev/apps/scheduler/src/index.ts"
click node_resolvable "https://github.com/deepnotesapp/deepnotes/blob/dev/packages/%40stdlib/misc/src/resolvable.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_appui,node_routing,node_realtimeclient,node_contexts,node_notifications,node_misc,node_resolvable,node_user toneBlue
class node_fastify,node_trpc,node_sessions,node_sessionrefresh,node_demologin,node_cookies,node_jwt,node_groupsapi,node_pagesapi,node_pagecreate,node_pagebump,node_usersapi,node_stripehook,node_revenuehook,node_appwebhook toneAmber
class node_collabserver,node_rooms,node_buffer,node_redis toneMint
class node_realtime,node_scheduler toneRose
```

## Components

### Client experience

- [Application UI](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/App.vue): `apps/client/src/App.vue`
- [Client routing](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/routing.ts): `apps/client/src/code/routing.ts`
- [Realtime client](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/areas/realtime/client.ts): `apps/client/src/code/areas/realtime/client.ts`
- [Realtime contexts](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/areas/realtime/context.ts): `apps/client/src/code/areas/realtime/context.ts`
- [Notifications](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/pages/notifications/notifications.ts): `apps/client/src/code/pages/notifications/notifications.ts`
- [Client utilities](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/client/src/code/utils/misc.ts): `apps/client/src/code/utils/misc.ts`
- [Async resolvable](https://github.com/deepnotesapp/deepnotes/blob/dev/packages/%40stdlib/misc/src/resolvable.ts): `packages/@stdlib/misc/src/resolvable.ts`

### Application API

- [Fastify server](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/server.ts): `apps/app-server/src/fastify/server.ts`
- [tRPC router](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/router.ts): `apps/app-server/src/trpc/router.ts`
- [Session API](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/sessions/login.ts): `apps/app-server/src/trpc/api/sessions/login.ts`
- [Session refresh](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/sessions/refresh.ts): `apps/app-server/src/trpc/api/sessions/refresh.ts`
- [Demo sessions](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/sessions/start-demo.ts): `apps/app-server/src/trpc/api/sessions/start-demo.ts`
- [Session cookies](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/utils/cookies.ts): `apps/app-server/src/utils/cookies.ts`
- [JWT handling](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/utils/jwt.ts): `apps/app-server/src/utils/jwt.ts`
- [Group API](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/groups/index.ts): `apps/app-server/src/trpc/api/groups/index.ts`
- [Page API](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/pages/index.ts): `apps/app-server/src/trpc/api/pages/index.ts`
- [Page creation](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/pages/create.ts): `apps/app-server/src/trpc/api/pages/create.ts`
- [Page updates](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/pages/bump.ts): `apps/app-server/src/trpc/api/pages/bump.ts`
- [User API](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/trpc/api/users/index.ts): `apps/app-server/src/trpc/api/users/index.ts`
- [Stripe webhook](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/stripe-webhook.ts): `apps/app-server/src/fastify/stripe-webhook.ts`
- [RevenueCat webhook](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/revenuecat-webhook.ts): `apps/app-server/src/fastify/revenuecat-webhook.ts`
- [App Store webhook](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/app-server/src/fastify/app-store-webhook.ts): `apps/app-server/src/fastify/app-store-webhook.ts`

### Collaboration

- [Collaboration sockets](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/collab-server/src/sockets.ts): `apps/collab-server/src/sockets.ts`
- [Page rooms](https://github.com/deepnotesapp/deepnotes/tree/dev/apps/collab-server/src): `apps/collab-server/src`
- [Update buffering](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/collab-server/src/data/redis/bufferize-page-update.ts): `apps/collab-server/src/data/redis/bufferize-page-update.ts`
- [Collab Redis](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/collab-server/src/data/redis.ts): `apps/collab-server/src/data/redis.ts`

### Background services

- [Realtime service](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/realtime-server/src/sockets.ts): `apps/realtime-server/src/sockets.ts`
- [Retention cleanup](https://github.com/deepnotesapp/deepnotes/blob/dev/apps/scheduler/src/index.ts): `apps/scheduler/src/index.ts`

### Other components

- **User**

## Connections

- User → Application UI: uses
- Application UI → Client utilities: uses (evidence: `apps/client/src/App.vue`)
- Client routing → Client utilities: uses (evidence: `apps/client/src/code/routing.ts`)
- Realtime client → Realtime contexts: uses (evidence: `apps/client/src/code/areas/realtime/client.ts`)
- Realtime client → Notifications: loads (evidence: `apps/client/src/code/areas/realtime/client.ts`)
- Fastify server → tRPC router: registers (evidence: `apps/app-server/src/fastify/server.ts`)
- Fastify server → Stripe webhook: registers (evidence: `apps/app-server/src/fastify/server.ts`)
- Fastify server → RevenueCat webhook: registers (evidence: `apps/app-server/src/fastify/server.ts`)
- tRPC router → Group API: routes (evidence: `apps/app-server/src/trpc/router.ts`)
- tRPC router → Page API: routes (evidence: `apps/app-server/src/trpc/router.ts`)
- tRPC router → Session API: routes (evidence: `apps/app-server/src/trpc/router.ts`)
- tRPC router → User API: routes (evidence: `apps/app-server/src/trpc/router.ts`)
- Session API → Session refresh: includes (evidence: `apps/app-server/src/trpc/api/sessions/index.ts`)
- Session API → Demo sessions: includes (evidence: `apps/app-server/src/trpc/api/sessions/index.ts`)
- Collaboration sockets → Update buffering: buffers updates (evidence: `apps/collab-server/src/sockets.ts`)
- Collaboration sockets → Collab Redis: uses (evidence: `apps/collab-server/src/sockets.ts`)
- Collaboration sockets → Page rooms: uses (evidence: `apps/collab-server/src/sockets.ts`)
- Retention cleanup → Retention cleanup: deletes expired data (evidence: `apps/scheduler/src/index.ts`)
