# realstin/booksstore architecture

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

- Interactive diagram: https://gitdiagram.com/realstin/booksstore
- Repository: https://github.com/realstin/booksstore

## Overview

This is a BookStore backend API for a digital-book library and its reader community. Clients enter through the Express server, which mounts feature routes; route handlers authenticate or authorize requests, apply domain operations, and return API results. The major workflows cover accounts, book discovery and PDF delivery, bookmarks and notes, plus editorial content, teams, statistics, and newsletter subscriptions. Persistence is modeled with Mongoose; book/article publishing can trigger subscriber email. The tree and excerpts establish these boundaries, but several controllers and route implementations were not sampled, so their internal links are conservative.

Main entry points: [`server.js`](https://github.com/realstin/booksstore/blob/main/server.js) (Express server), [`middleware/authenticate.js`](https://github.com/realstin/booksstore/blob/main/middleware/authenticate.js) (JWT authentication), [`middleware/requireAdmin.js`](https://github.com/realstin/booksstore/blob/main/middleware/requireAdmin.js) (Admin guard), [`routes/adminUsers.js`](https://github.com/realstin/booksstore/blob/main/routes/adminUsers.js) (User administration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_server["Express server<br/>[server.js]"]
  node_auth_routes["Auth routes<br/>[auth.js]"]
  node_auth_controller["Account auth<br/>[authController.js]"]
  node_auth_middleware["JWT authentication<br/>[authenticate.js]"]
  node_admin_middleware["Admin guard<br/>[requireAdmin.js]"]
  node_user_routes["User administration<br/>[adminUsers.js]"]
  node_admin_users["Admin user operations"]
  node_user_model[("User records<br/>[User.js]")]
end

subgraph group_library["Reading library"]
  node_book_routes["Book routes<br/>[books.js]"]
  node_book_controller["Book catalog and PDF<br/>[bookController.js]"]
  node_book_model[("Book records<br/>[Book.js]")]
  node_book_cache["Book cache<br/>[bookCache.js]"]
  node_library_controller["Reader library"]
end

subgraph group_community["Reader community"]
  node_bookmark_routes["Bookmark routes<br/>[bookmarks.js]"]
  node_bookmark_controller["Bookmark operations"]
  node_bookmark_model[("Bookmarks<br/>[Bookmark.js]")]
  node_note_routes["Note routes<br/>[notes.js]"]
  node_note_controller["Reader notes<br/>[noteController.js]"]
  node_note_model[("Notes<br/>[Note.js]")]
end

subgraph group_content["Content and engagement"]
  node_article_routes["Article routes<br/>[articles.js]"]
  node_article_controller["Article publishing"]
  node_article_model[("Articles<br/>[Article.js]")]
  node_team_routes["Team routes<br/>[team.js]"]
  node_team_controller["Team operations<br/>[teamController.js]"]
  node_team_model[("Team records<br/>[Team.js]")]
  node_stats_routes["Statistics routes<br/>[stats.js]"]
  node_stats_controller["Statistics<br/>[statsController.js]"]
end

subgraph group_messaging["Subscriber messaging"]
  node_newsletter_routes["Newsletter routes<br/>[newsletter.js]"]
  node_newsletter_controller["Subscriptions"]
  node_subscriber_model[("Subscribers<br/>[Subscriber.js]")]
  node_notify["Subscriber notifications"]
  node_mailer["SMTP mailer<br/>[mailer.js]"]
end

node_clients(("API clients"))
node_smtp(("Gmail SMTP"))

node_clients -->|"send requests"| node_server
node_server -->|"mounts auth"| node_auth_routes
node_server -->|"mounts books"| node_book_routes
node_server -->|"mounts admin users"| node_user_routes
node_server -->|"mounts bookmarks"| node_bookmark_routes
node_server -->|"mounts notes"| node_note_routes
node_server -->|"mounts articles"| node_article_routes
node_server -->|"mounts team"| node_team_routes
node_server -->|"mounts statistics"| node_stats_routes
node_server -->|"mounts newsletter"| node_newsletter_routes
node_auth_routes -->|"dispatches auth"| node_auth_controller
node_auth_routes -->|"protects session"| node_auth_middleware
node_auth_controller -->|"uses subscriber records"| node_subscriber_model
node_auth_middleware -.->|"provides user context"| node_admin_middleware
node_auth_middleware -->|"loads account"| node_user_model
node_user_routes -->|"protects admin routes"| node_auth_middleware
node_user_routes -->|"guards admin routes"| node_admin_middleware
node_user_routes -->|"dispatches operations"| node_admin_users
node_book_routes -->|"protects operations"| node_auth_middleware
node_book_routes -->|"guards changes"| node_admin_middleware
node_book_routes -->|"dispatches catalog"| node_book_controller
node_book_controller -->|"queries books"| node_book_model
node_book_controller -->|"reads and clears"| node_book_cache
node_book_controller -->|"notifies new books"| node_notify
node_library_controller -->|"queries books"| node_book_model
node_library_controller -->|"uses cached books"| node_book_cache
node_library_controller -->|"updates reader"| node_user_model
node_bookmark_routes -->|"protects routes"| node_auth_middleware
node_bookmark_routes -->|"dispatches actions"| node_bookmark_controller
node_bookmark_controller -->|"queries bookmarks"| node_bookmark_model
node_bookmark_controller -->|"updates book counts"| node_book_model
node_note_routes -->|"protects routes"| node_auth_middleware
node_note_routes -->|"dispatches actions"| node_note_controller
node_note_controller -->|"creates and queries"| node_note_model
node_note_controller -->|"checks book existence"| node_book_model
node_article_routes -->|"protects edits"| node_auth_middleware
node_article_routes -->|"guards publishing"| node_admin_middleware
node_article_routes -->|"dispatches articles"| node_article_controller
node_article_controller -->|"queries articles"| node_article_model
node_article_controller -->|"notifies publication"| node_notify
node_team_routes -->|"protects edits"| node_auth_middleware
node_team_routes -->|"guards changes"| node_admin_middleware
node_team_routes -->|"dispatches team"| node_team_controller
node_team_controller -->|"queries team"| node_team_model
node_stats_routes -.->|"dispatches statistics"| node_stats_controller
node_newsletter_routes -->|"protects admin actions"| node_auth_middleware
node_newsletter_routes -->|"guards admin actions"| node_admin_middleware
node_newsletter_routes -->|"dispatches subscriptions"| node_newsletter_controller

click node_server "https://github.com/realstin/booksstore/blob/main/server.js"
click node_auth_routes "https://github.com/realstin/booksstore/blob/main/routes/auth.js"
click node_auth_controller "https://github.com/realstin/booksstore/blob/main/controllers/authController.js"
click node_auth_middleware "https://github.com/realstin/booksstore/blob/main/middleware/authenticate.js"
click node_admin_middleware "https://github.com/realstin/booksstore/blob/main/middleware/requireAdmin.js"
click node_user_routes "https://github.com/realstin/booksstore/blob/main/routes/adminUsers.js"
click node_admin_users "https://github.com/realstin/booksstore/blob/main/controllers/adminUserController.js"
click node_user_model "https://github.com/realstin/booksstore/blob/main/models/User.js"
click node_book_routes "https://github.com/realstin/booksstore/blob/main/routes/books.js"
click node_book_controller "https://github.com/realstin/booksstore/blob/main/controllers/bookController.js"
click node_book_model "https://github.com/realstin/booksstore/blob/main/models/Book.js"
click node_book_cache "https://github.com/realstin/booksstore/blob/main/utils/bookCache.js"
click node_library_controller "https://github.com/realstin/booksstore/blob/main/controllers/libraryController.js"
click node_bookmark_routes "https://github.com/realstin/booksstore/blob/main/routes/bookmarks.js"
click node_bookmark_controller "https://github.com/realstin/booksstore/blob/main/controllers/bookmarkController.js"
click node_bookmark_model "https://github.com/realstin/booksstore/blob/main/models/Bookmark.js"
click node_note_routes "https://github.com/realstin/booksstore/blob/main/routes/notes.js"
click node_note_controller "https://github.com/realstin/booksstore/blob/main/controllers/noteController.js"
click node_note_model "https://github.com/realstin/booksstore/blob/main/models/Note.js"
click node_article_routes "https://github.com/realstin/booksstore/blob/main/routes/articles.js"
click node_article_controller "https://github.com/realstin/booksstore/blob/main/controllers/articleController.js"
click node_article_model "https://github.com/realstin/booksstore/blob/main/models/Article.js"
click node_team_routes "https://github.com/realstin/booksstore/blob/main/routes/team.js"
click node_team_controller "https://github.com/realstin/booksstore/blob/main/controllers/teamController.js"
click node_team_model "https://github.com/realstin/booksstore/blob/main/models/Team.js"
click node_stats_routes "https://github.com/realstin/booksstore/blob/main/routes/stats.js"
click node_stats_controller "https://github.com/realstin/booksstore/blob/main/controllers/statsController.js"
click node_newsletter_routes "https://github.com/realstin/booksstore/blob/main/routes/newsletter.js"
click node_newsletter_controller "https://github.com/realstin/booksstore/blob/main/controllers/newsletterController.js"
click node_subscriber_model "https://github.com/realstin/booksstore/blob/main/models/Subscriber.js"
click node_notify "https://github.com/realstin/booksstore/blob/main/utils/notifySubscribers.js"
click node_mailer "https://github.com/realstin/booksstore/blob/main/utils/mailer.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_server,node_auth_routes,node_auth_controller,node_auth_middleware,node_admin_middleware,node_user_routes,node_admin_users,node_user_model,node_clients toneBlue
class node_book_routes,node_book_controller,node_book_model,node_book_cache,node_library_controller toneAmber
class node_bookmark_routes,node_bookmark_controller,node_bookmark_model,node_note_routes,node_note_controller,node_note_model toneMint
class node_article_routes,node_article_controller,node_article_model,node_team_routes,node_team_controller,node_team_model,node_stats_routes,node_stats_controller toneRose
class node_newsletter_routes,node_newsletter_controller,node_subscriber_model,node_notify,node_mailer,node_smtp toneIndigo
```

## Components

### API and access

- [Express server](https://github.com/realstin/booksstore/blob/main/server.js): `server.js`
- [Auth routes](https://github.com/realstin/booksstore/blob/main/routes/auth.js): `routes/auth.js`
- [Account auth](https://github.com/realstin/booksstore/blob/main/controllers/authController.js): `controllers/authController.js`
- [JWT authentication](https://github.com/realstin/booksstore/blob/main/middleware/authenticate.js): `middleware/authenticate.js`
- [Admin guard](https://github.com/realstin/booksstore/blob/main/middleware/requireAdmin.js): `middleware/requireAdmin.js`
- [User administration](https://github.com/realstin/booksstore/blob/main/routes/adminUsers.js): `routes/adminUsers.js`
- [Admin user operations](https://github.com/realstin/booksstore/blob/main/controllers/adminUserController.js): `controllers/adminUserController.js`
- [User records](https://github.com/realstin/booksstore/blob/main/models/User.js): `models/User.js`

### Reading library

- [Book routes](https://github.com/realstin/booksstore/blob/main/routes/books.js): `routes/books.js`
- [Book catalog and PDF](https://github.com/realstin/booksstore/blob/main/controllers/bookController.js): `controllers/bookController.js`
- [Book records](https://github.com/realstin/booksstore/blob/main/models/Book.js): `models/Book.js`
- [Book cache](https://github.com/realstin/booksstore/blob/main/utils/bookCache.js): `utils/bookCache.js`
- [Reader library](https://github.com/realstin/booksstore/blob/main/controllers/libraryController.js): `controllers/libraryController.js`

### Reader community

- [Bookmark routes](https://github.com/realstin/booksstore/blob/main/routes/bookmarks.js): `routes/bookmarks.js`
- [Bookmark operations](https://github.com/realstin/booksstore/blob/main/controllers/bookmarkController.js): `controllers/bookmarkController.js`
- [Bookmarks](https://github.com/realstin/booksstore/blob/main/models/Bookmark.js): `models/Bookmark.js`
- [Note routes](https://github.com/realstin/booksstore/blob/main/routes/notes.js): `routes/notes.js`
- [Reader notes](https://github.com/realstin/booksstore/blob/main/controllers/noteController.js): `controllers/noteController.js`
- [Notes](https://github.com/realstin/booksstore/blob/main/models/Note.js): `models/Note.js`

### Content and engagement

- [Article routes](https://github.com/realstin/booksstore/blob/main/routes/articles.js): `routes/articles.js`
- [Article publishing](https://github.com/realstin/booksstore/blob/main/controllers/articleController.js): `controllers/articleController.js`
- [Articles](https://github.com/realstin/booksstore/blob/main/models/Article.js): `models/Article.js`
- [Team routes](https://github.com/realstin/booksstore/blob/main/routes/team.js): `routes/team.js`
- [Team operations](https://github.com/realstin/booksstore/blob/main/controllers/teamController.js): `controllers/teamController.js`
- [Team records](https://github.com/realstin/booksstore/blob/main/models/Team.js): `models/Team.js`
- [Statistics routes](https://github.com/realstin/booksstore/blob/main/routes/stats.js): `routes/stats.js`
- [Statistics](https://github.com/realstin/booksstore/blob/main/controllers/statsController.js): `controllers/statsController.js`

### Subscriber messaging

- [Newsletter routes](https://github.com/realstin/booksstore/blob/main/routes/newsletter.js): `routes/newsletter.js`
- [Subscriptions](https://github.com/realstin/booksstore/blob/main/controllers/newsletterController.js): `controllers/newsletterController.js`
- [Subscribers](https://github.com/realstin/booksstore/blob/main/models/Subscriber.js): `models/Subscriber.js`
- [Subscriber notifications](https://github.com/realstin/booksstore/blob/main/utils/notifySubscribers.js): `utils/notifySubscribers.js`
- [SMTP mailer](https://github.com/realstin/booksstore/blob/main/utils/mailer.js): `utils/mailer.js`

### Other components

- **API clients**
- **Gmail SMTP**

## Connections

- API clients → Express server: send requests (evidence: `server.js`)
- Express server → Auth routes: mounts auth (evidence: `server.js`)
- Express server → Book routes: mounts books (evidence: `server.js`)
- Express server → User administration: mounts admin users (evidence: `server.js`)
- Express server → Bookmark routes: mounts bookmarks (evidence: `server.js`)
- Express server → Note routes: mounts notes (evidence: `server.js`)
- Express server → Article routes: mounts articles (evidence: `server.js`)
- Express server → Team routes: mounts team (evidence: `server.js`)
- Express server → Statistics routes: mounts statistics (evidence: `server.js`)
- Express server → Newsletter routes: mounts newsletter (evidence: `server.js`)
- Auth routes → Account auth: dispatches auth (evidence: `routes/auth.js`)
- Auth routes → JWT authentication: protects session (evidence: `routes/auth.js`)
- Account auth → Subscribers: uses subscriber records (evidence: `controllers/authController.js`)
- JWT authentication → Admin guard: provides user context
- JWT authentication → User records: loads account (evidence: `middleware/authenticate.js`)
- User administration → JWT authentication: protects admin routes (evidence: `routes/adminUsers.js`)
- User administration → Admin guard: guards admin routes (evidence: `routes/adminUsers.js`)
- User administration → Admin user operations: dispatches operations (evidence: `routes/adminUsers.js`)
- Book routes → JWT authentication: protects operations (evidence: `routes/books.js`)
- Book routes → Admin guard: guards changes (evidence: `routes/books.js`)
- Book routes → Book catalog and PDF: dispatches catalog (evidence: `routes/books.js`)
- Book catalog and PDF → Book records: queries books (evidence: `controllers/bookController.js`)
- Book catalog and PDF → Book cache: reads and clears (evidence: `controllers/bookController.js`)
- Book catalog and PDF → Subscriber notifications: notifies new books (evidence: `controllers/bookController.js`)
- Reader library → Book records: queries books (evidence: `controllers/libraryController.js`)
- Reader library → Book cache: uses cached books (evidence: `controllers/libraryController.js`)
- Reader library → User records: updates reader (evidence: `controllers/libraryController.js`)
- Bookmark routes → JWT authentication: protects routes (evidence: `routes/bookmarks.js`)
- Bookmark routes → Bookmark operations: dispatches actions (evidence: `routes/bookmarks.js`)
- Bookmark operations → Bookmarks: queries bookmarks (evidence: `controllers/bookmarkController.js`)
- Bookmark operations → Book records: updates book counts (evidence: `controllers/bookmarkController.js`)
- Note routes → JWT authentication: protects routes (evidence: `routes/notes.js`)
- Note routes → Reader notes: dispatches actions (evidence: `routes/notes.js`)
- Reader notes → Notes: creates and queries (evidence: `controllers/noteController.js`)
- Reader notes → Book records: checks book existence (evidence: `controllers/noteController.js`)
- Article routes → JWT authentication: protects edits (evidence: `routes/articles.js`)
- Article routes → Admin guard: guards publishing (evidence: `routes/articles.js`)
- Article routes → Article publishing: dispatches articles (evidence: `routes/articles.js`)
- Article publishing → Articles: queries articles (evidence: `controllers/articleController.js`)
- Article publishing → Subscriber notifications: notifies publication (evidence: `controllers/articleController.js`)
- Team routes → JWT authentication: protects edits (evidence: `routes/team.js`)
- Team routes → Admin guard: guards changes (evidence: `routes/team.js`)
- Team routes → Team operations: dispatches team (evidence: `routes/team.js`)
- Team operations → Team records: queries team (evidence: `controllers/teamController.js`)
- Statistics routes → Statistics: dispatches statistics
- Newsletter routes → JWT authentication: protects admin actions (evidence: `routes/newsletter.js`)
- Newsletter routes → Admin guard: guards admin actions (evidence: `routes/newsletter.js`)
- Newsletter routes → Subscriptions: dispatches subscriptions (evidence: `routes/newsletter.js`)
