Technology Stack

Uxie is built with modern, battle-tested technologies chosen for developer experience, performance, and scalability. This page documents every major dependency and explains why it was chosen.

Core Framework

Next.js 14

Version: 14.2.35Full-stack React framework with:

Hybrid routing (App + Pages Router)
API routes for serverless functions
Automatic code splitting
Built-in optimization

Why Next.js? Industry-standard React framework with excellent Vercel integration and best-in-class DX.

React 18

Version: 18.2.0UI library with:

Concurrent rendering
Suspense boundaries
Server Components support
Streaming SSR

Why React 18? Most mature UI library with massive ecosystem and community support.

Type Safety Layer

TypeScript

Version: 5.7.3 Provides static typing across the entire codebase, catching errors at compile time rather than runtime.

tRPC

Version: 10.34.0

tRPC Packages

@trpc/server - Server-side router and procedures
@trpc/client - Type-safe client
@trpc/next - Next.js adapter
@trpc/react-query - React Query integration

Why tRPC? Eliminates API contracts, provides end-to-end type safety, and auto-completes API calls in the frontend.

Zod

Version: 4.1.13 Schema validation library used for:

Runtime type validation
Input sanitization
Form validation with React Hook Form
Environment variable validation

Why Zod? First-class TypeScript inference and composable schemas.

Backend Infrastructure

Database & ORM

Supabase PostgreSQL

Managed PostgreSQL database with:

Row-level security
Built-in authentication (not used, using NextAuth instead)
Real-time subscriptions
Automatic backups

Package: @supabase/[email protected]

Prisma ORM

Version: 5.11.0Type-safe ORM with:

Schema-first design
Automatic migrations
Introspection and type generation
Query optimization

// Fully typed queries
const document = await prisma.document.findFirst({
  where: { id: docId },
  include: { highlights: true },
});

Why Prisma? Best-in-class TypeScript integration and excellent developer experience.

Authentication

NextAuth.js v4.24.5 Authentication library with:

OAuth providers (Google)
Session management
JWT tokens
Prisma adapter

Packages:

[email protected]
@next-auth/[email protected]

Why NextAuth? Secure, production-ready auth with minimal configuration.

AI & Machine Learning

LLM Integration

Vercel AI SDK

Version: 6.0.6

Streaming text generation
Tool/function calling
Multi-provider support
React hooks for UI

Packages:

Google Gemini

Model: Gemini 2.5 FlashUsed for:

PDF question answering
Flashcard generation
Flashcard evaluation
Text completion & enhancement

Why Gemini? Fast, cost-effective, and excellent at RAG tasks.

Vector Database & Embeddings

Pinecone

Version: 6.1.3 (@pinecone-database/pinecone)Managed vector database for:

Storing 768-dimensional embeddings
Similarity search (cosine metric)
Namespace-based multi-tenancy

const pinecone = new Pinecone({ apiKey });
const index = pinecone.Index("uxie");

HuggingFace Embeddings

Version: 4.13.4 (@huggingface/inference)Model: BAAI/bge-base-en-v1.5

Generates 768-dimensional embeddings
Optimized for retrieval tasks
Free to use via HuggingFace API

Why HuggingFace? High-quality embeddings without vendor lock-in, free tier suitable for production.

Langchain

Version: 0.0.171Framework for:

Document loading (PDFLoader)
Text splitting (RecursiveCharacterTextSplitter)
Vector store integration (PineconeStore)

Package: @langchain/[email protected]

Client-Side AI

Transformers.js

Version: 3.8.1 (@huggingface/transformers)Runs ML models in the browser:

OCR with Tesseract
Local embeddings
Text processing

Enables offline AI features.

PDF Processing

react-pdf-highlighter

Version: 6.1.0 (patched)Fork of react-pdf-highlighter with:

Text highlighting
Area selection
Custom annotations
Coordinates tracking

Patched to fix TypeScript issues and add custom features.

pdfjs-dist

Version: 2.16.105Mozilla’s PDF.js library:

PDF rendering
Text extraction
Canvas-based display

Supporting packages:

[email protected] - Server-side parsing

OCR Support

scribe.js-ocr v0.9.3 Client-side OCR for scanned PDFs:

Tesseract.js integration
English language support
Browser-based processing

Rich Text Editor

BlockNote v0.17.1 Notion-style block editor with:

Markdown support
Drag-and-drop blocks
Slash commands
Custom blocks

Packages:

@blocknote/core
@blocknote/react
@blocknote/mantine

Why BlockNote? Modern, extensible editor with excellent UX.

Real-time Collaboration

Liveblocks v1.7.0 Real-time collaboration infrastructure:

Presence (cursors, avatars)
Shared state
Yjs CRDT integration

Packages:

@liveblocks/client
@liveblocks/react
@liveblocks/yjs
[email protected]

Why Liveblocks? Easy integration with React and Yjs, handles WebSocket complexity.

UI Framework

Component Libraries

Radix UI

Headless, accessible component primitives:

@radix-ui/react-dialog
@radix-ui/react-dropdown-menu
@radix-ui/react-popover
@radix-ui/react-accordion
@radix-ui/react-slider
And more…

Why Radix? WAI-ARIA compliant, unstyled components perfect for custom designs.

Shadcn UI

Pre-styled Radix components with Tailwind:

Copy-paste components (not npm package)
Fully customizable
Consistent design system

Located in src/components/ui/

Styling

Tailwind CSS v3.3.3 Utility-first CSS framework with:

JIT compilation
Custom design tokens
Typography plugin
Animation plugin

Packages:

[email protected]
@tailwindcss/[email protected]
[email protected]
[email protected] - Merge classes safely

Supporting:

[email protected] - Type-safe variants
[email protected] - Class name utility

Data Fetching & State

React Query

Version: 4.29.25Server state management:

Caching & invalidation
Optimistic updates
Background refetching
Pagination & infinite scroll

Integrated with tRPC for type-safe queries.

Zustand

Version: 4.4.6Client state management:

Minimal boilerplate
No providers needed
DevTools integration

Used for UI state like sidebar open/close.

Form Handling

React Hook Form v7.46.2 Performant form library with:

Uncontrolled components
Schema validation via Zod
Error handling

Package: @hookform/[email protected] - Zod integration

File Upload

UploadThing v7.0.2 File upload infrastructure with:

Serverless file handling
CDN delivery
Type-safe API

Packages:

[email protected]
@uploadthing/[email protected]

Why UploadThing? Built for Next.js, handles large PDFs, generous free tier.

Text-to-Speech

TTS Providers

Multiple TTS providers for flexibility:

Browser Native - Web Speech API (free)
Kokoro.js v1.2.1 - Local neural TTS models
Custom Provider - Abstract interface for extensibility

Implementation in src/lib/tts/providers/

Utilities & Helpers

Essential Libraries

Package	Version	Purpose
`superjson`	1.13.1	Serialize Dates, Maps, Sets over network
`nuqs`	1.17.8	Type-safe search params (URL state)
`usehooks-ts`	3.1.1	Collection of useful React hooks
`use-debounce`	9.0.4	Debounce values and functions
`react-hotkeys-hook`	5.2.3	Keyboard shortcuts
`react-intersection-observer`	9.5.3	Visibility detection
`framer-motion`	10.16.4	Animation library
`lucide-react`	0.563.0	Icon library
`sonner`	1.4.41	Toast notifications
`cmdk`	1.0.0	Command palette (Cmd+K)
`vaul`	1.0.0	Bottom sheet drawer

UI Utilities

[email protected] - Resizable split panels
[email protected] - Auto-growing textareas
[email protected] - Balanced text wrapping
[email protected] - Markdown renderer
[email protected] - SEO meta tags

Development Tools

Code Quality

ESLint

Version: 8.47.0Linting with:

eslint-config-next - Next.js rules
@typescript-eslint/eslint-plugin - TypeScript rules

Prettier

Version: 3.0.0Code formatting with plugins:

prettier-plugin-tailwindcss - Sort classes
prettier-plugin-organize-imports - Sort imports

Build Tools

PostCSS v8.4.27 - CSS transformation
Autoprefixer v10.4.14 - Vendor prefixes
TSX v4.9.3 - TypeScript executor for scripts
Terser v5.3.16 - JavaScript minification

Environment Variables

Required Environment Variables

# Database
DATABASE_URL=postgresql://...

# Auth
NEXTAUTH_SECRET=<openssl rand -base64 32>
NEXTAUTH_URL=http://localhost:3000
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# File Upload
UPLOADTHING_TOKEN=...

# AI Services
PINECONE_API_KEY=...
PINECONE_ENVIRONMENT=...
HUGGINGFACE_API_KEY=...
GOOGLE_GENERATIVE_AI_API_KEY=...

# Collaboration (optional)
NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_API_KEY=...

Validated with @t3-oss/[email protected] and Zod in src/env.mjs.

Version Requirements

Node.js

Minimum: v18.16.0Required for:

Native fetch API
ESM support
Crypto APIs

pnpm

Version: 9.14.2Package manager with:

Faster installs
Disk space efficiency
Patch support

Why These Choices?

Type Safety Everywhere

Every layer has type safety:

Database → Prisma types
API → tRPC procedures
Forms → Zod schemas
UI → TypeScript components

Performance First

Edge-ready - Most APIs can run on edge
Streaming - AI responses stream to reduce latency
Code splitting - Automatic with Next.js
Vector search - Sub-second similarity queries

Developer Experience

End-to-end types - Auto-complete everywhere
Hot reload - Fast development cycle
No code generation - Types inferred, not generated
Modern tooling - ESLint, Prettier, TypeScript

Dependency Management

Patch Strategy

Patched dependencies in pnpm.patchedDependencies:

{
  "[email protected]": "patches/[email protected]"
}

Applied with pnpm patch command.

Update Strategy

Major versions - Reviewed quarterly
Minor versions - Updated monthly
Patch versions - Auto-updated with Dependabot
Security patches - Immediate updates

Next Steps

Architecture

Learn how these technologies work together

Contributing

Set up your development environment

Contributing

​Technology Stack

​Core Framework

Next.js 14

React 18

​Type Safety Layer

​TypeScript

​tRPC

​Zod

​Backend Infrastructure

​Database & ORM

​Authentication

​AI & Machine Learning

​LLM Integration

Vercel AI SDK

Google Gemini

​Vector Database & Embeddings

​Client-Side AI

​PDF Processing

react-pdf-highlighter

pdfjs-dist

​OCR Support

​Rich Text Editor

​Real-time Collaboration

​UI Framework

​Component Libraries

​Styling

​Data Fetching & State

React Query

Zustand

​Form Handling

​File Upload

​Text-to-Speech

​Utilities & Helpers

​Essential Libraries

​UI Utilities

​Development Tools

​Code Quality

​Build Tools

​Environment Variables

​Version Requirements

Node.js

pnpm

​Why These Choices?

​Type Safety Everywhere

​Performance First

​Developer Experience

​Dependency Management

​Patch Strategy

​Update Strategy

​Next Steps

Architecture

Contributing

Build docs developers (and LLMs) love

Technology Stack

Core Framework

Type Safety Layer

TypeScript

tRPC

Zod

Backend Infrastructure

Database & ORM

Authentication

AI & Machine Learning

LLM Integration

Vector Database & Embeddings

Client-Side AI

PDF Processing

OCR Support

Rich Text Editor

Real-time Collaboration

UI Framework

Component Libraries

Styling

Data Fetching & State

Form Handling

File Upload

Text-to-Speech

Utilities & Helpers

Essential Libraries

UI Utilities

Development Tools

Code Quality

Build Tools

Environment Variables

Version Requirements

Why These Choices?

Type Safety Everywhere

Performance First

Developer Experience

Dependency Management

Patch Strategy

Update Strategy

Next Steps