Vasuki Publication

Production-grade public web publishing and reading platform for books generated by VasukiSquare.

Overview

Vasuki Publication is the official public web application for browsing, searching, discovering, and reading digital books generated by the VasukiSquare authoring engine.

Unlike traditional publishing websites that force users to download static PDF files or use sluggish PDF viewers, Vasuki Publication is built with a Zero-PDF Architecture. All books, covers, chapter structures, individual pages, page styles, layout metadata, structured content blocks, and native advertisements are consumed directly from a canonical MongoDB database.

┌─────────────────────────────────────────────────────────────┐
│                        VasukiSquare                         │
│   (LLM Research Engine • Layout Planner • Book Generator)   │
└──────────────────────────────┬──────────────────────────────┘
                               │ Persists structured documents
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                      MongoDB Database                       │
│    Collections: books • pages • covers • ads                │
└──────────────────────────────┬──────────────────────────────┘
                               │ Reads public published content
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                      VasukiPublication                      │
│   (Next.js App Router • React Server Components • Reader)   │
│                                                             │
│  ┌───────────────┐     ┌───────────────┐   ┌─────────────┐  │
│  │   Discovery   │     │    Reader     │   │    Admin    │  │
│  │  Home • Search│     │  DOM Pages    │   │  Dashboard  │  │
│  │  Ads • Covers │     │  Zero Ads     │   │  CRUD • SEO │  │
│  └───────────────┘     └───────────────┘   └─────────────┘  │
└─────────────────────────────────────────────────────────────┘

Key Features

Official Brand Identity & Vector Scenery:
- Transparent blackish vector logo (public/Vasuki.png) integrated across website chrome (navbar header, footer), cover previews, reader toolbar, metadata icons, and dynamic OpenGraph social banners.
- Direct navbar link to the official engine repository: https://github.com/UltronTheAI/VasukiSquare.
Zero-PDF Native Web Reader (/book/[slug]/read):
- Reconstructs publications directly from structured MongoDB page blocks into responsive, pixel-accurate A4 DOM pages (1:1.414 aspect ratio).
- Linked-list page progression, progressive prefetching, full keyboard navigation (left/right arrow keys), and spread view mode ($\ge 1280\text{px}$).
- Enforces streamlined single-page view on mobile/tablet viewports ($< 1280\text{px}$) with comfortable aspect-ratio margins and scrollbar padding.
- Simplified, distraction-free Table of Contents with direct chapter jump links, active chapter glow tracking, and single-line page counters.
- Zero Ads Rule: Advertisements are strictly prohibited inside the book reader container.
Public Book Discovery & Catalog (/):
- URL-driven search (?q=...) and pagination (?page=...).
- Featured publication showcase supporting up to 5 pinned books with corner-flush bottom palettes.
- Responsive book cards with dynamic cover previews, synopses, author attribution, and reading times.
Book Detail Experience (/book/[slug]):
- Complete chapter hierarchy, table of contents, and topic metadata.
- Schema.org/Book JSON-LD structured data and dynamic edge-rendered OpenGraph previews (/book/[slug]/opengraph-image).
Anonymous Browser-Local Saved Books (/saved):
- Hydration-safe client-side reading queue using localStorage (vasuki.savedBooks.v1) and React 19 useSyncExternalStore.
- Multi-tab synchronization without reader registration, database user accounts, or server-side tracking.
- High-performance batch resolution endpoint (/api/books/batch).
Private Administrative Portal (/admin):
- Protected single-administrator authentication using constant-time token validation (crypto.timingSafeEqual) and signed HMAC-SHA256 session cookies.
- Brute-force rate limiting and Origin/Host CSRF verification.
- Overview dashboard, publications directory, hero pin ranking editor (1..5), live cover design customizer with instant preview, and safe cascade deletion requiring title confirmation.
Native Advertisements Model (/admin/ads):
- Restrained native sponsor cards in website discovery spaces (home_banner, home_sidebar, saved_banner, saved_sidebar).
- Priority-weighted rotation (P1: 10, P2: 5, P3: 2), safe outbound confirmation modals, and anonymous impression/click counters.
Production SEO & Comprehensive OpenGraph Coverage:
- Dynamic OpenGraph (1200x630) and Twitter image cards across all platform routes (/, /book/[slug], /book/[slug]/read, /saved, /terms, /privacy).
- Native browser favicon and mobile touch icons referencing /Vasuki.png.
- Dynamic sitemap (/sitemap.xml) and robots exclusion rules (/robots.txt).
- Production security headers: Content-Security-Policy, HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy.
- Legal compliance pages for Privacy Policy (/privacy) and Terms of Service (/terms).

Tech Stack

Framework: Next.js 16 (App Router)
UI Runtime: React 19
Language: TypeScript
Database: MongoDB Node.js Driver
Styling: Tailwind CSS v4
Icons: Lucide React
Validation: Zod

Architecture & Design Invariants

Design System Isolation:
- The Website Shell strictly follows DESIGN.md (dark/light contrast, monochrome with brand accents).
- The Book Reader follows lib/vasuki/render-tokens.ts (isolated VasukiSquare publication tokens).
Zero PDF Dependency:
- Books and covers are rendered natively from MongoDB documents. No PDF parsing, upload, or runtime dependency exists.
Strict Ad Boundary:
- Advertisements appear exclusively in website discovery spaces and are never rendered inside the book reader.
Server-Only Data Access:
- Client components cannot query MongoDB directly. All data access occurs through Server Components and lib/repositories/*.
Single-Operator Security:
- Zero public user accounts. Administrative access is restricted to the operator holding ADMIN_ACCESS_TOKEN.

Route Overview

Route	Type	Description
`/`	Server Component	Public homepage, hero search, pinned books, book catalog, native ads
`/book/[slug]`	Server Component	Book detail page, synopsis, chapter outline, JSON-LD data
`/book/[slug]/opengraph-image`	Dynamic OG Image	1200x630 dynamic social preview card generator
`/book/[slug]/read`	Client/Server Reader	Interactive A4 reader, keyboard navigation, zero ads
`/saved`	Client/Server Hybrid	Browser-local saved reading list with batch API resolution
`/privacy`	Server Component	Transparency & privacy policy
`/terms`	Server Component	Terms of service for public platform usage
`/admin`	Server Component	Private administrative dashboard and operational metrics
`/admin/login`	Client/Server Hybrid	Single-administrator login portal with brute-force rate limiter
`/admin/books`	Server Component	Publications directory with search, filters, and quick pinning
`/admin/books/[id]`	Client/Server Hybrid	Publication editor, live cover visualizer, safe cascade delete
`/admin/ads`	Client/Server Hybrid	Native ads campaign management, metrics, and live component preview
`/sitemap.xml`	Dynamic Metadata	Search engine sitemap indexing public publications
`/robots.txt`	Dynamic Metadata	Crawler directives protecting admin and internal endpoints
`/api/books/batch`	API Route Handler	Batch resolution endpoint for saved book slugs
`/api/books/[slug]/pages`	API Route Handler	Paginated page streaming endpoint for reader prefetching

Getting Started

Prerequisites

Node.js 20.x or higher
MongoDB instance (local instance or MongoDB Atlas cluster)

1. Installation

git clone https://github.com/UltronTheAI/VasukiPublication.git
cd vasukipublication
npm install

2. Environment Setup

Copy .env.example to .env.local:

cp .env.example .env.local

Configure your environment variables in .env.local:

MONGODB_URI=mongodb://127.0.0.1:27017
MONGODB_DATABASE=vasukisquare
ADMIN_ACCESS_TOKEN=vasuki_local_development_admin_token
ADMIN_SESSION_SECRET=vasuki_local_development_session_secret_32chars
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_SITE_NAME=Vasuki Publication
NODE_ENV=development

3. Run Development Server

npm run dev

Open http://localhost:3000 to view the application.

Available Scripts

Script	Command	Description
`dev`	`npm run dev`	Runs Next.js development server with hot reload
`build`	`npm run build`	Compiles production bundle with strict TypeScript verification
`start`	`npm run start`	Runs production server locally
`lint`	`npm run lint`	Runs ESLint analysis across the codebase
`test`	`npm test`	Runs Node.js test runner across all test suites

Project Structure

vasukipublication/
├── app/                    # Next.js App Router (pages, layouts, metadata, routes)
│   ├── admin/              # Private administration portal
│   ├── api/                # API route handlers (batch, pages)
│   ├── book/[slug]/        # Book detail, reader, and OpenGraph routes
│   ├── privacy/            # Privacy policy page
│   ├── terms/              # Terms of service page
│   ├── saved/              # Saved books page
│   ├── sitemap.ts          # Dynamic sitemap generator
│   └── robots.ts           # Dynamic robots manifest
├── components/
│   ├── admin/              # Admin dashboard, forms, table, and editors
│   ├── ads/                # Native advertisement components and modals
│   ├── book/               # Book cards, grid, pinned showcase, save button
│   ├── cover/              # Dynamic SVG/HTML cover renderer
│   ├── discovery/          # Search bar, pagination, filters
│   ├── layout/             # Site header, footer, navigation
│   ├── reader/             # Isolated A4 book reader and page renderer
│   └── saved/              # Saved books view
├── docs/                   # System & architecture documentation
│   ├── admin.md            # Admin portal architecture & security
│   ├── ads.md              # Native ads model & analytics
│   ├── architecture.md     # System relationships and routing overview
│   ├── book-rendering.md   # Zero-PDF rendering model and theme isolation
│   ├── deployment.md       # Production checklist and Vercel setup
│   ├── development.md      # Development workflow and scripts
│   ├── mongodb.md          # Collections, schemas, and indexing guidelines
│   ├── security.md         # Threat model, secrets, and sanitization
│   └── seo.md              # Canonicalization, sitemap, and OpenGraph
├── lib/
│   ├── db/                 # MongoDB client, connections, and collections
│   ├── env.ts              # Zod environment variable validation
│   ├── hooks/              # Reusable React hooks (useSavedBooks)
│   ├── repositories/       # Server-only repository data-access layer
│   ├── security/           # Admin auth, URL validation, crypto, HTML sanitization
│   ├── types/              # Publication, Book, Page, and Cover TypeScript models
│   ├── utils/              # General utilities (cn helper)
│   └── vasuki/             # VasukiSquare compatibility layer and tokens
├── tests/                  # Automated test suites
├── AGENTS.md               # AI coding assistant guidelines
├── DESIGN.md               # Master website UI design specification
├── LICENSE                 # VasukiSquare Commercial Source License v1.0
├── README.md               # Project overview and technical documentation
└── TEST.md                 # Quality assurance & testing strategy

Documentation Index

License & Commercial Terms

This project is source-available and governed by the VASUKISQUARE COMMERCIAL SOURCE LICENSE Version 1.0. See the LICENSE file for complete commercial terms and redistribution restrictions.

Navigation Menu

Repository navigation

About

Repository files navigation

Vasuki Publication

Overview

Key Features

Tech Stack

Architecture & Design Invariants

Route Overview

Getting Started

Prerequisites

1. Installation

2. Environment Setup

3. Run Development Server

Available Scripts

Project Structure

Documentation Index

License & Commercial Terms

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
app		app
components		components
docs		docs
lib		lib
public		public
styles		styles
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
DESIGN.md		DESIGN.md
LICENSE		LICENSE
README.md		README.md
TEST.md		TEST.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Vasuki Publication

Overview

Key Features

Tech Stack

Architecture & Design Invariants

Route Overview

Getting Started

Prerequisites

1. Installation

2. Environment Setup

3. Run Development Server

Available Scripts

Project Structure

Documentation Index

License & Commercial Terms

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages