# ok2codei/jotdown architecture

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

- Interactive diagram: https://gitdiagram.com/ok2codei/jotdown
- Repository: https://github.com/ok2codei/jotdown

## Overview

JotDown is a full-stack notes application. Users authenticate, enter protected note and archive views, and create, search, edit, delete, archive, or restore notes; the frontend separates pages, hooks, and API services from the Express routes, middleware, controllers, and PostgreSQL access. Authentication, tags, folders, and theme support are also represented. The README documents product capabilities, while several frontend components and backend modules were not sampled; uncertain links are omitted rather than inferred.

Main entry points: [`backend/src/app.js`](https://github.com/ok2codei/jotdown/blob/main/backend/src/app.js) (Express server), [`backend/src/config/db.js`](https://github.com/ok2codei/jotdown/blob/main/backend/src/config/db.js) (PostgreSQL), [`frontend/src/routes/router.tsx`](https://github.com/ok2codei/jotdown/blob/main/frontend/src/routes/router.tsx) (App router), [`backend/src/middleware/authMiddleware.js`](https://github.com/ok2codei/jotdown/blob/main/backend/src/middleware/authMiddleware.js) (Token verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_router["App router<br/>[router.tsx]"]
  node_marketing["Home page<br/>[Home.tsx]"]
  node_theme["Theme controls<br/>[useDarkMode.ts]"]
end

subgraph group_auth["Authentication"]
  node_auth_pages["Login and register"]
  node_auth_hook["Auth hook<br/>[useAuth.ts]"]
  node_auth_context["Auth context<br/>[AuthContext.tsx]"]
  node_auth_service["Auth service<br/>[authService.ts]"]
  node_protected["Route guard<br/>[ProtectedRoute.tsx]"]
end

subgraph group_notes["Notes and organization"]
  node_notes_page["Notes page<br/>[Notes.tsx]"]
  node_archive_page["Archive page<br/>[Archive.tsx]"]
  node_note_hook["Note state<br/>[useNote.ts]"]
  node_note_views["Note views"]
  node_note_service["Note service<br/>[noteService.ts]"]
  node_tag_routes["Tag endpoints<br/>[tags.routes.js]"]
  node_tag_controller["Tag operations"]
  node_folder_routes["Folder endpoints<br/>[folders.routes.js]"]
  node_folder_controller["Folder operations"]
end

subgraph group_backend["Backend API"]
  node_note_api["Note endpoints<br/>[notes.routes.js]"]
  node_note_controller["Note operations"]
  node_auth_routes["Auth endpoints<br/>[auth.routes.js]"]
  node_auth_controller["Auth controllers"]
  node_users_routes["User endpoints<br/>[users.routes.js]"]
  node_users_controller["User operations"]
  node_server["Express server<br/>[app.js]"]
  node_auth_middleware["Token verification<br/>[authMiddleware.js]"]
end

subgraph group_persistence["Persistence"]
  node_database[("PostgreSQL<br/>[db.js]")]
end

node_user(("User"))

node_user -->|"uses"| node_router
node_router -->|"routes to"| node_marketing
node_router -->|"routes to"| node_notes_page
node_router -->|"routes to"| node_archive_page
node_router -->|"guards app"| node_protected
node_notes_page -->|"uses"| node_note_hook
node_notes_page -->|"renders"| node_note_views
node_note_hook -->|"calls"| node_note_service
node_note_service -.->|"requests"| node_note_api
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_users_routes
node_server -->|"mounts"| node_note_api
node_server -->|"mounts"| node_folder_routes
node_server -->|"mounts"| node_tag_routes
node_note_api -->|"verifies"| node_auth_middleware
node_note_api -->|"dispatches"| node_note_controller
node_tag_routes -->|"verifies"| node_auth_middleware
node_tag_routes -->|"dispatches"| node_tag_controller
node_folder_routes -->|"verifies"| node_auth_middleware
node_folder_routes -->|"dispatches"| node_folder_controller
node_auth_routes -->|"dispatches"| node_auth_controller
node_users_routes -->|"dispatches"| node_users_controller
node_users_routes -->|"verifies"| node_auth_middleware
node_auth_middleware -->|"checks users"| node_database
node_note_controller -->|"reads and writes"| node_database
node_tag_controller -->|"reads and writes"| node_database
node_folder_controller -->|"accesses"| node_database
node_auth_controller -->|"accesses"| node_database
node_users_controller -->|"accesses"| node_database
node_user -->|"authenticates"| node_auth_pages
node_auth_pages -->|"uses"| node_auth_hook
node_auth_pages -->|"calls"| node_auth_service
node_auth_hook -->|"reads"| node_auth_context
node_auth_context -.->|"uses"| node_auth_service
node_protected -->|"checks session"| node_auth_hook

click node_router "https://github.com/ok2codei/jotdown/blob/main/frontend/src/routes/router.tsx"
click node_marketing "https://github.com/ok2codei/jotdown/blob/main/frontend/src/pages/app/Home.tsx"
click node_notes_page "https://github.com/ok2codei/jotdown/blob/main/frontend/src/pages/app/Notes.tsx"
click node_archive_page "https://github.com/ok2codei/jotdown/blob/main/frontend/src/pages/app/Archive.tsx"
click node_note_hook "https://github.com/ok2codei/jotdown/blob/main/frontend/src/hooks/useNote.ts"
click node_note_views "https://github.com/ok2codei/jotdown/tree/main/frontend/src/components/notes"
click node_note_service "https://github.com/ok2codei/jotdown/blob/main/frontend/src/services/noteService.ts"
click node_note_api "https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/notes.routes.js"
click node_note_controller "https://github.com/ok2codei/jotdown/blob/main/backend/src/controllers/notes.controllers.js"
click node_tag_routes "https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/tags.routes.js"
click node_tag_controller "https://github.com/ok2codei/jotdown/blob/main/backend/src/controllers/tags.controllers.js"
click node_folder_routes "https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/folders.routes.js"
click node_folder_controller "https://github.com/ok2codei/jotdown/blob/main/backend/src/controllers/folders.controllers.js"
click node_auth_pages "https://github.com/ok2codei/jotdown/tree/main/frontend/src/pages/auth"
click node_auth_hook "https://github.com/ok2codei/jotdown/blob/main/frontend/src/hooks/useAuth.ts"
click node_auth_context "https://github.com/ok2codei/jotdown/blob/main/frontend/src/context/AuthContext.tsx"
click node_auth_service "https://github.com/ok2codei/jotdown/blob/main/frontend/src/services/authService.ts"
click node_protected "https://github.com/ok2codei/jotdown/blob/main/frontend/src/routes/ProtectedRoute.tsx"
click node_auth_routes "https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/auth.routes.js"
click node_auth_controller "https://github.com/ok2codei/jotdown/tree/main/backend/src/controllers"
click node_users_routes "https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/users.routes.js"
click node_users_controller "https://github.com/ok2codei/jotdown/blob/main/backend/src/controllers/users.controllers.js"
click node_server "https://github.com/ok2codei/jotdown/blob/main/backend/src/app.js"
click node_auth_middleware "https://github.com/ok2codei/jotdown/blob/main/backend/src/middleware/authMiddleware.js"
click node_database "https://github.com/ok2codei/jotdown/blob/main/backend/src/config/db.js"
click node_theme "https://github.com/ok2codei/jotdown/blob/main/frontend/src/hooks/useDarkMode.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_router,node_marketing,node_theme,node_user toneBlue
class node_auth_pages,node_auth_hook,node_auth_context,node_auth_service,node_protected toneAmber
class node_notes_page,node_archive_page,node_note_hook,node_note_views,node_note_service,node_tag_routes,node_tag_controller,node_folder_routes,node_folder_controller toneMint
class node_note_api,node_note_controller,node_auth_routes,node_auth_controller,node_users_routes,node_users_controller,node_server,node_auth_middleware toneRose
class node_database toneIndigo
```

## Components

### Frontend

- [App router](https://github.com/ok2codei/jotdown/blob/main/frontend/src/routes/router.tsx): `frontend/src/routes/router.tsx`
- [Home page](https://github.com/ok2codei/jotdown/blob/main/frontend/src/pages/app/Home.tsx): `frontend/src/pages/app/Home.tsx`
- [Theme controls](https://github.com/ok2codei/jotdown/blob/main/frontend/src/hooks/useDarkMode.ts): `frontend/src/hooks/useDarkMode.ts`

### Authentication

- [Login and register](https://github.com/ok2codei/jotdown/tree/main/frontend/src/pages/auth): `frontend/src/pages/auth`
- [Auth hook](https://github.com/ok2codei/jotdown/blob/main/frontend/src/hooks/useAuth.ts): `frontend/src/hooks/useAuth.ts`
- [Auth context](https://github.com/ok2codei/jotdown/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Auth service](https://github.com/ok2codei/jotdown/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- [Route guard](https://github.com/ok2codei/jotdown/blob/main/frontend/src/routes/ProtectedRoute.tsx): `frontend/src/routes/ProtectedRoute.tsx`

### Notes and organization

- [Notes page](https://github.com/ok2codei/jotdown/blob/main/frontend/src/pages/app/Notes.tsx): `frontend/src/pages/app/Notes.tsx`
- [Archive page](https://github.com/ok2codei/jotdown/blob/main/frontend/src/pages/app/Archive.tsx): `frontend/src/pages/app/Archive.tsx`
- [Note state](https://github.com/ok2codei/jotdown/blob/main/frontend/src/hooks/useNote.ts): `frontend/src/hooks/useNote.ts`
- [Note views](https://github.com/ok2codei/jotdown/tree/main/frontend/src/components/notes): `frontend/src/components/notes`
- [Note service](https://github.com/ok2codei/jotdown/blob/main/frontend/src/services/noteService.ts): `frontend/src/services/noteService.ts`
- [Tag endpoints](https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/tags.routes.js): `backend/src/routes/tags.routes.js`
- [Tag operations](https://github.com/ok2codei/jotdown/blob/main/backend/src/controllers/tags.controllers.js): `backend/src/controllers/tags.controllers.js`
- [Folder endpoints](https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/folders.routes.js): `backend/src/routes/folders.routes.js`
- [Folder operations](https://github.com/ok2codei/jotdown/blob/main/backend/src/controllers/folders.controllers.js): `backend/src/controllers/folders.controllers.js`

### Backend API

- [Note endpoints](https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/notes.routes.js): `backend/src/routes/notes.routes.js`
- [Note operations](https://github.com/ok2codei/jotdown/blob/main/backend/src/controllers/notes.controllers.js): `backend/src/controllers/notes.controllers.js`
- [Auth endpoints](https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/auth.routes.js): `backend/src/routes/auth.routes.js`
- [Auth controllers](https://github.com/ok2codei/jotdown/tree/main/backend/src/controllers): `backend/src/controllers`
- [User endpoints](https://github.com/ok2codei/jotdown/blob/main/backend/src/routes/users.routes.js): `backend/src/routes/users.routes.js`
- [User operations](https://github.com/ok2codei/jotdown/blob/main/backend/src/controllers/users.controllers.js): `backend/src/controllers/users.controllers.js`
- [Express server](https://github.com/ok2codei/jotdown/blob/main/backend/src/app.js): `backend/src/app.js`
- [Token verification](https://github.com/ok2codei/jotdown/blob/main/backend/src/middleware/authMiddleware.js): `backend/src/middleware/authMiddleware.js`

### Persistence

- [PostgreSQL](https://github.com/ok2codei/jotdown/blob/main/backend/src/config/db.js): `backend/src/config/db.js`

### Other components

- **User**

## Connections

- User → App router: uses
- App router → Home page: routes to (evidence: `frontend/src/routes/router.tsx`)
- App router → Notes page: routes to (evidence: `frontend/src/routes/router.tsx`)
- App router → Archive page: routes to (evidence: `frontend/src/routes/router.tsx`)
- App router → Route guard: guards app (evidence: `frontend/src/routes/router.tsx`)
- Notes page → Note state: uses (evidence: `frontend/src/pages/app/Notes.tsx`)
- Notes page → Note views: renders (evidence: `frontend/src/pages/app/Notes.tsx`)
- Note state → Note service: calls (evidence: `frontend/src/hooks/useNote.ts`)
- Note service → Note endpoints: requests
- Express server → Auth endpoints: mounts (evidence: `backend/src/app.js`)
- Express server → User endpoints: mounts (evidence: `backend/src/app.js`)
- Express server → Note endpoints: mounts (evidence: `backend/src/app.js`)
- Express server → Folder endpoints: mounts (evidence: `backend/src/app.js`)
- Express server → Tag endpoints: mounts (evidence: `backend/src/app.js`)
- Note endpoints → Token verification: verifies (evidence: `backend/src/routes/notes.routes.js`)
- Note endpoints → Note operations: dispatches (evidence: `backend/src/routes/notes.routes.js`)
- Tag endpoints → Token verification: verifies (evidence: `backend/src/routes/tags.routes.js`)
- Tag endpoints → Tag operations: dispatches (evidence: `backend/src/routes/tags.routes.js`)
- Folder endpoints → Token verification: verifies (evidence: `backend/src/routes/folders.routes.js`)
- Folder endpoints → Folder operations: dispatches (evidence: `backend/src/routes/folders.routes.js`)
- Auth endpoints → Auth controllers: dispatches (evidence: `backend/src/routes/auth.routes.js`)
- User endpoints → User operations: dispatches (evidence: `backend/src/routes/users.routes.js`)
- User endpoints → Token verification: verifies (evidence: `backend/src/routes/users.routes.js`)
- Token verification → PostgreSQL: checks users (evidence: `backend/src/middleware/authMiddleware.js`)
- Note operations → PostgreSQL: reads and writes (evidence: `backend/src/controllers/notes.controllers.js`)
- Tag operations → PostgreSQL: reads and writes (evidence: `backend/src/controllers/tags.controllers.js`)
- Folder operations → PostgreSQL: accesses (evidence: `backend/src/controllers/folders.controllers.js`)
- Auth controllers → PostgreSQL: accesses (evidence: `backend/src/controllers/auth.login.controllers.js`)
- User operations → PostgreSQL: accesses (evidence: `backend/src/controllers/users.controllers.js`)
- User → Login and register: authenticates
- Login and register → Auth hook: uses (evidence: `frontend/src/pages/auth/Login.tsx`)
- Login and register → Auth service: calls (evidence: `frontend/src/pages/auth/Login.tsx`)
- Auth hook → Auth context: reads (evidence: `frontend/src/hooks/useAuth.ts`)
- Auth context → Auth service: uses
- Route guard → Auth hook: checks session (evidence: `frontend/src/routes/ProtectedRoute.tsx`)
