Share to X
Share to LinkedInKeepFlash Architecture Overview
This guide describes how KeepFlash is structured for developers working on the codebase.
Application Stack
- Next.js App Router with React 19 server and client components
- PostgreSQL via Prisma ORM for relational data (notes, tags, spaces, users)
- Meilisearch for full-text and semantic note search
- better-auth for authentication (email/password, magic link, OAuth)
- Creem as the default payment provider (optional Stripe/Paddle adapters)
- Standalone Node.js Worker for PostgreSQL-backed background jobs
- BlockNote for the block-based note editor
Key Directories
| Path | Purpose |
|---|---|
apps/web/app/[locale]/ | Public and authenticated routes |
apps/web/app/api/ | REST and streaming API endpoints |
apps/web/components/notes/ | Note list, detail, and editor UI |
apps/worker/ | Queue polling, lease renewal, health, and shutdown |
packages/database/prisma/schema.prisma | Database schema |
packages/jobs/ | Queue protocol, schedulers, handlers, and registry |
apps/web/db/services/ | Web database access layer |
apps/web/lib/ | Server Actions, AI, search, and utilities |
apps/web/messages/ | i18n translation files (en, zh) |
Data Flow: Saving a Note
- User saves via browser extension, paste, or upload.
- An API route in
apps/web/app/api/notes/creates theNoteandBlockrecords. - A scheduler in
@keepflash/jobswrites a durable pending task to PostgreSQL. apps/workerclaims the task directly, holds a resource lease, and renews it while running.- The shared handler performs AI tagging, embedding, search projection, or Auto Wiki work and commits the outcome.
The queue is PostgreSQL-only. The Worker exposes /health/live and /health/ready; production processes are managed with the root pm2:worker:start, pm2:worker:reload, and pm2:worker:logs commands.
Search Architecture
KeepFlash uses Meilisearch for search with two modes:
- Full-text search: keyword matching across note title, body, and metadata
- Semantic search: vector similarity via embeddings (Plus/Pro plans)
Embeddings and search projections are scheduled through @keepflash/jobs.
AI Processing
AI features use the providers in lib/ai/providers/. The chat endpoint at app/api/ai/chat/stream/ uses a two-stage LangGraph pipeline:
- A planner model (not billed to users) handles tool calls
- The user-selected model generates the final answer
- Credits are deducted based on actual token usage of the final model only
Auto Wiki
Auto Wiki runs as a chain of durable Worker tasks. Shared handlers evaluate topic creation and compilation, while per-plan limits are enforced before page creation.
Operational rollback redeploys the previous Worker build; there is no legacy executor to restore.