Cache

Your personal knowledge management companion

Cache is a modern, full-stack web application designed to help users capture, organize, and revisit their thoughts, ideas, and inspirations. Built with Next.js, Prisma, and a modular component architecture, Cache provides a seamless and intuitive experience for personal knowledge management.

Quick Start: Press Cmd/Ctrl + K to add your first thought! 💭

Table of Contents

• Features
• Tech Stack
• Getting Started
• Project Structure
• Architecture
  • Database Schema
  • API Routes
  • State Management
  • Key Components
  • Data Flow
• Scripts
• Technical Details
• Keyboard Shortcuts
• Security Features
• Performance Optimizations
• Contributing
• License

Features

• User Authentication: Secure sign-in and session management with NextAuth.js.
• Thought Management: Add, edit, delete, and categorize thoughts easily.
• Category Organization: Group thoughts by categories for better organization.
• Link Previews: Automatically generate rich previews for links added to thoughts.
• Responsive UI: Clean, modern interface with reusable UI components.
• API-First: RESTful API endpoints for thoughts, categories, and link previews.
• Prisma ORM: Type-safe database access and migrations.

Tech Stack

• Next.js
• TypeScript
• Prisma
• NextAuth.js
• Tailwind CSS (assumed for styling)

Getting Started

Prerequisites

• Node.js (v18+ recommended)
• npm or yarn
• A PostgreSQL database (or update prisma/schema.prisma for your DB)

Installation

1. Clone the repository:

   git clone https://github.com/Ayroid/Cache.git
   cd Cache

2. Install dependencies:

   npm install
   # or
   yarn install

3. Configure environment variables:

   • Copy .env.example to .env and fill in the required values (database URL, NextAuth secrets, etc).

4. Run database migrations:

   npx prisma migrate dev --name init

5. Start the development server:

   npm run dev
   # or
   yarn dev

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

Project Structure

• app/ — Next.js app directory (routes, API, pages)
  • app/page.tsx — Main application entry point
  • app/api/thoughts/ — Thought management endpoints
  • app/api/categories/ — Category management endpoints
  • app/api/link-preview/ — Link metadata fetching
  • app/api/auth/ — NextAuth.js authentication
• components/ — Reusable React components
  • Dashboard.tsx — Main application interface
  • AddThoughtModal.tsx — Thought creation modal (Cmd/Ctrl+K)
  • ThoughtCard.tsx — Individual thought display
  • CategoryBar.tsx — Category filter and management
  • ui/ — Shadcn-style UI components
• lib/ — Utility functions, hooks, and Prisma client
  • hooks.ts — useMind hook for state management
  • prisma.ts — PostgreSQL connection via Prisma
• prisma/ — Prisma schema and migrations
  • schema.prisma — Database schema (User, Category, Thought models)
• public/ — Static assets
• types/ — TypeScript type definitions
  • index.ts — Core types and constants

Architecture

Database Schema

Cache uses Prisma ORM with PostgreSQL for type-safe database access. The schema consists of three main models:

User Model

• Handles authentication via NextAuth.js
• Stores username, email, profile picture
• Relations: categories, thoughts
• See: auth.ts, app/api/auth/[...nextauth]/route.ts

Category Model (prisma/schema.prisma:24-33)

• User-defined thought organization (max 5 per user)
• Colors: amber, coral, teal, sage, lavender, stone
• Cascade deletes associated thoughts
• See: app/api/categories/route.ts

Thought Model (prisma/schema.prisma:35-48)

• Stores text or link-type thoughts
• Optional link metadata (title, image, favicon)
• Pin functionality for important thoughts
• See: app/api/thoughts/route.ts

API Routes

All API routes are located in app/api/ and follow RESTful conventions:

Thoughts (app/api/thoughts/route.ts)

• GET /api/thoughts — Fetch all user thoughts (ordered by newest)
• POST /api/thoughts — Create new thought (auto-detects URLs)
• PATCH /api/thoughts/[id] — Update content, category, or pin status
• DELETE /api/thoughts/[id] — Delete thought

Categories (app/api/categories/route.ts)

• GET /api/categories — Fetch all user categories
• POST /api/categories — Create new category (enforces max 5)
• PATCH /api/categories/[id] — Update name or color
• DELETE /api/categories/[id] — Delete category and all thoughts

Link Preview (app/api/link-preview/route.ts)

• GET /api/link-preview?url=<url> — Fetch Open Graph metadata
• Extracts title, image, and favicon for link-type thoughts

State Management

The useMind hook manages all application state:

• Fetches and caches categories/thoughts
• Provides CRUD methods for thoughts and categories
• Handles filtering, pinning, and sorting logic
• Auto-syncs with backend APIs

Key features:

• filterThoughts() — Filters by category, sorts pinned first
• formatRelativeTime() — Human-readable timestamps
• togglePin() — Pin/unpin thoughts to top

Key Components

Dashboard (components/Dashboard.tsx)

• Main application container
• Sticky header with category filter
• Masonry grid layout for thoughts
• Empty state handling

AddThoughtModal (components/AddThoughtModal.tsx)

• Floating action button (bottom-right)
• Keyboard shortcut: Cmd/Ctrl + K
• Auto-detects URLs and fetches link previews
• Save with Cmd/Ctrl + Enter

ThoughtCard (components/ThoughtCard.tsx)

• Displays individual thoughts
• Link preview for URL-type thoughts
• Pin, edit, move, delete actions
• Category badge with color coding

CategoryBar (components/CategoryBar.tsx)

• Horizontal scrollable category pills
• "All" filter to show everything
• Add/edit categories with color picker

Data Flow

1. Authentication → Google OAuth via NextAuth.js
2. Dashboard Load → useMind hook fetches data from API
3. Add Thought → Modal → URL detection → Link preview API → Save to DB
4. Organize → Filter, pin, edit, move via ThoughtCard actions
5. Persistence → All changes saved to PostgreSQL via Prisma

Scripts

• dev — Start the development server
• build — Build the application for production
• start — Start the production server
• prisma — Prisma CLI commands

Technical Details

For a comprehensive technical overview including:

• Complete API endpoint documentation
• Detailed database schema specifications
• Component architecture and data flow
• Security and permission patterns
• Performance optimizations

See the detailed codebase analysis section above, or explore the following key files:

• Database: prisma/schema.prisma
• State Management: lib/hooks.ts
• Type Definitions: types/index.ts
• Authentication: auth.ts

Keyboard Shortcuts

• Cmd/Ctrl + K — Open add thought modal
• Cmd/Ctrl + Enter — Save thought (in modal)
• Esc — Close modal

Security Features

• Authentication: Google OAuth via NextAuth.js
• Authorization: All API routes verify user ownership before modifications
• Data Isolation: Users can only access their own thoughts and categories
• Input Validation: Server-side validation for all user inputs
• SQL Injection Protection: Prisma ORM provides parameterized queries

Performance Optimizations

• Connection Pooling: PostgreSQL connections pooled via pg.Pool
• Indexed Queries: Database indexes on userId, categoryId, isPinned, createdAt
• Client-side Caching: useMind hook caches data to minimize API calls
• Lazy Loading: Components load only when needed
• Masonry Layout: CSS-based layout for efficient rendering

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)

Contributing

Contributions are welcome! Please open issues or pull requests for suggestions, bug fixes, or new features.

License

This project is licensed under the MIT License.