A reading and intellectual-growth platform designed around meaningful conversations, reflection, lifelong learning, and intimate community rather than passive, algorithmic, superficial content consumption.
Modern digital media platforms are engineered to optimize for virality, impulsive engagement, and ad revenue. This creates severe structural pathologies:
- Superficial Skimming & Doomscrolling: Content algorithms prioritize outrage, short-form ephemera, and rapid dopamine loops, reducing attention spans and eroding deep cognitive focus.
- Commoditized Book Discovery: Mainstream book platforms treat literature like retail inventory, relying on crude genre tags and bestseller rankings rather than evaluating ideas, philosophical resonance, or personal transformation.
- Polarized & Toxic Forums: Discussion spaces reward antagonism, flame wars, and superficial hot takes where "winning" the debate takes precedence over genuine intellectual comprehension.
- Isolated Reading Without Accountability: Readers frequently read books in isolation without structured opportunities to synthesize insights, debate nuance, or maintain private, meaningful reflections.
Paradize addresses this breakdown by offering an intellectual sanctuary: small, tight-knit reading cohorts (5–20 readers), AI-assisted reflection, and evidence-based discussions that reward depth over vanity metrics.
Every technical and architectural decision in Paradize is guided by four core tenets:
- Curiosity Over Certainty: The best readers ask searching questions rather than merely collecting answers.
- Respect Over Agreement: Disagree with ideas rigorously, but always respect individuals.
- Growth Over Ego: Celebrate the humility and courage of changing one's mind in the face of evidence.
- Understanding Over Winning: Discourse is conducted for shared comprehension, not competitive victory.
- Active Readers & Lifelong Learners: Individuals seeking substantive literary engagement, reflective synthesis, and intellectual growth rather than superficial page-count tracking.
- Reading Circles & Cohorts: Groups of 5–20 participants who require shared reading schedules, structured accountability, and focused discussion spaces free from forum noise.
- Reflective Thinkers & Journalers: Writers and thinkers who desire a private, secure journal with AI-generated introspective prompts that connect literary themes directly to real-life decisions.
- Multilingual Readers: Global readers who can participate seamlessly across 6 supported languages (English, Hindi, Spanish, French, German, and Bengali).
Paradize is built on a modern Next.js 16 full-stack architecture with strict server/client separation, runtime validation, and server-side authorization:
[ User Interaction / Next.js 16 Frontend (React 19) ]
│
▼
[ Route Guards: Next.js Proxy Middleware (src/proxy.ts) ]
│
▼
[ Input Sanitization & Validation: isomorphic-dompurify + Zod 4 ]
│
▼
[ Next.js API Handlers & Better Auth Session Authorization ]
│
┌───────────────┴───────────────┐
▼ ▼
[ External Intelligence Layer ] [ Data Layer ]
- Google Gemini 2.0 Flash - Drizzle ORM (Type-Safe SQL)
- HuggingFace Toxicity API - Neon Serverless PostgreSQL
- Google Books & Open Library - Strict Multi-Tenant Scoping
- User Intent & Navigation: The user initiates an action (e.g. creating a group, logging a private reflection, contributing to a discussion).
- Proxy Route Guarding:
src/proxy.tsinspects session tokens via Better Auth. Unauthenticated requests to protected zones (/dashboard,/journal,/groups,/library) are redirected to/login. - Zero-Trust Validation & Sanitization:
- Inbound JSON payloads are validated against strict Zod schemas (
createDiscussionSchema,createReflectionSchema,createGroupSchema,updateProfileSchema). - Rich text and HTML are sanitized via
DOMPurify.sanitize()before persistence, eliminating stored Cross-Site Scripting (XSS).
- Inbound JSON payloads are validated against strict Zod schemas (
- Session Authorization & Multi-Tenant Scoping: All mutations strictly extract
session.user.idfrom the verified session rather than accepting client-supplied author identifiers, eliminating IDOR and impersonation vulnerabilities. - Intelligence & Enrichment: Contextual book recommendations and reflection prompts are generated via Google Gemini 2.0 Flash with regex JSON extraction and deterministic fallback safeguards.
- Persistence: Drizzle ORM executes type-safe queries against Neon Serverless PostgreSQL.
Paradize integrates both external metadata catalogs and proprietary application datasets:
| Dataset / Source | Purpose | Data Type | Measurable Scope | Important Fields / Attributes | Privacy Considerations |
|---|---|---|---|---|---|
| Google Books Volumes API | Book discovery, synopsis retrieval, author attribution, published dates | REST JSON | Billions of indexed volumes queried dynamically | id, volumeInfo.title, volumeInfo.authors, volumeInfo.description, volumeInfo.imageLinks |
Public catalog metadata; no user PII transmitted |
| Open Library API | Fallback high-resolution cover retrieval | Image / CDN assets | Dynamic ISBN lookup | ISBN-10, ISBN-13, cover URL | Public catalog assets; no user PII |
| User Library & Reading State | Tracking reading states, personal ratings, and reading milestones | Relational PostgreSQL | Scalable per-user records | userId, bookId, status (want_to_read, reading, completed, abandoned), progress, rating |
Private to user; sensitive behavioral reading telemetry |
| Discussions & Threaded Discourse | Public and cohort-level intellectual exchanges | Relational PostgreSQL | Community-generated threads and replies | id, authorId, bookId, groupId, type, title, content, upvotes |
Public to platform or cohort members; author-attributed |
| Private Reflection Journal | Introspective synthesis connecting literature to personal life | Relational PostgreSQL | User-scoped reflections | id, userId, bookId, content, mood, createdAt |
Strictly confidential; isolated by server-enforced session identity |
| Reading Cohorts (5–20 Members) | Structured small-group reading circles with capacity caps | Relational PostgreSQL | Cohort rosters and discussion threads | id, name, description, currentBookId, creatorId, maxMembers (5–20), meetingSchedule |
Cohort-scoped visibility; bounded membership |
| AI Contextual Prompts | Ephemeral prompts for book recommendations and reflection questions | Ephemeral JSON | Per-request generation | goal, interests, recentBooks, title, author |
Zero user PII, passwords, or emails transmitted |
Unlike mass-market social networks where discussions devolve into chaotic comment threads, Paradize explicitly enforces small cohort sizes:
- Group capacity is bound between 5 and 20 members at both schema validation and database insertion layers.
- Cohort members share reading deadlines, discussion threads, and meeting schedules to foster real accountability and camaraderie.
- Contextual Book Recommendations: Integrates Google Gemini 2.0 Flash to analyze reader growth goals (e.g. "cultivating stoic resilience", "understanding cognitive biases") and recommend philosophically aligned books with explanatory rationales.
- Regex JSON Extraction: LLM responses frequently contain Markdown code fences or introductory conversational filler. Paradize implements
extractJsonFromResponseusing robust multi-pattern regular expressions to cleanly parse structured data. - Fail-Safe Fallbacks: All AI endpoints feature strict 8-second abort timeouts (
AbortSignal.timeout(8000)). If an API quota is exhausted or a network timeout occurs, Paradize immediately delivers curated, high-value philosophical recommendations and reflection prompts rather than surfacing UI errors. - Toxicity & Sentiment Moderation: Employs HuggingFace toxicity scoring and rule-based sentiment checks to guide discussions toward respectful, constructive dialogue.
- Zero-Trust Session Authentication: Server-side session verification via Better Auth (
getServerSession(auth)) on all modifying endpoints (POST,PATCH,DELETE). - Complete IDOR Remediation: User IDs from client request bodies are completely ignored; mutations strictly operate on the verified session subject.
- Input Sanitization: All user-authored content (discussions, replies, reflections, profile bios) is sanitized through
DOMPurify.sanitize()prior to storage. - UUID & Non-UUID Interception: Book ID routes safely handle both standard UUIDs and alphanumeric Google Books identifiers (e.g.
zyTCAlFPjgYC), preventing database driver crashes.
- Native support for 6 global languages: English (
en), Hindi (hi), Spanish (es), French (fr), German (de), and Bengali (bn). - Uses React 19
useSyncExternalStoreinLanguageContextfor instant, tear-free language switching with automaticlocalStoragepersistence and fallback resolution.
| Category | Target / Requirement | Verified Codebase Measurement | Status |
|---|---|---|---|
| Automated Test Suite | Comprehensive unit & security coverage | 40 / 40 passing (100%) across 14 test suites in Node 24 native test runner | ✅ PASSED |
| Security Test Matrix | IDOR, impersonation, XSS, injection | 10 / 10 formal security test cases passing (SEC-01 through SEC-10) | ✅ PASSED |
| TypeScript Compilation | Strict zero-error compilation | 0 type errors (npx tsc --noEmit and production build pass in 12.7s) |
✅ PASSED |
| ESLint Quality Check | Zero lint errors and zero warnings | 0 errors, 0 warnings across all app components and tests | ✅ PASSED |
| Next.js Production Build | Clean static generation and dynamic routes | 24 / 24 routes compiled cleanly in 34.3s | ✅ PASSED |
| Input Sanitization Coverage | 100% of user text inputs sanitized | DOMPurify active on discussions, replies, reflections, profiles | ✅ PASSED |
| Cohort Capacity Bounds | Enforce 5–20 member limit | Enforced at Zod schema, API route, and UI levels | ✅ PASSED |
| Production API Latency | Benchmark in distributed production | Not yet measured in production; requires staging deployment telemetry. | ℹ️ NOTED |
During the engineering audit and refactoring process, the following critical edge cases and bugs were identified and resolved:
- Reflection IDOR Vulnerability:
- Failure:
PATCH /api/reflections/[id]andDELETE /api/reflections/[id]accepted reflection IDs and updated or deleted them without checking ownership against the active session. - Remediation: Added mandatory
getServerSession(auth)checks and strict SQL ownership clauses (where(and(eq(reflections.id, id), eq(reflections.userId, session.user.id)))).
- Failure:
- Discussion Reply Impersonation:
- Failure:
POST /api/discussions/[id]/repliesacceptedbody.authorIddirectly from the client JSON payload, allowing any logged-in user to post replies under another user's identity. - Remediation: Discarded
body.authorIdentirely; author identity is now strictly set tosession.user.id.
- Failure:
- Google Books Non-UUID Query Crash:
- Failure: Navigating to
/discover/[bookId]with an alphanumeric Google Books volume ID caused PostgreSQLinvalid input syntax for type uuidcrashes when querying the local database. - Remediation: Added UUID format detection. Non-UUID IDs gracefully query the Google Books API and cache the record locally with a valid UUID.
- Failure: Navigating to
- Cohort Member Cap Bypass:
- Failure: Reading groups had no enforcement of the 5–20 member cohort limit in group joining routes.
- Remediation: Added duplicate membership checks and strict capacity verification (
group.memberCount >= (group.maxMembers || 20)) returning HTTP 409 Conflict when cohorts are full.
- AI JSON Extraction Failure Under Markdown Fences:
- Failure: Google Gemini responses wrapped in
```json ... ```failedJSON.parse(). - Remediation: Implemented
extractJsonFromResponsewith multi-stage regex extraction and deterministic fallback responses.
- Failure: Google Gemini responses wrapped in
| Technology | Declared | Actually Used | Verified Version | Purpose |
|---|---|---|---|---|
| Next.js | Yes | Yes | 16.2.10 | Full-stack framework (App Router, Server Components, Route Handlers, Proxy) |
| React | Yes | Yes | 19.2.4 | UI component model, Concurrent React, useSyncExternalStore for i18n |
| TypeScript | Yes | Yes | 5.x | End-to-end static type safety |
| Neon PostgreSQL | Yes | Yes | Serverless | Relational database storage |
| Drizzle ORM | Yes | Yes | 0.45.2 | Type-safe SQL query builder and schema migrations |
| Better Auth | Yes | Yes | 1.6.23 | Authentication, session management, and OAuth adapters |
| Zod | Yes | Yes | 4.4.3 | Declarative runtime validation schemas |
| DOMPurify | Yes | Yes | 3.4.12 | Server/client HTML and XSS sanitization (isomorphic-dompurify) |
| Google Gemini API | Yes | Yes | 2.0 Flash | Contextual book recommendations and introspective reflection prompts |
| HuggingFace API | Yes | Yes | Cloud API | Discussion content moderation and toxicity detection |
| Google Books API | Yes | Yes | v1 Volumes | Comprehensive volume metadata, synopsis, and author search |
| Open Library API | Yes | Yes | Covers API | Fallback book cover resolution via ISBN |
| Framer Motion | Yes | Yes | 12.42.2 | Minimalist UI animations and transition effects |
- Local Development / Staging:
http://localhost:3000 - Production URL: Paradize has not yet been deployed to a public production domain. Staging readiness has been validated locally.
- Node.js: v20.x or higher (tested on Node v24.12.0)
- npm: v10.x or higher
- PostgreSQL: A Neon PostgreSQL connection string
git clone https://github.com/Knight6azer/Paradize.git
cd Paradize
npm installCreate a .env.local file in the project root:
# Database
DATABASE_URL=postgresql://user:password@ep-example.region.aws.neon.tech/paradize?sslmode=require
# Authentication (Better Auth)
BETTER_AUTH_SECRET=your_32_character_random_secret_here
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
# OAuth Providers (Optional for local dev, email/password works out of the box)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
# AI Services
GEMINI_API_KEY=your_google_gemini_api_key
HUGGINGFACE_API_KEY=your_huggingface_api_key
# Book APIs
GOOGLE_BOOKS_API_KEY=your_optional_google_books_keyGenerate Drizzle migrations and push the schema to Neon:
npm run db:generate
npm run db:pushExecute the unit and security test suites:
npm testRun ESLint and the TypeScript compiler:
npm run lint
npx tsc --noEmitBuild the Next.js application:
npm run buildnpm run devOpen http://localhost:3000 in your browser.
The Paradize user interface is organized around minimalist, high-contrast typography and focused reading workflows:
- Landing Page (
/): Displays the 4 Core Principles (Curiosity Over Certainty, Respect Over Agreement, Growth Over Ego, Understanding Over Winning), cohort specifications, and multilingual toggle. - Discovery Engine (
/discover): Search literature via Google Books API, filter by philosophical themes, and receive AI-curated reading paths. - Reading Cohort Roster & Detail (
/groups,/groups/[id]): View intimate circles, member capacity bars (enforced 5–20 readers), and current shared readings. - Circle Creation Workflow (
/groups/new): Configure a new circle with targeted cohort sizing and meeting schedules. - Intellectual Discussions (
/discussions,/discussions/[id]): Filter discussions by category (Questions, Insights, Debates, Reflections, Reviews) with AI-assisted toxicity screening. - Private Reflection Journal (
/journal): An introspective space to log thoughts, select emotional moods, and answer AI-generated prompts. - Reader Profile (
/profile/[username]): Public intellectual profile displaying reading trajectories, shelves, and shared contributions.
- End-to-End Encrypted Reflection Journal: Implement client-side envelope encryption (using Web Crypto API with user-derived passphrases) so reflection notes cannot be decrypted even by database administrators.
- Real-Time Cohort Synchronization: Incorporate WebSockets or Server-Sent Events (SSE) for live reading circle discussions and synchronized reading sprints.
- Automated CI/CD Pipeline: Deploy GitHub Actions workflows that execute
npm test,npx tsc --noEmit, andnpm run linton every pull request. - Highlights & Notes Import: Integrate direct Kindle and Readwise sync to allow readers to automatically import book highlights directly into their private journal.
- Offline PWA Capabilities: Implement service worker caching and IndexedDB offline persistence for reading lists and journal entries during travel or offline focus sessions.
This project is licensed under the MIT License.
Crafted by Ujjwal & Om in Mumbai, for thoughtful readers worldwide.