Inquisitive — AI-Powered Dynamic Knowledge Mapping

Inquisitive is a modern, structured learning workspace designed to convert user curiosity into comprehensive, actionable learning curriculums. By combining search capabilities with generative model pipelines, it transforms open-ended research topics into interactive Kanban learning boards loaded with high-quality articles, tutorial videos, and custom progress tracking.

Built as a modular monorepo using Express.js, React 18 (Vite), TypeScript, Drizzle ORM, Neon serverless PostgreSQL, and Upstash Redis, Inquisitive is engineered for rapid, structured knowledge mapping with production-grade speed, safety guardrails, and total type integrity.

Workspace Modules

The project is structured as a monorepo containing distinct, specialized packages:

Module	Location	Primary Technologies	Purpose
Backend API	`/backend`	Node.js, Express, TypeScript, Drizzle ORM, Upstash Rate Limiter	Handles the core generative pipeline, parses request payloads, manages database operations, and enforces API traffic limiters.
Frontend SPA	`/frontend`	React 18, Vite, Zustand, Framer Motion, dnd-kit, Tailwind CSS, CSS Variables	Delivers a high-fidelity client interface with spring-loaded Kanban interactions, progress meters, and responsive layouts.

Directory File Structures

Inquisitive is split into structured directories designed for clean decoupling, modular scaling, and type safety.

🧩 Frontend Project Structure (`/frontend`)

The client application utilizes a modern Feature-Based Architecture where components, views, and core assets are logically categorized by their functional domain:

frontend/
├── src/
│   ├── assets/              # Brand visual assets (logos, loading animations, gifs)
│   ├── config/              # App constants, REST base endpoints, and environment variables
│   ├── context/             # Global React Context providers
│   ├── features/            # Feature-Based Modules (Highly Modular & Decoupled)
│   │   ├── auth/            # Authentication & anonymous profiling flow
│   │   ├── LandingPage/     # Brand presentation components
│   │   ├── dashboard/       # Core Hub Workspace
│   │   │   └── components/  # Sidebar, SearchSection, NotebooksSection, LoadingScreen
│   │   └── notebook/        # Interactive curriculum workspace
│   │       └── components/  # KanbanBoard, KanbanColumn, ResourceCard, StreakBadge, SkeletonCard
│   ├── hooks/               # Shared global React hooks (e.g., useStreak)
│   ├── layouts/             # App page structural wrappers
│   ├── lib/                 # Timezone-safe streak utility engines & helpers
│   ├── pages/               # Top-level view router pages
│   │   ├── HomePage.tsx     # Generative prompt deck and path index overview
│   │   ├── NotebookPage.tsx # Curated Kanban workspace page
│   │   ├── LandingPage.tsx  # Product showcase landing page
│   │   └── NotFoundPage.tsx # Custom 404 error handler
│   ├── routes/              # Client-side router configuration
│   ├── services/            # Axios API transaction wrappers
│   ├── stores/              # Zustand global client-side state engines (e.g., kanbanStore)
│   ├── styles/              # Global Vanilla CSS tokens, HSL typography & visual themes
│   └── types/               # Shared client TypeScript compiler interface definitions
├── index.html               # Main single-page application entrypoint (contains SEO & Favicon)
└── package.json             # Client packages, scripts index, and workspace bindings

⚡ Backend Project Structure (`/backend`)

The server-side application is built using a robust controller-service abstraction that isolates endpoints, data models, web crawlers, and AI orchestrators:

backend/
├── src/
│   ├── config/              # Server setups (caching, CORS security profile, Redis rate-limiters)
│   ├── controllers/         # HTTP request handlers & parser controllers
│   │   ├── notebook.controller.ts
│   │   └── resource.controller.ts
│   ├── db/                  # Drizzle ORM database engine
│   │   ├── index.ts         # Neon Serverless postgres client connector
│   │   └── schema.ts        # Strictly typed SQL table definitions (notebooks & resources)
│   ├── middleware/          # CORS interceptors, IP rate-limiting guards, and logging gates
│   ├── routes/              # Express router endpoints
│   │   ├── index.ts         # Parent route consolidator
│   │   ├── notebook.route.ts
│   │   └── resource.route.ts
│   ├── services/            # Business & orchestration workflows
│   │   ├── ai.service.ts    # Dual-stage curriculum generator prompt planner (Gemini/GROQ/OpenRouter)
│   │   └── search.service.ts # Parallel web search crawler & YouTube scraper API matches
│   ├── types/               # Server-side TypeScript interface declarations
│   └── index.ts             # Express application main runner and listener
├── drizzle/                 # SQL schemas compiled into migration scripts
├── package.json             # Server packaging, environment commands, and db syncs
└── tsconfig.json            # Server TypeScript compilation parameters

Production Cloud Architecture

Inquisitive is engineered as a serverless, decoupled monorepo designed for rapid, distributed cloud delivery. The live production environment is orchestrated across specialized high-performance platforms:

Component Stack Details

Frontend Hosting (Vercel): Serves the highly optimized Vite single-page application React assets from Vercel's global edge network. Fully maps client-side browser routing rewrites through vercel.json.
Backend Runtime (Render): Hosts the Express API server with automatic Git-triggered deployments, managing high-throughput traffic and parallel web-crawling/parsing operations.
Serverless SQL (Neon Postgres): Powers the robust relational storage using Neon's serverless PostgreSQL engine, integrated with Drizzle ORM for automatic schema generation, migration mapping, and hot query execution.
Serverless Cache (Upstash Redis): Provides low-latency key-value storing for IP-based rate limiting via the @upstash/ratelimit or rate-limit-redis layers with elegant fail-open resiliency.

Database Schema (Drizzle ORM)

The relational database is structured around two core tables: notebook and resource.

Table Definitions

Notebook Table (`notebook`)

Field	Data Type	Constraints	Description
id	`uuid`	Primary Key, `defaultRandom()`	Unique identifier for each generated learning curriculum.
deviceId	`varchar(36)`	Not Null	Identifies the client browser or machine that initiated the request.
createdAt	`timestamp`	`defaultNow()`, With Timezone	Records the execution timestamp of the planning request.
topic	`varchar(255)`	Not Null	The primary subject or topic parsed by the AI Planner.
level	`topic_level`	Not Null, Custom Enum	Difficulty tier: `beginner`, `intermediate`, or `hard`.
length	`length`	Not Null, Custom Enum	Course depth / node count: `short`, `medium`, or `long`.

Resource Table (`resource`)

Field	Data Type	Constraints	Description
id	`uuid`	Primary Key, `defaultRandom()`	Unique identifier for the individual learning node.
notebookId	`uuid`	Foreign Key, References `notebook.id`	Establishes the relationship. Configured with cascading delete behavior.
title	`text`	Not Null	Curated learning material title.
url	`varchar(255)`	Not Null	Hyperlink leading to the video tutorial or article documentation.
thumbNail	`text`	Nullable	Custom YouTube preview image (derived from YouTube API matches).
sourceType	`source_type`	Not Null, Custom Enum	Type classification: `article` or `video`.
difficulty	`difficulty`	Not Null, Custom Enum	Structural skill level ranking from `1` (simplest) to `5` (hardest).
status	`status`	Not Null, Custom Enum	Kanban Board status state: `todo`, `in_progress`, `completed`, or `skipped`.
summary	`text`	Nullable	Highly concise, action-focused 2-sentence curriculum description.
createdAt	`timestamp`	`defaultNow()`, With Timezone	Timestamp when resource was fetched and saved.
updatedAt	`timestamp`	`defaultNow()`, With Timezone	Tracks column transitions or manual metadata edits.

Design System Tokens & Aesthetics

The client interface utilizes a custom warm editorial design system mapped entirely in Vanilla CSS to avoid layout bloat.

Token Group	Values / Variables	Application & Visual Experience
Background Color	`#fdfbf7`, `bg-bento-warm`	Warm organic paper base mirroring physical textbook paper texture.
Typography Fonts	Outfit, Plus Jakarta Sans, Sora	Muted, high-contrast print headlines paired with readable UI labels.
Accents & Borders	`#D4C4A8`, `border-bento`, `#7c3aed`	Golden sand borders combined with deep violet interactive icons.
Physics & Motion	`Framer Motion`, `dnd-kit`	Spring-based Kanban node interactions and staggered card dealing.

Application Walkthrough & Visuals

Here is an overview of the core application viewports. Keep these sections updated with screenshots of your current deployment:

Dashboard & Smart Search Setup

The clean, minimalist landing workspace allows immediate input, structured filters, and error banner notifications if input validation fails.

High-Fidelity Kanban Board

When the AI orchestrator builds a notebook, resources are organized into an interactive Kanban board. Moving cards immediately recalculates the learning progress bar and syncs back to Neon.

Mobile-First Bottom Bars & Columns

For smaller viewports, columns smoothly stack into a responsive layout with touch-friendly dragging handles and a responsive bottom navigation.

(Screenshot Space: Place mobile_responsive_view.png here showing mobile column layouts)

Getting Started

Follow these steps to run a fully functional development environment locally.

Prerequisites

Prerequisite	Minimum Version	Required For
Node.js	20.x (LTS)	Package runner, builds, and backend operations.
npm	10.x	Monorepo workspaces management.
Docker Desktop	Latest	Running local caching/Redis clusters and emulators.

1. Environment Configurations

Backend Configuration (`/backend/.env`)

Variable	Recommended / Default Value	Purpose
PORT	`3000`	Express API port.
NODE_ENV	`development`	Enables debug loggers and verbose schema checking.
CLIENT_URL	`"http://localhost:5173"`	Configures CORS allowed origin vectors.
DATABASE_URL	`postgres://user:pass@ep-host.neon.tech/db`	Neon Serverless PostgreSQL connection string.
GROQ_API_KEY	`your_GROQ_api_key`	Authenticates planner and enricher GROQ LLM queries (via the free tier API).

Frontend Configuration (`/frontend/.env`)

Variable	Default Value	Purpose
VITE_API_URL	`"http://localhost:3000/api"`	Base client entrypoint for REST interactions.
VITE_PUBLIC_POSTHOG_KEY	`"your_posthog_project_api_key"`	Ingestion key for PostHog client analytics.
VITE_PUBLIC_POSTHOG_HOST	`"https://us.i.posthog.com"`	Ingestion host endpoint URL.

2. Infrastructure Setup (Docker Compose)

The repository includes a customized Docker environment that runs a local Postgres-compatible Redis Stack (redis-stack) along with an Upstash HTTP Translator container (upstash-local), allowing @upstash/ratelimit to resolve without real Upstash Cloud credentials.

Boot all core database and caching services concurrently:

docker compose -f docker-compose.dev.yaml up --build

This initializes:

Redis Stack: Running on standard port 6379.
RedisInsight GUI: Available on port 8001 for real-time key inspection.
Serverless Redis HTTP Emulator: Translation bridge available on port 8079 (maps internal container port 80).

3. Application Execution

Install all workspace dependencies from the root directory:

npm install

Boot the frontend Vite server and backend Express server concurrently using workspace scripts:

npm run dev:frontend  # Boots React + Vite Client (http://localhost:5173)
npm run dev:backend   # Boots Express API Server (http://localhost:3000)

Unified Scripts Index

Execute commands directly from the monorepo root:

Command	Action	Workspace / Scope
`npm run dev:frontend`	Boots the Vite client environment with proxy mappings.	`frontend`
`npm run dev:backend`	Boots Express server with TS-Node-Dev live-reloading.	`backend`
`npm run build`	Builds and transpiles all client and backend production assets.	Monorepo Root

API Routes Reference

The backend exposes these core routes under /api:

Notebooks Endpoint (`/api/notebook`)

Method	Route	Request Payload	Behavior / Function
GET	`/getAll`	None	Retrieves all saved learning notebooks for the active device.
POST	`/create`	`{ topic: string, level: string, length: string }`	Triggers the dual-stage AI orchestrator pipeline to validate the query, plan skills, crawl the web, enrich resources, persist structures, and return the final JSON.
DELETE	`/:id`	None	Deletes a notebook and cascades deletion to all associated resources.

Resources Endpoint (`/api/resources`)

Method	Route	Request Payload	Behavior / Function
GET	`/:notebookId`	None	Retrieves all learning materials associated with a specific notebook.
DELETE	`/:id`	None	Deletes a single learning node card.
PATCH	`/update/:id`	`{ status: string }`	Updates the card's column status (e.g. `todo` to `in_progress`, `completed`, or `skipped`) in the database.

📈 Telemetry & Analytics (PostHog)

Inquisitive includes client-side session recording and event logging powered by PostHog to track learning behaviors and engagement milestones:

Tracked Events & Lifecycle

Device Session Binding: Maps client actions to a persistent browser UUID (posthog.identify(deviceId)) to group anonymous activities into single, continuous profiles.
Notebook Generation:
- notebook_created: Logs topic name, difficulty level, and size size when a dynamic curriculum resolves.
- notebook_creation_failed: Logs error messages and target topic to catch generative failures.
Engagement Signals (card_status_changed): Logs card moves between Kanban states (e.g. todo, in_progress, completed, skipped) alongside resource media type (article vs video).
Retention Signals (notebook_completed): Fires once a learning progress meter reaches 100% (i.e. all valid cards completed) with topic and card count metadata.

AI Usage

Antigravity

Used for debugging.

Tavily

Used for web search.

GROQ API OR OPENROUTER_API

Used for AI generation (using Google's free-tier GROQ or Openrouter models).

Claude Web, Perplexity

Used for brainstorm.

UI inspiration:

https://cofounder.co/
Dribble: Taqwah
Notion for Kanban Dashboard.
CTA.gallery for CTA inspiration.
Framer Motion Library for animations.

Inquisitive - Made with Love: Jay Mehta

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
.planning		.planning
backend		backend
dev_docs		dev_docs
frontend		frontend
readme_assets		readme_assets
.gitignore		.gitignore
README.md		README.md
docker-compose.dev.yaml		docker-compose.dev.yaml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json

Folders and files

Latest commit

History

Repository files navigation

Inquisitive — AI-Powered Dynamic Knowledge Mapping

Workspace Modules

Directory File Structures

🧩 Frontend Project Structure (/frontend)

⚡ Backend Project Structure (/backend)

Production Cloud Architecture

Component Stack Details

Database Schema (Drizzle ORM)

Table Definitions

Notebook Table (notebook)

Resource Table (resource)

Design System Tokens & Aesthetics

Application Walkthrough & Visuals

Dashboard & Smart Search Setup

High-Fidelity Kanban Board

Mobile-First Bottom Bars & Columns

Getting Started

Prerequisites

1. Environment Configurations

Backend Configuration (/backend/.env)

Frontend Configuration (/frontend/.env)

2. Infrastructure Setup (Docker Compose)

3. Application Execution

Unified Scripts Index

API Routes Reference

Notebooks Endpoint (/api/notebook)

Resources Endpoint (/api/resources)

📈 Telemetry & Analytics (PostHog)

Tracked Events & Lifecycle

AI Usage

Antigravity

Tavily

GROQ API OR OPENROUTER_API

Claude Web, Perplexity

UI inspiration:

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

🧩 Frontend Project Structure (`/frontend`)

⚡ Backend Project Structure (`/backend`)

Notebook Table (`notebook`)

Resource Table (`resource`)

Backend Configuration (`/backend/.env`)

Frontend Configuration (`/frontend/.env`)

Notebooks Endpoint (`/api/notebook`)

Resources Endpoint (`/api/resources`)

Packages