How kripu77/prompt-map works
1. High-level shape
- This is a Next.js App Router application centered on one product workflow: turn a user prompt into a visual mind map.
- The architecture splits cleanly into three layers: UI/components, client-side state/hooks, and server/API services backed by PostgreSQL and LLM integrations.
2. Primary user journey
- The main entry points are app/page.tsx for the mind map experience and app/signin/page.tsx for authentication.
- A user enters a topic, the client triggers generation, the server calls AI services, and the result is rendered either as a streaming mind map or as a fully built React Flow graph.
3. Server-side route layer
- API routes live under app/api/* and act as the boundary for all backend operations.
- Major route groups are:
- mindmap/generate, mindmap/stream, mindmap/topic-shift for AI generation workflows
- threads for saved mind map/thread CRUD
- user/onboarding and user/settings for profile-related persistence
- auth/[...nextauth] for NextAuth session management
- analytics/anonymous-mindmap for anonymous tracking
- health for service monitoring
4. Business logic/services layer
- The route handlers delegate to service modules in lib/api/services/*.
- These services encapsulate the application’s actual behavior: mind map generation, streaming generation, threads persistence, onboarding, and anonymous analytics.
- This keeps the route handlers thin and makes the service layer the main orchestration boundary.
5. AI generation pipeline
- AI integration is implemented under lib/api/llm/*.
- client.ts and streaming-client.ts are the integration points for model calls, while prompts/mindmap-prompts.ts defines the prompt templates.
- The generation path can optionally use the web search tool in lib/tools/web-search-tool.tsx for current information, which materially changes how prompts are enriched before generation.
6. Mind map rendering and transformation
- The server response is transformed into visualization-friendly structures using utilities such as lib/parsers/markdown-to-reactflow.ts, lib/mindmap-utils.ts, and tree/layout helpers in lib/utils/*.
- The UI supports two rendering modes:
- a React Flow-based node graph under components/features/mindmap/views/react-flow
- a streaming view under components/features/mindmap/views/streaming-mindmap-view.tsx
- This separation shows a pipeline from AI text/structured output to graph layout and interactive rendering.
7. Client state and interaction model
- Client behavior is coordinated through hooks in hooks/* and Zustand-like stores in lib/stores/*.
- Key state domains include mind map data, reasoning panel visibility, side panel state, sidebar state, thread state, and onboarding state.
- Hooks such as use-mindmap-generation, use-streaming-mindmap, use-mindmap-data, and use-threads bridge UI actions to API calls and shared state.
8. Feature composition in the UI
- The components/features/mindmap/* tree is the main product UI, with submodules for controls, dialogs, editors, panels, and views.
- The editor stack includes rich-text, equation handling, code highlighting, toolbar actions, and custom link/citation rendering, which implies the mind map content is not just plain text nodes.
- Supporting feature areas include auth UI, onboarding walkthroughs, thread sidebar controls, and settings modal flows.
9. Persistence and database boundary
- Persistence is handled with PostgreSQL through Drizzle ORM.
- Schema and DB access live under lib/db/*, with migration history split between migrations/* and lib/db/migrations/*.
- The stored data model includes user settings, threads/mind maps, onboarding-related state, and a separate anonymous mind map table for non-authenticated usage.
10. Authentication and user context
- Authentication is built around NextAuth via app/api/auth/[...nextauth]/route.ts and lib/auth.ts.
- Session context is provided on the client through components/features/auth/session-provider.tsx and related providers.
- Middleware and auth-aware UI providers indicate that access to save/view personalized data is gated by signed-in session state.
11. Analytics and anonymous usage
- Anonymous users are not ignored; they have a dedicated analytics path in app/api/analytics/anonymous-mindmap/route.ts.
- The README confirms this data is stored separately and excludes personally identifiable information.
- This creates a distinct data boundary between authenticated product data and lightweight anonymous telemetry/storage.
12. Layout, theming, and cross-cutting concerns
- Shared app scaffolding is in app/layout.tsx, with UI chrome in components/layout/*.
- The app supports theme switching and responsive behavior through theme providers, toggles, and Tailwind-based styling.
- Sentry configs and instrumentation.ts show observability/error tracking as a cross-cutting concern rather than a product feature.
13. External service dependencies
- The main external dependencies that matter architecturally are NextAuth, PostgreSQL, Drizzle ORM, the AI/LLM provider, and optional Exa web search.
- React Flow and Markdown/ProseMirror-style editor tooling shape how generated content is represented and edited in the UI.
14. Diagramming summary
- If you draw this architecture, place the user interface on one side, the Next.js route layer in the middle, and the service/LLM/database layer on the other.
- The primary flows are: prompt input → generation API → AI service/web search → parsed mind map data → interactive graph/editor; and save/login/settings flows → authenticated API routes → PostgreSQL.
Main entry points: use-mindmap-data.ts Data hooks · mindmap-service.ts Mindmap service · page.tsx Mindmap app · index.ts Mindmap UI
Components 24
UI
App routes and feature components for the mind map product
- Mindmap app · Main mind map experience entry point
app/page.tsx - Sign in · Authentication entry page
app/signin/page.tsx - Mindmap UI · Controls, panels, dialogs, editors, and views for the product workflow
components/features/mindmap/index.ts - Graph view · Interactive React Flow mind map renderer
components/features/mindmap/views/react-flow/ReactFlowMindmapView.tsx - Streaming view · Incremental mind map rendering during generation
components/features/mindmap/views/streaming-mindmap-view.tsx - Auth UI · Session provider and sign-in form
components/features/auth/index.ts
Client State
Hooks and stores coordinating browser-side behavior
- Generation hooks · Prompt, streaming, and generation orchestration in the browser
hooks/use-mindmap-generation.ts - Data hooks · Thread, settings, onboarding, and mind map state bridges
hooks/use-mindmap-data.ts - App stores · Shared state for mind map, threads, panels, and sidebar
lib/stores/mindmap-store.ts
Server API
Next.js route handlers and business services
- Mindmap API · Generation and topic-shift route handlers
app/api/mindmap/generate/route.ts - Threads API · Saved mind map and thread CRUD routes
app/api/threads/route.ts - User API · Onboarding and settings persistence routes
app/api/user/settings/route.ts - Auth API · NextAuth session route
app/api/auth/[...nextauth]/route.ts - Mindmap service · Core orchestration for generation and formatting
lib/api/services/mindmap-service.ts - Streaming service · Streaming generation orchestration
lib/api/services/streaming-mindmap-service.ts - Threads service · Persistence and retrieval for saved threads
lib/api/services/threads-service.ts - LLM client · Model call integration and prompt execution
lib/api/llm/client.ts - Web search · Optional search tool used to enrich generation
lib/tools/web-search-tool.tsx - Graph transform · Markdown and tree/layout conversion into React Flow data
lib/parsers/markdown-to-reactflow.ts
Data
Database schema, migrations, and persistence
- Postgres schema · Drizzle schema and DB access boundary
lib/db/schema.ts - Migrations · Database migration files and schema evolution
migrations/schema.ts
Infra
Authentication, observability, and app-wide providers
- Auth core · NextAuth configuration and session logic
lib/auth.ts - App providers · Theme, query, auth sidebar, and session providers
lib/providers/query-provider.tsx - Observability · Sentry and runtime instrumentation
instrumentation.ts
Connections 26
- Mindmap app → Mindmap UI: uses · Main page composes the product feature shell
- Mindmap app → Generation hooks: drives · Page interactions trigger generation hooks
- Mindmap app → Data hooks: reads state · Page uses shared client-side data and thread state
- Sign in → Auth UI: renders · Sign-in page uses auth feature components
- Mindmap UI → Graph view: renders · Feature shell can display the interactive graph view
- Mindmap UI → Streaming view: renders · Feature shell can display the streaming view
- Generation hooks → Mindmap API: calls · Generation hooks invoke mind map API routes
- Data hooks → Threads API: calls · Client data hooks manage saved threads through API
- Data hooks → User API: calls · Client data hooks persist onboarding and settings
- Data hooks → App stores: syncs · Hooks bridge UI events and shared stores
- Mindmap API → Mindmap service: delegates · Route handlers stay thin and hand off to services
- Mindmap API → Streaming service: delegates · Streaming route uses streaming service
- Threads API → Threads service: delegates · Thread routes use the threads service
- User API → Postgres schema: persists · User routes write settings and onboarding state
- Threads API → Postgres schema: persists · Thread routes read and write PostgreSQL state
- Mindmap service → LLM client: invokes · Mind map generation calls the model client
- Streaming service → LLM client: streams via · Streaming generation uses the streaming LLM client
- Mindmap service → Web search: optionally enriches · Generation can incorporate external search results
- Mindmap service → Graph transform: formats · Generated content is transformed into graph-ready data
- Graph transform → Graph view: feeds · Transformation output drives the React Flow renderer
- LLM client → Streaming view: feeds · Streaming responses update the streaming mind map view
- Auth UI → Auth API: signs in via · Auth UI relies on the NextAuth route
- Auth API → Auth core: uses · Route is backed by shared auth configuration
- App providers → Auth UI: provides · Session and UI providers supply auth context
- Observability → Mindmap app: wraps · Instrumentation supports app runtime monitoring
- Migrations → Postgres schema: evolves · Migration history tracks the database schema