Intelligent Personal Knowledge Manager

A full‑stack, TypeScript‑only, test‑driven personal knowledge manager that uses AI to summarise, tag, and suggest connections between notes.
Built with Next.js, RTK‑Toolkit, Supabase, IndexedDB, OpenAI, and optional local transformer inference.

🚀 Features

Feature	Human‑Centered Benefit	AI Contribution
Write & edit	Rich markdown, code blocks, instant preview	–
Auto‑tags	Faster organization	GPT‑4o‑mini “What tags fit this note?”
Summary sidebar	Quick review	GPT‑4o‑mini “Summarise this note in 3 bullets.”
Graph view	Visual link map	GPT‑4o‑mini “Which other notes could be linked to this?”
Q&A chat	Ask “What did I learn about X?”	GPT‑4o‑mini or local transformer
Offline mode	Work without internet	Local transformer (t5‑small) runs in‑browser
Electron wrapper	Desktop app	–
Local AI toggle	Switch between server‑side and in‑browser inference	–

🛠️ Tech Stack

• Framework: Next.js 14 (App Router, SSR/ISR)
• Language: TypeScript
• UI: Tailwind CSS + Radix UI
• State: Redux Toolkit + RTK Query
• Database: Supabase (PostgreSQL) + IndexedDB (Dexie)
• AI: OpenAI (server‑side) + @xenova/transformers (local)
• Testing: Jest, React Testing Library, Cypress, axe‑core
• CI/CD: GitHub Actions
• Deployment: Vercel (serverless API routes)
• Desktop: Electron (electron‑forge)

📦 Installation

# Clone the repo
git clone https://github.com/your-username/your-repo.git
cd your-repo

# Install dependencies
npm install
# or
yarn
# or
pnpm

Environment Variables

Create a .env.local file at the root and add:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key

# OpenAI
OPENAI_API_KEY=your-openai-key

Tip: Keep the OpenAI key server‑side only – it is never exposed to the browser.

🚀 Running the App

# Development
npm run dev
# or
yarn dev

Open http://localhost:3000 to see the app.

📦 Building for Production

npm run build
npm start

🧪 Testing

# Unit & integration tests
npm test

# End‑to‑end tests (Cypress)
npm run cy:open

All tests run automatically in the CI pipeline.

📦 CI / CD

• GitHub Actions: lint, test, build, and upload artifacts.
• Vercel: One‑click deploy button in the README (see below).

📱 Offline & Local AI

• IndexedDB: All notes, tags, and links are cached locally for offline editing.
• Local Transformer: Toggle “Use local AI” to run summarisation/tag‑suggestion in‑browser (no network).

📦 Electron Build

npm run build:electron

This produces a native desktop app for Windows, macOS, and Linux.

📄 Documentation

• Architecture diagram (see docs/architecture.svg)
• API reference (auto‑generated by Vercel)
• Contribution guide (CONTRIBUTING.md)

📦 Deploy on Vercel

Vercel automatically builds the Next.js app and exposes the serverless API routes.

📚 FAQ

Question	Answer
Can I replace Supabase with Firestore?	Yes – swap the client in the API routes and adjust schemas.
What if I need GPT‑4 instead of GPT‑4o‑mini?	Change the model in pages/api/ai/summarise.ts to gpt-4.
Is the local model stable?	@xenova/transformers works on Chrome/Edge/Firefox; Safari is slower.
How to handle > 5 k tokens?	Chunk the content, summarise each chunk, concat results, show progress.
Do I need a dedicated server?	Vercel’s serverless API routes run on edge nodes; no VM needed.

📜 License

MIT © 2025 Your Name