# vanshika114/ch.aptered architecture

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

- Interactive diagram: https://gitdiagram.com/vanshika114/ch.aptered
- Repository: https://github.com/vanshika114/ch.aptered

## Overview

1. **Repository shape**
   - The repo is split into two top-level application areas:
     - `chaptered-web`: the actual working client application
     - `chaptered-api`: a backend package that currently looks like a scaffold/placeholder
   - The root `README.md` describes the product vision and planned stack, but the implemented code is still early-stage.

2. **Current runtime model**
   - The frontend is a **React + TypeScript + Vite** app running in the browser.
   - The backend is a **Node.js/TypeScript** package, but from the tree alone it appears to have only a minimal entry file and no visible feature modules yet.
   - So the current architecture is mostly **client-side**, with persistence likely happening locally rather than through an API.

3. **Frontend composition**
   - `chaptered-web/src/main.tsx` is the browser entry point.
   - `App.tsx` is the top-level application shell.
   - The app is organized into pages:
     - `pages/Landing.tsx` for the public marketing/entry experience
     - `pages/Library.tsx` for the core reading/library workspace
   - The presence of separate CSS files (`landing.css`, `library.css`, plus global styles) suggests page-scoped UI concerns rather than a large shared component system yet.

4. **State and data ownership**
   - `src/store/useLibraryStore.ts` indicates the frontend uses **Zustand** for client state.
   - This store is the likely source of truth for reading-library data in the current implementation.
   - Because there is also a `src/lib/storage.ts`, the store likely persists or hydrates data from browser storage instead of calling a remote backend.

5. **Domain logic boundary**
   - `src/lib/bookUtils.ts` suggests shared book-related transformation or formatting logic lives outside the UI layer.
   - That file is the likely boundary for normalizing book data, computing derived values, or adapting external book records into the app’s internal shape.
   - `storage.ts` is the other important non-UI boundary: it likely encapsulates browser persistence concerns so pages and stores don’t talk directly to storage APIs.

6. **UI/data flow in the frontend**
   - User interaction starts in the page components.
   - Page components read/write state through the Zustand store.
   - The store likely uses `bookUtils` for derived book logic and `storage.ts` for persistence.
   - The rendered output is therefore driven by a simple flow: **user action → store update → persisted local state → UI re-render**.

7. **Backend status and boundary**
   - `chaptered-api/src/index.ts` exists, but the tree does not show routes, controllers, services, database models, or realtime modules.
   - This means the backend boundary is present as a separate package, but its architecture has not been built out yet.
   - For an architecture diagram, it should be shown as a **planned service layer** rather than a live dependency of the frontend right now.

8. **Planned external integrations from the README**
   - The README names the future backend ecosystem:
     - Google Books API for search
     - MongoDB/Mongoose for persistence
     - JWT for authentication
     - Socket.io for realtime club chat
   - None of those integrations are visible in the current file tree, so they should be treated as roadmap components, not current runtime dependencies.

9. **Product boundaries implied by the codebase**
   - The current codebase only exposes the early reading/library side of the product.
   - The larger Chaptered vision in the README includes clubs, chat, voting, analytics, and authentication, but those are not yet represented in the repository structure.
   - In other words, the repo currently reflects a **single-user library tracker shell**, not the full social platform.

10. **Infrastructure and tooling**
   - Frontend build tooling is **Vite**, with TypeScript config split for app and node environments.
   - Both packages use npm lockfiles, so npm is the package manager in practice.
   - ESLint is configured in the web app, indicating code-quality enforcement is already part of the frontend workflow.

11. **How to draw the architecture accurately**
   - Show the browser app as the primary implemented system.
   - Inside it, place:
     - top-level app shell
     - landing page
     - library page
     - Zustand library store
     - helper modules for storage and book logic
   - Show the backend as a separate but mostly empty service boundary.
   - Show external services from the README as **future integrations** connected to the backend, not to the current frontend directly.

12. **Bottom line**
   - This repository is at an early stage: the **frontend prototype exists**, the **backend is just a scaffold**, and the **core architecture is local-state-driven UI with browser persistence**.
   - The key design boundary today is between **presentation/pages** and **shared state + persistence helpers** in the web app.

Main entry points: [`chaptered-api/src/index.ts`](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-api/src/index.ts) (API entry), [`chaptered-web/src/main.tsx`](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/main.tsx) (Main entry), [`chaptered-web/src/App.tsx`](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/App.tsx) (App shell), [`chaptered-web/src/store/useLibraryStore.ts`](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/store/useLibraryStore.ts) (Library store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["chaptered-web"]
  node_web_main(("Main entry<br/>browser entry<br/>[main.tsx]"))
  node_web_app["App shell<br/>react shell<br/>[App.tsx]"]
  node_web_landing["Landing page<br/>[Landing.tsx]"]
  node_web_library["Library page<br/>[Library.tsx]"]
  node_web_store[("Library store<br/>zustand store<br/>[useLibraryStore.ts]")]
  node_web_storage[("Storage<br/>browser persistence<br/>[storage.ts]")]
  node_web_books["Book utils<br/>domain helpers<br/>[bookUtils.ts]"]
  node_web_styles["Styles"]
  node_web_vite{{"Vite build<br/>tooling<br/>[vite.config.ts]"}}
  node_web_eslint{{"Linting<br/>tooling<br/>[eslint.config.js]"}}
end

subgraph group_api["chaptered-api"]
  node_api_index(("API entry<br/>node entry<br/>[index.ts]"))
end

subgraph group_future["Future integrations"]
  node_google_books{{"Google Books<br/>external api"}}
  node_mongodb[("MongoDB<br/>database")]
  node_jwt{{"JWT auth"}}
  node_socketio["Socket.io<br/>realtime"]
end

node_root_readme["README<br/>vision<br/>[README.md]"]

node_root_readme -->|"describes"| node_web_main
node_root_readme -->|"describes"| node_api_index
node_web_main -->|"mounts"| node_web_app
node_web_app -->|"routes to"| node_web_landing
node_web_app -->|"routes to"| node_web_library
node_web_library -->|"reads/writes"| node_web_store
node_web_landing -->|"reads"| node_web_store
node_web_store -->|"persists"| node_web_storage
node_web_store -->|"derives"| node_web_books
node_web_landing -->|"styles"| node_web_styles
node_web_library -->|"styles"| node_web_styles
node_web_app -->|"styles"| node_web_styles
node_web_main -->|"built by"| node_web_vite
node_web_main -->|"checked by"| node_web_eslint
node_api_index -.->|"planned"| node_google_books
node_api_index -.->|"planned"| node_mongodb
node_api_index -.->|"planned"| node_jwt
node_api_index -.->|"planned"| node_socketio

click node_root_readme "https://github.com/vanshika114/ch.aptered/blob/main/README.md"
click node_web_main "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/main.tsx"
click node_web_app "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/App.tsx"
click node_web_landing "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/pages/Landing.tsx"
click node_web_library "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/pages/Library.tsx"
click node_web_store "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/store/useLibraryStore.ts"
click node_web_storage "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/lib/storage.ts"
click node_web_books "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/lib/bookUtils.ts"
click node_web_vite "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/vite.config.ts"
click node_web_eslint "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/eslint.config.js"
click node_api_index "https://github.com/vanshika114/ch.aptered/blob/main/chaptered-api/src/index.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_web_main,node_web_app,node_web_landing,node_web_library,node_web_store,node_web_storage,node_web_books,node_web_styles,node_web_vite,node_web_eslint toneBlue
class node_api_index toneAmber
class node_google_books,node_mongodb,node_jwt,node_socketio toneMint
class node_root_readme toneNeutral
```

## Components

### chaptered-web

Implemented browser app and local state-driven reading workspace

- [Main entry](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/main.tsx): browser entry · Bootstraps the React app · `chaptered-web/src/main.tsx`
- [App shell](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/App.tsx): react shell · Top-level application composition · `chaptered-web/src/App.tsx`
- [Landing page](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/pages/Landing.tsx): page · Public entry and marketing view · `chaptered-web/src/pages/Landing.tsx`
- [Library page](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/pages/Library.tsx): page · Core reading and library workspace · `chaptered-web/src/pages/Library.tsx`
- [Library store](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/store/useLibraryStore.ts): zustand store · Client-side source of truth for library state · `chaptered-web/src/store/useLibraryStore.ts`
- [Storage](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/lib/storage.ts): browser persistence · Encapsulates local persistence and hydration · `chaptered-web/src/lib/storage.ts`
- [Book utils](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/src/lib/bookUtils.ts): domain helpers · Book normalization and derived logic · `chaptered-web/src/lib/bookUtils.ts`
- **Styles**: ui styles · Global and page-scoped styling layer
- [Vite build](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/vite.config.ts): tooling · Frontend dev server and build pipeline · `chaptered-web/vite.config.ts`
- [Linting](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-web/eslint.config.js): tooling · Frontend code-quality configuration · `chaptered-web/eslint.config.js`

### chaptered-api

Backend package scaffolded as a separate service boundary

- [API entry](https://github.com/vanshika114/ch.aptered/blob/main/chaptered-api/src/index.ts): node entry · Minimal backend scaffold with no visible feature modules · `chaptered-api/src/index.ts`

### Future integrations

Planned services described in the README but not yet present in the tree

- **Google Books**: external api · Planned book search integration
- **MongoDB**: database · Planned server-side persistence
- **JWT auth**: auth · Planned authentication layer
- **Socket.io**: realtime · Planned club chat and realtime messaging

### Other components

- [README](https://github.com/vanshika114/ch.aptered/blob/main/README.md): vision · Product vision and planned architecture · `README.md`

## Connections

- README → Main entry: describes · Vision maps to the implemented browser app
- README → API entry: describes · Vision also includes a backend package boundary
- Main entry → App shell: mounts · Browser entry renders the app shell
- App shell → Landing page: routes to · App shell includes the public landing experience
- App shell → Library page: routes to · App shell includes the core library workspace
- Library page → Library store: reads/writes · Workspace state flows through the Zustand store
- Landing page → Library store: reads · Landing can reflect shared app state
- Library store → Storage: persists · Store hydrates and saves local state
- Library store → Book utils: derives · Store uses book helpers for normalization and computed values
- Landing page → Styles: styles · Page-scoped UI styling
- Library page → Styles: styles · Page-scoped UI styling
- App shell → Styles: styles · Shared application styling
- Main entry → Vite build: built by · Frontend is served and bundled with Vite
- Main entry → Linting: checked by · Frontend linting and code-quality workflow
- API entry → Google Books: planned · Future search integration exposed through backend
- API entry → MongoDB: planned · Future persistent storage layer
- API entry → JWT auth: planned · Future authentication boundary
- API entry → Socket.io: planned · Future realtime chat and club features