# ravvys/booksnest architecture

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

- Interactive diagram: https://gitdiagram.com/ravvys/booksnest
- Repository: https://github.com/ravvys/booksnest

## Overview

Booksnest is a role-based learning platform for discovering books and educational materials, with author submissions and librarian moderation. Readers browse approved content, borrow books or join waitlists, and manage comments and bookmarks; authors submit and manage content; librarians review submissions and administer the catalog and users. The frontend’s API modules connect its role-specific pages to the Express API, whose controllers delegate business operations to application use cases and MongoDB-backed repositories. The README documents additional email notifications and external-book discovery; wiring beyond the sampled book search service is not inferred.

Main entry points: [`backend/src/interfaces/controllers`](https://github.com/ravvys/booksnest/tree/main/backend/src/interfaces/controllers) (Request controllers), [`backend/src/infrastructure/repositories`](https://github.com/ravvys/booksnest/tree/main/backend/src/infrastructure/repositories) (Repository implementations), [`backend/src/interfaces/routes`](https://github.com/ravvys/booksnest/tree/main/backend/src/interfaces/routes) (API routes), [`frontend/src/pages`](https://github.com/ravvys/booksnest/tree/main/frontend/src/pages) (Role-based pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web["Role-based pages"]
  node_webapp["App routes<br/>[App.jsx]"]
  node_authstate["Auth context<br/>[AuthContext.jsx]"]
  node_client["API client<br/>[apiClient.js]"]
  node_apis["Feature API modules"]
end

subgraph group_http["HTTP API"]
  node_express["Express application<br/>[app.js]"]
  node_routes["API routes"]
  node_middleware["Auth and role checks"]
  node_controllers["Request controllers"]
end

subgraph group_application["Application operations"]
  node_authops["Accounts and access"]
  node_catalogops["Books and categories"]
  node_materialops["Learning materials"]
  node_borrowops["Borrow and return"]
  node_queueops["Waitlist operations"]
  node_communityops["Reader interactions"]
  node_userops["Librarian user admin"]
end

subgraph group_persistence["Persistence"]
  node_repositories["Repository implementations"]
  node_mongo[("MongoDB models")]
end

subgraph group_integrations["External services"]
  node_search["Book search service"]
  node_google["Google Books API"]
  node_email["Email notifications<br/>[EmailService.js]"]
  node_smtp["Email provider"]
end

node_user(("Reader / Author / Librarian"))

node_user -->|"uses"| node_web
node_webapp -->|"routes to"| node_web
node_webapp -->|"provides auth"| node_authstate
node_web -->|"requests via"| node_apis
node_apis -->|"uses"| node_client
node_client -->|"calls API"| node_express
node_express -->|"mounts"| node_routes
node_routes -->|"protects"| node_middleware
node_routes -->|"dispatches"| node_controllers
node_controllers -->|"delegates"| node_authops
node_controllers -->|"delegates"| node_catalogops
node_controllers -->|"delegates"| node_materialops
node_controllers -->|"delegates"| node_borrowops
node_controllers -->|"delegates"| node_queueops
node_controllers -->|"delegates"| node_communityops
node_controllers -->|"delegates"| node_userops
node_authops -->|"uses"| node_repositories
node_catalogops -->|"uses"| node_repositories
node_materialops -->|"uses"| node_repositories
node_borrowops -->|"uses"| node_repositories
node_queueops -->|"uses"| node_repositories
node_communityops -->|"uses"| node_repositories
node_userops -->|"uses"| node_repositories
node_repositories -->|"reads and writes"| node_mongo
node_controllers -->|"invokes"| node_search
node_search -.->|"queries"| node_google
node_email -.->|"sends mail"| node_smtp

click node_web "https://github.com/ravvys/booksnest/tree/main/frontend/src/pages"
click node_webapp "https://github.com/ravvys/booksnest/blob/main/frontend/src/App.jsx"
click node_authstate "https://github.com/ravvys/booksnest/blob/main/frontend/src/context/AuthContext.jsx"
click node_client "https://github.com/ravvys/booksnest/blob/main/frontend/src/api/apiClient.js"
click node_apis "https://github.com/ravvys/booksnest/tree/main/frontend/src/api"
click node_express "https://github.com/ravvys/booksnest/blob/main/backend/src/app.js"
click node_routes "https://github.com/ravvys/booksnest/tree/main/backend/src/interfaces/routes"
click node_middleware "https://github.com/ravvys/booksnest/tree/main/backend/src/interfaces/middleware"
click node_controllers "https://github.com/ravvys/booksnest/tree/main/backend/src/interfaces/controllers"
click node_authops "https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/auth"
click node_catalogops "https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/book"
click node_materialops "https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/materials"
click node_borrowops "https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/borrow"
click node_queueops "https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/queue"
click node_communityops "https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases"
click node_userops "https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/users"
click node_repositories "https://github.com/ravvys/booksnest/tree/main/backend/src/infrastructure/repositories"
click node_mongo "https://github.com/ravvys/booksnest/tree/main/backend/src/infrastructure/database"
click node_search "https://github.com/ravvys/booksnest/blob/main/backend/src/infrastructure/services/BookSearchService.js"
click node_email "https://github.com/ravvys/booksnest/blob/main/backend/src/infrastructure/services/EmailService.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_web,node_webapp,node_authstate,node_client,node_apis toneBlue
class node_express,node_routes,node_middleware,node_controllers toneAmber
class node_authops,node_catalogops,node_materialops,node_borrowops,node_queueops,node_communityops,node_userops toneMint
class node_repositories,node_mongo toneRose
class node_search,node_google,node_email,node_smtp,node_user toneIndigo
```

## Components

### Web application

- [Role-based pages](https://github.com/ravvys/booksnest/tree/main/frontend/src/pages): `frontend/src/pages`
- [App routes](https://github.com/ravvys/booksnest/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth context](https://github.com/ravvys/booksnest/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/ravvys/booksnest/blob/main/frontend/src/api/apiClient.js): `frontend/src/api/apiClient.js`
- [Feature API modules](https://github.com/ravvys/booksnest/tree/main/frontend/src/api): `frontend/src/api`

### HTTP API

- [Express application](https://github.com/ravvys/booksnest/blob/main/backend/src/app.js): `backend/src/app.js`
- [API routes](https://github.com/ravvys/booksnest/tree/main/backend/src/interfaces/routes): `backend/src/interfaces/routes`
- [Auth and role checks](https://github.com/ravvys/booksnest/tree/main/backend/src/interfaces/middleware): `backend/src/interfaces/middleware`
- [Request controllers](https://github.com/ravvys/booksnest/tree/main/backend/src/interfaces/controllers): `backend/src/interfaces/controllers`

### Application operations

- [Accounts and access](https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/auth): `backend/src/application/usecases/auth`
- [Books and categories](https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/book): `backend/src/application/usecases/book`
- [Learning materials](https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/materials): `backend/src/application/usecases/materials`
- [Borrow and return](https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/borrow): `backend/src/application/usecases/borrow`
- [Waitlist operations](https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/queue): `backend/src/application/usecases/queue`
- [Reader interactions](https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases): `backend/src/application/usecases`
- [Librarian user admin](https://github.com/ravvys/booksnest/tree/main/backend/src/application/usecases/users): `backend/src/application/usecases/users`

### Persistence

- [Repository implementations](https://github.com/ravvys/booksnest/tree/main/backend/src/infrastructure/repositories): `backend/src/infrastructure/repositories`
- [MongoDB models](https://github.com/ravvys/booksnest/tree/main/backend/src/infrastructure/database): `backend/src/infrastructure/database`

### External services

- [Book search service](https://github.com/ravvys/booksnest/blob/main/backend/src/infrastructure/services/BookSearchService.js): `backend/src/infrastructure/services/BookSearchService.js`
- **Google Books API**
- [Email notifications](https://github.com/ravvys/booksnest/blob/main/backend/src/infrastructure/services/EmailService.js): `backend/src/infrastructure/services/EmailService.js`
- **Email provider**

### Other components

- **Reader / Author / Librarian**

## Connections

- Reader / Author / Librarian → Role-based pages: uses
- App routes → Role-based pages: routes to
- App routes → Auth context: provides auth
- Role-based pages → Feature API modules: requests via
- Feature API modules → API client: uses
- API client → Express application: calls API
- Express application → API routes: mounts
- API routes → Auth and role checks: protects
- API routes → Request controllers: dispatches
- Request controllers → Accounts and access: delegates
- Request controllers → Books and categories: delegates
- Request controllers → Learning materials: delegates
- Request controllers → Borrow and return: delegates
- Request controllers → Waitlist operations: delegates
- Request controllers → Reader interactions: delegates
- Request controllers → Librarian user admin: delegates
- Accounts and access → Repository implementations: uses
- Books and categories → Repository implementations: uses
- Learning materials → Repository implementations: uses
- Borrow and return → Repository implementations: uses
- Waitlist operations → Repository implementations: uses
- Reader interactions → Repository implementations: uses
- Librarian user admin → Repository implementations: uses
- Repository implementations → MongoDB models: reads and writes
- Request controllers → Book search service: invokes
- Book search service → Google Books API: queries
- Email notifications → Email provider: sends mail