# spviswanath/collaborative-story-builder architecture

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

- Interactive diagram: https://gitdiagram.com/spviswanath/collaborative-story-builder
- Repository: https://github.com/spviswanath/collaborative-story-builder

## Overview

StoryBuilder supports discovery and reading of both authored stories and Project Gutenberg books, plus authenticated story creation, collaboration, chapter editing, branching and PDF export. The documented external-book flow proxies raw text through the backend, then parses it in the browser into chapters. The graph follows the sampled route/controller and frontend call relationships; unsampled UI and integration internals are represented only where README or source-index evidence supports them.

Main entry points: [`backend/src/controllers/storyController.js`](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/controllers/storyController.js) (Story service), [`backend/src/routes/storyRoutes.js`](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/routes/storyRoutes.js) (Story routes), [`frontend/src/pages/Reader.jsx`](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/pages/Reader.jsx) (Reader), [`backend/src/app.js`](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/app.js) (HTTP application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_reader["Reader<br/>[Reader.jsx]"]
  node_catalog["Story discovery<br/>[Main.jsx]"]
  node_story_card["Story cards<br/>[StoryCard.jsx]"]
  node_editor["Story editor<br/>[Editor.jsx]"]
  node_chapter_ui["Chapter tools<br/>[ChapterSidebar.jsx]"]
  node_routes_ui["Page routing<br/>[AppRoutes.jsx]"]
  node_gutenberg_parser["Book parser<br/>[gutenbergParser.js]"]
end

subgraph group_story["Story workflows"]
  node_story_api["Story API<br/>[storyApi.js]"]
  node_story_routes["Story routes<br/>[storyRoutes.js]"]
  node_story_controller["Story service<br/>[storyController.js]"]
  node_stories[("Story records<br/>[Story.js]")]
  node_chapter_routes["Chapter routes<br/>[chapterRoutes.js]"]
  node_chapter_controller["Chapter service"]
  node_chapters[("Chapter records<br/>[Chapter.js]")]
  node_pdf["PDF export<br/>[pdfGenerator.js]"]
end

subgraph group_identity["Identity and accounts"]
  node_auth_context["Auth session<br/>[AuthContext.jsx]"]
  node_auth_api["Auth API<br/>[authApi.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_auth_controller["Auth service<br/>[authController.js]"]
  node_auth_middleware["JWT guard<br/>[authMiddleware.js]"]
  node_users[("User records<br/>[User.js]")]
end

subgraph group_platform["Backend platform"]
  node_cloudinary["Image hosting<br/>[cloudinary.js]"]
  node_app["HTTP application<br/>[app.js]"]
  node_server["Server startup<br/>[server.js]"]
  node_database_config["Database connection<br/>[db.js]"]
  node_socket["Live collaboration<br/>[socket.js]"]
end

node_gutenberg["Project Gutenberg"]
node_visitor(("Reader or author"))
node_mongo[("MongoDB")]

node_visitor -->|"browses"| node_catalog
node_catalog -->|"loads listings"| node_story_api
node_catalog -->|"renders"| node_story_card
node_visitor -->|"opens book"| node_reader
node_reader -.->|"requests story"| node_story_api
node_reader -->|"parses text"| node_gutenberg_parser
node_gutenberg_parser -->|"provides chapters"| node_reader
node_visitor -->|"creates stories"| node_editor
node_editor -.->|"uses editor tools"| node_chapter_ui
node_chapter_ui -->|"coordinates edits"| node_socket
node_routes_ui -->|"routes to"| node_reader
node_routes_ui -->|"routes to"| node_editor
node_auth_context -->|"authenticates with"| node_auth_api
node_auth_api -.->|"calls auth endpoints"| node_auth_routes
node_story_api -->|"calls story endpoints"| node_story_routes
node_story_routes -->|"dispatches"| node_story_controller
node_story_routes -->|"guards requests"| node_auth_middleware
node_story_controller -->|"reads and writes"| node_stories
node_story_controller -->|"reads chapters"| node_chapters
node_story_controller -->|"reads users"| node_users
node_story_controller -->|"generates export"| node_pdf
node_story_controller -->|"uses image service"| node_cloudinary
node_story_routes -->|"proxies book text"| node_gutenberg
node_chapter_routes -->|"dispatches"| node_chapter_controller
node_chapter_routes -->|"guards requests"| node_auth_middleware
node_chapter_controller -->|"reads and writes"| node_chapters
node_chapter_controller -->|"checks story access"| node_stories
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_routes -->|"guards session"| node_auth_middleware
node_auth_controller -->|"reads and writes"| node_users
node_auth_middleware -.->|"identifies request"| node_users
node_server -->|"starts"| node_app
node_server -->|"connects database"| node_database_config
node_server -->|"initializes"| node_socket
node_app -->|"mounts"| node_auth_routes
node_app -->|"mounts"| node_story_routes
node_app -->|"mounts"| node_chapter_routes
node_stories -.->|"persists in"| node_mongo
node_chapters -.->|"persists in"| node_mongo
node_users -.->|"persists in"| node_mongo

click node_reader "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/pages/Reader.jsx"
click node_catalog "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/pages/Main.jsx"
click node_story_card "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/components/story/StoryCard.jsx"
click node_editor "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/pages/Editor.jsx"
click node_chapter_ui "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/components/editor/ChapterSidebar.jsx"
click node_routes_ui "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/routes/AppRoutes.jsx"
click node_gutenberg_parser "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/utils/gutenbergParser.js"
click node_auth_context "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/context/AuthContext.jsx"
click node_auth_api "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/api/authApi.js"
click node_auth_routes "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/routes/authRoutes.js"
click node_auth_controller "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/controllers/authController.js"
click node_auth_middleware "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/middleware/authMiddleware.js"
click node_users "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/models/User.js"
click node_story_api "https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/api/storyApi.js"
click node_story_routes "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/routes/storyRoutes.js"
click node_story_controller "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/controllers/storyController.js"
click node_stories "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/models/Story.js"
click node_chapter_routes "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/routes/chapterRoutes.js"
click node_chapter_controller "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/controllers/chapterController.js"
click node_chapters "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/models/Chapter.js"
click node_pdf "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/utils/pdfGenerator.js"
click node_cloudinary "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/config/cloudinary.js"
click node_app "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/app.js"
click node_server "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/server.js"
click node_database_config "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/config/db.js"
click node_socket "https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/socket.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_reader,node_catalog,node_story_card,node_editor,node_chapter_ui,node_routes_ui,node_gutenberg_parser toneBlue
class node_story_api,node_story_routes,node_story_controller,node_stories,node_chapter_routes,node_chapter_controller,node_chapters,node_pdf,node_mongo toneAmber
class node_auth_context,node_auth_api,node_auth_routes,node_auth_controller,node_auth_middleware,node_users toneMint
class node_cloudinary,node_app,node_server,node_database_config,node_socket toneRose
class node_gutenberg,node_visitor toneIndigo
```

## Components

### Web experience

- [Reader](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/pages/Reader.jsx): `frontend/src/pages/Reader.jsx`
- [Story discovery](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/pages/Main.jsx): `frontend/src/pages/Main.jsx`
- [Story cards](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/components/story/StoryCard.jsx): `frontend/src/components/story/StoryCard.jsx`
- [Story editor](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/pages/Editor.jsx): `frontend/src/pages/Editor.jsx`
- [Chapter tools](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/components/editor/ChapterSidebar.jsx): `frontend/src/components/editor/ChapterSidebar.jsx`
- [Page routing](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/routes/AppRoutes.jsx): `frontend/src/routes/AppRoutes.jsx`
- [Book parser](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/utils/gutenbergParser.js): `frontend/src/utils/gutenbergParser.js`

### Story workflows

- [Story API](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/api/storyApi.js): `frontend/src/api/storyApi.js`
- [Story routes](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/routes/storyRoutes.js): `backend/src/routes/storyRoutes.js`
- [Story service](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/controllers/storyController.js): `backend/src/controllers/storyController.js`
- [Story records](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/models/Story.js): `backend/src/models/Story.js`
- [Chapter routes](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/routes/chapterRoutes.js): `backend/src/routes/chapterRoutes.js`
- [Chapter service](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/controllers/chapterController.js): `backend/src/controllers/chapterController.js`
- [Chapter records](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/models/Chapter.js): `backend/src/models/Chapter.js`
- [PDF export](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/utils/pdfGenerator.js): `backend/src/utils/pdfGenerator.js`

### Identity and accounts

- [Auth session](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Auth API](https://github.com/spviswanath/collaborative-story-builder/blob/main/frontend/src/api/authApi.js): `frontend/src/api/authApi.js`
- [Auth routes](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/routes/authRoutes.js): `backend/src/routes/authRoutes.js`
- [Auth service](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [JWT guard](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/middleware/authMiddleware.js): `backend/src/middleware/authMiddleware.js`
- [User records](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/models/User.js): `backend/src/models/User.js`

### Backend platform

- [Image hosting](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/config/cloudinary.js): `backend/src/config/cloudinary.js`
- [HTTP application](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/app.js): `backend/src/app.js`
- [Server startup](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/server.js): `backend/src/server.js`
- [Database connection](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/config/db.js): `backend/src/config/db.js`
- [Live collaboration](https://github.com/spviswanath/collaborative-story-builder/blob/main/backend/src/socket.js): `backend/src/socket.js`

### Other components

- **Project Gutenberg**
- **Reader or author**
- **MongoDB**

## Connections

- Reader or author → Story discovery: browses (evidence: `README.md`)
- Story discovery → Story API: loads listings (evidence: `frontend/src/pages/Main.jsx`)
- Story discovery → Story cards: renders (evidence: `frontend/src/pages/Main.jsx`)
- Reader or author → Reader: opens book (evidence: `README.md`)
- Reader → Story API: requests story
- Reader → Book parser: parses text (evidence: `README.md`)
- Book parser → Reader: provides chapters (evidence: `README.md`)
- Reader or author → Story editor: creates stories (evidence: `README.md`)
- Story editor → Chapter tools: uses editor tools
- Chapter tools → Live collaboration: coordinates edits (evidence: `frontend/src/components/editor/ChapterSidebar.jsx`)
- Page routing → Reader: routes to (evidence: `frontend/src/routes/AppRoutes.jsx`)
- Page routing → Story editor: routes to (evidence: `frontend/src/routes/AppRoutes.jsx`)
- Auth session → Auth API: authenticates with (evidence: `frontend/src/context/AuthContext.jsx`)
- Auth API → Auth routes: calls auth endpoints
- Story API → Story routes: calls story endpoints (evidence: `README.md`)
- Story routes → Story service: dispatches (evidence: `backend/src/routes/storyRoutes.js`)
- Story routes → JWT guard: guards requests (evidence: `backend/src/routes/storyRoutes.js`)
- Story service → Story records: reads and writes (evidence: `backend/src/controllers/storyController.js`)
- Story service → Chapter records: reads chapters (evidence: `backend/src/controllers/storyController.js`)
- Story service → User records: reads users (evidence: `backend/src/controllers/storyController.js`)
- Story service → PDF export: generates export (evidence: `backend/src/controllers/storyController.js`)
- Story service → Image hosting: uses image service (evidence: `backend/src/controllers/storyController.js`)
- Story routes → Project Gutenberg: proxies book text (evidence: `README.md`)
- Chapter routes → Chapter service: dispatches (evidence: `backend/src/routes/chapterRoutes.js`)
- Chapter routes → JWT guard: guards requests (evidence: `backend/src/routes/chapterRoutes.js`)
- Chapter service → Chapter records: reads and writes (evidence: `backend/src/controllers/chapterController.js`)
- Chapter service → Story records: checks story access (evidence: `backend/src/controllers/chapterController.js`)
- Auth routes → Auth service: dispatches (evidence: `backend/src/routes/authRoutes.js`)
- Auth routes → JWT guard: guards session (evidence: `backend/src/routes/authRoutes.js`)
- Auth service → User records: reads and writes (evidence: `backend/src/controllers/authController.js`)
- JWT guard → User records: identifies request
- Server startup → HTTP application: starts (evidence: `backend/src/server.js`)
- Server startup → Database connection: connects database (evidence: `backend/src/server.js`)
- Server startup → Live collaboration: initializes (evidence: `backend/src/server.js`)
- HTTP application → Auth routes: mounts (evidence: `backend/src/app.js`)
- HTTP application → Story routes: mounts (evidence: `backend/src/app.js`)
- HTTP application → Chapter routes: mounts (evidence: `backend/src/app.js`)
- Story records → MongoDB: persists in
- Chapter records → MongoDB: persists in
- User records → MongoDB: persists in
