# jobin-s/vayana architecture

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

- Interactive diagram: https://gitdiagram.com/jobin-s/vayana
- Repository: https://github.com/jobin-s/vayana

## Overview

**Vayana** is a **full-stack Next.js (App Router) web application** for **personal library management** with:
- **UI pages** (dashboard, add/edit book, login/register)
- **API routes** under `src/app/api/**` (auth + books CRUD)
- **MongoDB via Mongoose** models (`src/models/*`)
- **JWT auth (JOSE) stored in HTTP-only cookies**
- **Client state** via **Zustand** (`src/store/useBookStore.ts`)
- **Middleware** for request-time access control (`src/middleware.js`)

- a **server runtime** (Route Handlers, Server Actions, Middleware)
- a **client runtime** (React components + Zustand store)
- a **database** (MongoDB)
- auth token flow (JWT cookie creation/validation)

##### Top level
- `src/app/**`: **App Router**: pages, layouts, route handlers (API), server actions
- `src/components/**`: reusable UI components (pure client/view layer)
- `src/lib/**`:
- `db.js`: MongoDB connection logic (shared server utility)
- `auth.js`: JWT creation/verification helpers (server utility)
- `src/models/**`: Mongoose schemas (`Book.js`, `User.js`)
- `src/store/**`: Zustand store used by the client for UI state
- `src/middleware.js`: edge/server middleware intercepting requests (auth gate)

##### UI routes (pages)
- `src/app/page.tsx`: landing/root
- `src/app/login/page.tsx`, `src/app/register/page.tsx`: auth screens
- `src/app/(main)/dashboard/page.tsx`: main dashboard (list/search/filter)
- `src/app/(main)/add-book/*`: add book UI + `action.ts` (server action)
- `src/app/(main)/edit-book/[id]/page.tsx`: edit book UI

##### API routes (server endpoints)
- `src/app/api/auth/login/route.js`
- `src/app/api/auth/logout/route.js`
- `src/app/api/auth/register/route.js`
- `src/app/api/books/route.js` (collection: list/create)
- `src/app/api/books/[id]/route.js` (single book: read/update/delete)

These should appear as a **REST-ish API layer** inside the Next.js server boundary.

##### What to include as “main components”
For this project, break it into **as many components as possible** while keeping it readable:

##### Client / Browser layer
- **Next.js React UI**
- Pages: Login, Register, Dashboard, Add Book, Edit Book
- Components: `Header`, `Navbar`, `Footer`, `BookCard`, `BookList`
- **Zustand store** (`useBookStore.ts`)
- Holds client-side state: book list, filters/search term, optimistic updates (if used)

##### Next.js Server layer (same app, different concerns)
- **Route Handlers (API)** under `/api/**`
- Auth API: login/register/logout
- Books API: CRUD
- **Server Actions**
- `src/app/(main)/add-book/action.ts` (server-side mutations invoked from UI)
- **Middleware**
- `src/middleware.js` (auth enforcement / redirects / protecting `(main)` routes)

##### Data / Persistence layer
- **MongoDB**
- **Mongoose Models**
- `User` and `Book` schemas
- **DB connection utility**
- `src/lib/db.js`

- **JOSE JWT**
- **HTTP-only cookie**
- `src/lib/auth.js` for sign/verify helpers
- `JWT_SECRET` and `MONGODB_URI` from `.env.local`

##### Route Handler
- connect db
- `User` model lookup + password verify (implementation detail)
- `auth.js` signs JWT
- sets **HTTP-only cookie**

##### Flow 3: Auth gate (middleware)
- Browser → request to `/dashboard`, `/add-book`, `/edit-book/...`
- **`middleware.js`**:
- reads cookie
- verifies JWT via `auth.js`
- allow → continue to page
- deny → redirect to `/login`

##### Flow 5: Create book (Add Book)
- **Server Action path**:
1. Book page → calls `action.ts` (server action)
2. Server action → db → `Book` model create → returns result
- **API path** (if used elsewhere):
1. Browser → POST `/api/books`
2. Route Handler → db → create book

##### Flow 6: Update/Delete book (Edit Book)
- Browser → PATCH/PUT/DELETE `/api/books/[id]` (or server action if used)
- Handler/action → db → `Book` model update/delete
- Response → client updates Zustand store and UI

**Client/UI**
- `src/app/login/page.tsx`
- `src/app/register/page.tsx`
- `src/app/(main)/dashboard/page.tsx`
- `src/app/(main)/add-book/page.tsx` + `add-book-form.tsx`
- `src/app/(main)/edit-book/[id]/page.tsx`
- `src/components/{BookCard,BookList,Header,Navbar,Footer}.tsx`
- `src/store/useBookStore.ts`

**Server**
- `src/middleware.js`
- `src/app/api/auth/{login,logout,register}/route.js`
- `src/app/api/books/route.js`
- `src/app/api/books/[id]/route.js`
- `src/app/(main)/add-book/action.ts`

**Domain/Data**
- `src/lib/db.js`
- `src/models/User.js`
- `src/models/Book.js`
- `src/lib/auth.js`
- MongoDB

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram A — System Context (C4 L1)
%% =========================
subgraph "Diagram A — System Context (C4 L1)"
direction TB

U["User"]:::external
B["Browser (HTTPS Client)"]:::external

subgraph "Vayana — Next.js App (Single Deployable System)"
direction TB
NX["Next.js App (App Router)"]:::server
end

subgraph "Data Boundary"
direction TB
MDB[("MongoDB")]:::db
end

B <-->|"HTTPS_requests/responses"| NX
NX <-->|"Mongoose_driver"| MDB
U -->|"uses"| B
end

%% =========================
%% Diagram B — Container / Runtime Split (C4 L2-ish)
%% =========================
subgraph "Diagram B — Container / Runtime Split"
direction TB

subgraph "Trust Boundary: Browser"
direction TB
BR["Browser Runtime"]:::external

subgraph "Client Runtime (React)"
direction TB
AR["App Router Pages"]:::client
P_ROOT["Landing '/' (page.tsx)"]:::client
P_LOGIN["Login Page"]:::client
P_REGISTER["Register Page"]:::client

subgraph "Protected '(main)' Pages"
direction TB
P_DASH["Dashboard Page"]:::client
P_ADD["Add Book Page"]:::client
C_ADD_FORM["Add Book Form (client UI)"]:::client
P_EDIT["Edit Book Page '/edit-book/[id]'"]:::client
end

subgraph "Reusable UI Components"
direction TB
C_HEADER["Header"]:::client
C_NAV["Navbar"]:::client
C_FOOT["Footer"]:::client
C_LIST["BookList"]:::client
C_CARD["BookCard"]:::client
end

Z_STORE["Zustand Store (useBookStore)"]:::client
end

JWT_COOKIE["HTTP-only Cookie (JWT)"]:::auth
end

subgraph "Trust Boundary: Next.js Server Runtime"
direction TB

LAYOUTS["Layouts & Route Groups"]:::server
L_GLOBAL["Global Layout"]:::server
L_MAIN["'(main)' Layout (protected)"]:::server

MW["Middleware (Auth Gate)"]:::server

subgraph "Route Handlers (REST-ish API) under /api/**"
direction TB
subgraph "Auth API"
direction TB
API_LOGIN["POST /api/auth/login"]:::api
API_REGISTER["POST /api/auth/register"]:::api
API_LOGOUT["POST /api/auth/logout"]:::api
end

subgraph "Books API"
direction TB
API_BOOKS["/api/books (GET,POST)"]:::api
API_BOOK_ID["/api/books/[id] (GET,PUT/PATCH,DELETE)"]:::api
end
end

subgraph "Server Actions"
direction TB
SA_ADD["Server Action: Add Book"]:::action
end

subgraph "Shared Server Utilities"
direction TB
AUTH_UTIL["auth.js (JWT sign/verify via JOSE)"]:::auth
DB_UTIL["db.js (MongoDB connection)"]:::data
end

subgraph "Domain Models (Mongoose)"
direction TB
M_USER["User Model"]:::data
M_BOOK["Book Model"]:::data
end

ENV[".env.local: JWT_SECRET, MONGODB_URI"]:::config
end

subgraph "Trust Boundary: Database"
direction TB
DB_MONGO[("MongoDB")]:::db
end

%% --- Client composition / rendering ---
AR -->|"renders"| P_ROOT
AR -->|"renders"| P_LOGIN
AR -->|"renders"| P_REGISTER
AR -->|"renders"| P_DASH
AR -->|"renders"| P_ADD
AR -->|"renders"| P_EDIT

P_DASH -->|"uses"| C_LIST
C_LIST -->|"renders"| C_CARD
P_DASH -->|"uses"| C_HEADER
P_DASH -->|"uses"| C_NAV
P_DASH -->|"uses"| C_FOOT
P_ADD -->|"uses"| C_ADD_FORM

P_DASH -->|"reads/writes"| Z_STORE
P_ADD -->|"updates"| Z_STORE
P_EDIT -->|"updates"| Z_STORE

%% --- Auth cookie flow ---
API_LOGIN -->|"sets"| JWT_COOKIE
BR -->|"sends_cookie"| MW

%% --- Middleware gating (pages & API) ---
BR -->|"request_/dashboard"| MW
BR -->|"request_/add-book"| MW
BR -->|"request_/edit-book/[id]"| MW
MW -->|"verify_JWT"| AUTH_UTIL
MW -->|"allow_or_redirect_/login"| AR

BR -->|"request_/api/books"| MW
BR -->|"request_/api/books/[id]"| MW
BR -->|"request_/api/auth/*"| MW

%% --- API + Server Action interactions ---
P_REGISTER -->|"POST_fetch"| API_REGISTER
P_LOGIN -->|"POST_fetch"| API_LOGIN
P_DASH -->|"GET_fetch"| API_BOOKS
P_EDIT -->|"PUT/PATCH/DELETE_fetch"| API_BOOK_ID
P_ADD -->|"POST_fetch"| API_BOOKS

C_ADD_FORM -->|"invoke"| SA_ADD

%% --- Server-side dependencies ---
API_LOGIN -.->|"imports"| AUTH_UTIL
API_REGISTER -.->|"imports"| DB_UTIL
API_LOGOUT -.->|"imports"| AUTH_UTIL

API_BOOKS -.->|"imports"| DB_UTIL
API_BOOK_ID -.->|"imports"| DB_UTIL
SA_ADD -.->|"imports"| DB_UTIL

DB_UTIL -.->|"uses"| M_USER
DB_UTIL -.->|"uses"| M_BOOK

API_REGISTER -->|"create_user"| M_USER
API_LOGIN -->|"lookup_user"| M_USER

API_BOOKS -->|"query/create"| M_BOOK
API_BOOK_ID -->|"read/update/delete"| M_BOOK
SA_ADD -->|"create"| M_BOOK

DB_UTIL -->|"connect"| DB_MONGO

%% --- Env/config feeding utilities ---
ENV -->|"JWT_SECRET"| AUTH_UTIL
ENV -->|"MONGODB_URI"| DB_UTIL

%% --- Dashboard data back to UI ---
API_BOOKS -->|"JSON_response"| Z_STORE
Z_STORE -->|"state"| C_LIST
end

%% =========================
%% Diagram C — Key Sequences (Auth + CRUD)
%% =========================
subgraph "Diagram C — Key Sequences"
direction TB

subgraph "Sequence 1: Login (JWT issuance)"
direction TB
S1_BR["Browser: Login Page"]:::external
S1_API["POST /api/auth/login"]:::api
S1_AUTH["auth.js (sign JWT)"]:::auth
S1_DB["db.js (connect)"]:::data
S1_USER["User Model"]:::data
S1_COOKIE["HTTP-only Cookie (JWT)"]:::auth

S1_BR -->|"credentials"| S1_API
S1_API -->|"connect"| S1_DB
S1_DB -->|"lookup"| S1_USER
S1_API -->|"sign"| S1_AUTH
S1_API -->|"set_cookie"| S1_COOKIE
S1_API -->|"response"| S1_BR
end

subgraph "Sequence 2: Open Dashboard (Middleware gate + Books fetch)"
direction TB
S2_BR["Browser: /dashboard request"]:::external
S2_MW["middleware.js (auth gate)"]:::server
S2_AUTH["auth.js (verify JWT)"]:::auth
S2_PAGE["Dashboard Page"]:::client
S2_API["GET /api/books"]:::api
S2_DB["db.js (connect)"]:::data
S2_BOOK["Book Model"]:::data
S2_STORE["Zustand (useBookStore)"]:::client
S2_UI["BookList/BookCard render"]:::client

S2_BR -->|"request_with_cookie"| S2_MW
S2_MW -->|"verify"| S2_AUTH
S2_MW -->|"allow"| S2_PAGE
S2_PAGE -->|"fetch"| S2_API
S2_API -->|"connect"| S2_DB
S2_DB -->|"query"| S2_BOOK
S2_API -->|"JSON"| S2_STORE
S2_STORE -->|"state"| S2_UI
end

subgraph "Sequence 3: Add Book (Server Action path)"
direction TB
S3_BR["Browser: Add Book Form submit"]:::external
S3_SA["Server Action: add-book/action.ts"]:::action
S3_DB["db.js (connect)"]:::data
S3_BOOK["Book Model"]:::data
S3_STORE["Zustand (useBookStore)"]:::client

S3_BR -->|"invoke_action"| S3_SA
S3_SA -->|"connect"| S3_DB
S3_DB -->|"create"| S3_BOOK
S3_SA -->|"result"| S3_BR
S3_BR -->|"update_ui_state"| S3_STORE
end

end

%% =========================
%% Click Events (from component_mapping)
%% =========================
click AR "https://github.com/jobin-s/vayana/tree/main/src/app/"
click P_ROOT "https://github.com/jobin-s/vayana/blob/main/src/app/page.tsx"
click L_GLOBAL "https://github.com/jobin-s/vayana/blob/main/src/app/layout.tsx"
click L_MAIN "https://github.com/jobin-s/vayana/blob/main/src/app/(main)/layout.tsx"

click P_LOGIN "https://github.com/jobin-s/vayana/blob/main/src/app/login/page.tsx"
click P_REGISTER "https://github.com/jobin-s/vayana/blob/main/src/app/register/page.tsx"
click P_DASH "https://github.com/jobin-s/vayana/blob/main/src/app/(main)/dashboard/page.tsx"
click P_ADD "https://github.com/jobin-s/vayana/blob/main/src/app/(main)/add-book/page.tsx"
click C_ADD_FORM "https://github.com/jobin-s/vayana/blob/main/src/app/(main)/add-book/add-book-form.tsx"
click P_EDIT "https://github.com/jobin-s/vayana/blob/main/src/app/(main)/edit-book/[id]/page.tsx"

click C_HEADER "https://github.com/jobin-s/vayana/blob/main/src/components/Header.tsx"
click C_NAV "https://github.com/jobin-s/vayana/blob/main/src/components/Navbar.tsx"
click C_FOOT "https://github.com/jobin-s/vayana/blob/main/src/components/Footer.tsx"
click C_CARD "https://github.com/jobin-s/vayana/blob/main/src/components/BookCard.tsx"
click C_LIST "https://github.com/jobin-s/vayana/blob/main/src/components/BookList.tsx"
click Z_STORE "https://github.com/jobin-s/vayana/blob/main/src/store/useBookStore.ts"

click MW "https://github.com/jobin-s/vayana/blob/main/src/middleware.js"

click API_LOGIN "https://github.com/jobin-s/vayana/blob/main/src/app/api/auth/login/route.js"
click API_LOGOUT "https://github.com/jobin-s/vayana/blob/main/src/app/api/auth/logout/route.js"
click API_REGISTER "https://github.com/jobin-s/vayana/blob/main/src/app/api/auth/register/route.js"

click API_BOOKS "https://github.com/jobin-s/vayana/blob/main/src/app/api/books/route.js"
click API_BOOK_ID "https://github.com/jobin-s/vayana/blob/main/src/app/api/books/[id]/route.js"

click SA_ADD "https://github.com/jobin-s/vayana/blob/main/src/app/(main)/add-book/action.ts"

click DB_UTIL "https://github.com/jobin-s/vayana/blob/main/src/lib/db.js"
click AUTH_UTIL "https://github.com/jobin-s/vayana/blob/main/src/lib/auth.js"

click M_BOOK "https://github.com/jobin-s/vayana/blob/main/src/models/Book.js"
click M_USER "https://github.com/jobin-s/vayana/blob/main/src/models/User.js"

%% =========================
%% Styles
%% =========================
classDef external fill:#E6F0FF,stroke:#2B5FD9,stroke-width:2px,color:#0B1B3A;
classDef client fill:#D9ECFF,stroke:#1C6DD0,stroke-width:2px,color:#0B1B3A;
classDef server fill:#FFE8CC,stroke:#D97706,stroke-width:2px,color:#3A2200;
classDef api fill:#FFD7A8,stroke:#C2410C,stroke-width:2px,color:#3A2200;
classDef action fill:#FFC78A,stroke:#B45309,stroke-width:2px,color:#3A2200;
classDef data fill:#DFF7E5,stroke:#16A34A,stroke-width:2px,color:#05240F;
classDef db fill:#CFF5D8,stroke:#15803D,stroke-width:2px,color:#05240F;
classDef auth fill:#EAD9FF,stroke:#7C3AED,stroke-width:2px,color:#1F103A;
classDef config fill:#E5E7EB,stroke:#374151,stroke-width:2px,color:#111827;
```
