01
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)
- Cloudflare Workers for scheduled background jobs
- BlockNote for the block-based note editor
Key Directories
| Path | Purpose |
|---|---|
app/[locale]/ | Public and authenticated routes |
app/api/ | REST and streaming API endpoints |
components/landing/ | Homepage section components |
components/notes/ | Note list, detail, and editor UI |
db/prisma/schema.prisma | Database schema |
db/services/ | Database access layer |
lib/actions/ | Server Actions used by client components |
lib/ai/ | AI provider wrappers, usage ledgers, streaming |
lib/search/ | Meilisearch client and index sync |
lib/marketing/ | Homepage content builders |
messages/ | i18n translation files (en, zh) |
workers/keepflash-cron/ | Cloudflare Worker for scheduled tasks |
Data Flow: Saving a Note
- User saves via browser extension, paste, or upload.
- API route in
app/api/notes/creates aNoterecord and associatedBlockrecords. - A background analysis task is queued.
- The Cloudflare Worker (
keepflash-cron) polls and triggers the analysis endpoint. - Analysis runs: AI tagging, embedding generation, Meilisearch index update, Auto Wiki evaluation.
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 are generated asynchronously and scheduled through lib/embedding-scheduler.ts.
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 an async job via the cron worker. When enough related notes accumulate around a topic, lib/knowledge/ evaluates whether a Topic Page should be created or updated. Limits per plan are enforced via config/wiki-page-limits.ts.