Skip to content
Knight6azerPublic

About

Positioned as an alternative to mainstream media consumption, Paradize is a global initiative driving intellectual evolution. It provides an exclusive sanctuary where lifelong learners engage in elevate dialogue and purposeful personal development.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Paradize 🌿

A reading and intellectual-growth platform designed around meaningful conversations, reflection, lifelong learning, and intimate community rather than passive, algorithmic, superficial content consumption.


Problem

Modern digital media platforms are engineered to optimize for virality, impulsive engagement, and ad revenue. This creates severe structural pathologies:

  1. Superficial Skimming & Doomscrolling: Content algorithms prioritize outrage, short-form ephemera, and rapid dopamine loops, reducing attention spans and eroding deep cognitive focus.
  2. 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.
  3. Polarized & Toxic Forums: Discussion spaces reward antagonism, flame wars, and superficial hot takes where "winning" the debate takes precedence over genuine intellectual comprehension.
  4. 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.


Why It Matters

The Four Foundational Principles

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.

Who Benefits

  • 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).

Architecture

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

End-to-End Data Flow

  1. User Intent & Navigation: The user initiates an action (e.g. creating a group, logging a private reflection, contributing to a discussion).
  2. Proxy Route Guarding: src/proxy.ts inspects session tokens via Better Auth. Unauthenticated requests to protected zones (/dashboard, /journal, /groups, /library) are redirected to /login.
  3. 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).
  4. Session Authorization & Multi-Tenant Scoping: All mutations strictly extract session.user.id from the verified session rather than accepting client-supplied author identifiers, eliminating IDOR and impersonation vulnerabilities.
  5. Intelligence & Enrichment: Contextual book recommendations and reflection prompts are generated via Google Gemini 2.0 Flash with regex JSON extraction and deterministic fallback safeguards.
  6. Persistence: Drizzle ORM executes type-safe queries against Neon Serverless PostgreSQL.

Dataset

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

Approach

1. Intimate Cohort Architecture (5–20 Readers)

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.

2. Hybrid AI Integration & Resilience

  • 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 extractJsonFromResponse using 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.

3. Comprehensive Security Hardening

  • 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.

4. Internationalization (i18n)

  • Native support for 6 global languages: English (en), Hindi (hi), Spanish (es), French (fr), German (de), and Bengali (bn).
  • Uses React 19 useSyncExternalStore in LanguageContext for instant, tear-free language switching with automatic localStorage persistence and fallback resolution.

Results

Verified Quality Metrics

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

Error Analysis

During the engineering audit and refactoring process, the following critical edge cases and bugs were identified and resolved:

  1. Reflection IDOR Vulnerability:
    • Failure: PATCH /api/reflections/[id] and DELETE /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)))).
  2. Discussion Reply Impersonation:
    • Failure: POST /api/discussions/[id]/replies accepted body.authorId directly from the client JSON payload, allowing any logged-in user to post replies under another user's identity.
    • Remediation: Discarded body.authorId entirely; author identity is now strictly set to session.user.id.
  3. Google Books Non-UUID Query Crash:
    • Failure: Navigating to /discover/[bookId] with an alphanumeric Google Books volume ID caused PostgreSQL invalid input syntax for type uuid crashes 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.
  4. 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.
  5. AI JSON Extraction Failure Under Markdown Fences:
    • Failure: Google Gemini responses wrapped in ```json ... ``` failed JSON.parse().
    • Remediation: Implemented extractJsonFromResponse with multi-stage regex extraction and deterministic fallback responses.

Tech Stack

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

Demo

  • 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.

Installation & Setup

1. Prerequisites

  • Node.js: v20.x or higher (tested on Node v24.12.0)
  • npm: v10.x or higher
  • PostgreSQL: A Neon PostgreSQL connection string

2. Clone the Repository

git clone https://github.com/Knight6azer/Paradize.git
cd Paradize
npm install

3. Environment Configuration

Create 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_key

4. Database Schema Migration

Generate Drizzle migrations and push the schema to Neon:

npm run db:generate
npm run db:push

5. Running the Automated Test Suite

Execute the unit and security test suites:

npm test

6. Code Quality & Type Checks

Run ESLint and the TypeScript compiler:

npm run lint
npx tsc --noEmit

7. Building for Production

Build the Next.js application:

npm run build

8. Starting the Development Server

npm run dev

Open http://localhost:3000 in your browser.


Screenshots & Platform Interface

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.

Future Improvements

  1. 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.
  2. Real-Time Cohort Synchronization: Incorporate WebSockets or Server-Sent Events (SSE) for live reading circle discussions and synchronized reading sprints.
  3. Automated CI/CD Pipeline: Deploy GitHub Actions workflows that execute npm test, npx tsc --noEmit, and npm run lint on every pull request.
  4. Highlights & Notes Import: Integrate direct Kindle and Readwise sync to allow readers to automatically import book highlights directly into their private journal.
  5. Offline PWA Capabilities: Implement service worker caching and IndexedDB offline persistence for reading lists and journal entries during travel or offline focus sessions.

License

This project is licensed under the MIT License.

Crafted by Ujjwal & Om in Mumbai, for thoughtful readers worldwide.

About

Positioned as an alternative to mainstream media consumption, Paradize is a global initiative driving intellectual evolution. It provides an exclusive sanctuary where lifelong learners engage in elevate dialogue and purposeful personal development.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages