# kripu77/prompt-map architecture

> Architecture diagram of the GitHub repository kripu77/prompt-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kripu77/prompt-map
- Repository: https://github.com/kripu77/prompt-map

## Overview

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: [`hooks/use-mindmap-data.ts`](https://github.com/kripu77/prompt-map/blob/main/hooks/use-mindmap-data.ts) (Data hooks), [`lib/api/services/mindmap-service.ts`](https://github.com/kripu77/prompt-map/blob/main/lib/api/services/mindmap-service.ts) (Mindmap service), [`app/page.tsx`](https://github.com/kripu77/prompt-map/blob/main/app/page.tsx) (Mindmap app), [`components/features/mindmap/index.ts`](https://github.com/kripu77/prompt-map/blob/main/components/features/mindmap/index.ts) (Mindmap UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_app_page["Mindmap app<br/>next page<br/>[page.tsx]"]
  node_signin_page["Sign in<br/>next page<br/>[page.tsx]"]
  node_mindmap_features["Mindmap UI<br/>feature shell<br/>[index.ts]"]
  node_reactflow_view["Graph view<br/>rendering view"]
  node_stream_view["Streaming view"]
  node_auth_ui["Auth UI<br/>auth feature<br/>[index.ts]"]
end

subgraph group_client["Client State"]
  node_hooks_gen["Generation hooks<br/>client hooks"]
  node_hooks_data["Data hooks<br/>client hooks"]
  node_stores["App stores<br/>state stores<br/>[mindmap-store.ts]"]
end

subgraph group_server["Server API"]
  node_api_mindmap["Mindmap API<br/>route group<br/>[route.ts]"]
  node_api_threads["Threads API<br/>route group<br/>[route.ts]"]
  node_api_user["User API<br/>route group<br/>[route.ts]"]
  node_api_auth["Auth API<br/>auth route<br/>[route.ts]"]
  node_services_mindmap["Mindmap service<br/>service layer<br/>[mindmap-service.ts]"]
  node_services_stream["Streaming service<br/>service layer"]
  node_services_threads["Threads service<br/>service layer<br/>[threads-service.ts]"]
  node_llm_client["LLM client<br/>ai integration<br/>[client.ts]"]
  node_web_search["Web search<br/>tooling"]
  node_parser_utils["Graph transform<br/>transform utils"]
end

subgraph group_data["Data"]
  node_db_schema[("Postgres schema<br/>database layer<br/>[schema.ts]")]
  node_db_migrations["Migrations<br/>migration history<br/>[schema.ts]"]
end

subgraph group_infra["Infra"]
  node_auth_core["Auth core<br/>auth integration<br/>[auth.ts]"]
  node_providers["App providers<br/>client providers<br/>[query-provider.tsx]"]
  node_observability["Observability<br/>cross-cutting<br/>[instrumentation.ts]"]
end

node_app_page -->|"uses"| node_mindmap_features
node_app_page -->|"drives"| node_hooks_gen
node_app_page -->|"reads state"| node_hooks_data
node_signin_page -->|"renders"| node_auth_ui
node_mindmap_features -->|"renders"| node_reactflow_view
node_mindmap_features -->|"renders"| node_stream_view
node_hooks_gen -->|"calls"| node_api_mindmap
node_hooks_data -->|"calls"| node_api_threads
node_hooks_data -->|"calls"| node_api_user
node_hooks_data -->|"syncs"| node_stores
node_api_mindmap -->|"delegates"| node_services_mindmap
node_api_mindmap -->|"delegates"| node_services_stream
node_api_threads -->|"delegates"| node_services_threads
node_api_user -->|"persists"| node_db_schema
node_api_threads -->|"persists"| node_db_schema
node_services_mindmap -->|"invokes"| node_llm_client
node_services_stream -->|"streams via"| node_llm_client
node_services_mindmap -.->|"optionally enriches"| node_web_search
node_services_mindmap -->|"formats"| node_parser_utils
node_parser_utils -->|"feeds"| node_reactflow_view
node_llm_client -->|"feeds"| node_stream_view
node_auth_ui -->|"signs in via"| node_api_auth
node_api_auth -->|"uses"| node_auth_core
node_providers -->|"provides"| node_auth_ui
node_observability -.->|"wraps"| node_app_page
node_db_migrations -.->|"evolves"| node_db_schema

click node_app_page "https://github.com/kripu77/prompt-map/blob/main/app/page.tsx"
click node_signin_page "https://github.com/kripu77/prompt-map/blob/main/app/signin/page.tsx"
click node_mindmap_features "https://github.com/kripu77/prompt-map/blob/main/components/features/mindmap/index.ts"
click node_reactflow_view "https://github.com/kripu77/prompt-map/blob/main/components/features/mindmap/views/react-flow/ReactFlowMindmapView.tsx"
click node_stream_view "https://github.com/kripu77/prompt-map/blob/main/components/features/mindmap/views/streaming-mindmap-view.tsx"
click node_auth_ui "https://github.com/kripu77/prompt-map/blob/main/components/features/auth/index.ts"
click node_hooks_gen "https://github.com/kripu77/prompt-map/blob/main/hooks/use-mindmap-generation.ts"
click node_hooks_data "https://github.com/kripu77/prompt-map/blob/main/hooks/use-mindmap-data.ts"
click node_stores "https://github.com/kripu77/prompt-map/blob/main/lib/stores/mindmap-store.ts"
click node_api_mindmap "https://github.com/kripu77/prompt-map/blob/main/app/api/mindmap/generate/route.ts"
click node_api_threads "https://github.com/kripu77/prompt-map/blob/main/app/api/threads/route.ts"
click node_api_user "https://github.com/kripu77/prompt-map/blob/main/app/api/user/settings/route.ts"
click node_api_auth "https://github.com/kripu77/prompt-map/blob/main/app/api/auth/[...nextauth]/route.ts"
click node_services_mindmap "https://github.com/kripu77/prompt-map/blob/main/lib/api/services/mindmap-service.ts"
click node_services_stream "https://github.com/kripu77/prompt-map/blob/main/lib/api/services/streaming-mindmap-service.ts"
click node_services_threads "https://github.com/kripu77/prompt-map/blob/main/lib/api/services/threads-service.ts"
click node_llm_client "https://github.com/kripu77/prompt-map/blob/main/lib/api/llm/client.ts"
click node_web_search "https://github.com/kripu77/prompt-map/blob/main/lib/tools/web-search-tool.tsx"
click node_parser_utils "https://github.com/kripu77/prompt-map/blob/main/lib/parsers/markdown-to-reactflow.ts"
click node_db_schema "https://github.com/kripu77/prompt-map/blob/main/lib/db/schema.ts"
click node_db_migrations "https://github.com/kripu77/prompt-map/blob/main/migrations/schema.ts"
click node_auth_core "https://github.com/kripu77/prompt-map/blob/main/lib/auth.ts"
click node_providers "https://github.com/kripu77/prompt-map/blob/main/lib/providers/query-provider.tsx"
click node_observability "https://github.com/kripu77/prompt-map/blob/main/instrumentation.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_page,node_signin_page,node_mindmap_features,node_reactflow_view,node_stream_view,node_auth_ui toneBlue
class node_hooks_gen,node_hooks_data,node_stores toneAmber
class node_api_mindmap,node_api_threads,node_api_user,node_api_auth,node_services_mindmap,node_services_stream,node_services_threads,node_llm_client,node_web_search,node_parser_utils toneMint
class node_db_schema,node_db_migrations toneRose
class node_auth_core,node_providers,node_observability toneIndigo
```

## Components

### UI

App routes and feature components for the mind map product

- [Mindmap app](https://github.com/kripu77/prompt-map/blob/main/app/page.tsx): next page · Main mind map experience entry point · `app/page.tsx`
- [Sign in](https://github.com/kripu77/prompt-map/blob/main/app/signin/page.tsx): next page · Authentication entry page · `app/signin/page.tsx`
- [Mindmap UI](https://github.com/kripu77/prompt-map/blob/main/components/features/mindmap/index.ts): feature shell · Controls, panels, dialogs, editors, and views for the product workflow · `components/features/mindmap/index.ts`
- [Graph view](https://github.com/kripu77/prompt-map/blob/main/components/features/mindmap/views/react-flow/ReactFlowMindmapView.tsx): rendering view · Interactive React Flow mind map renderer · `components/features/mindmap/views/react-flow/ReactFlowMindmapView.tsx`
- [Streaming view](https://github.com/kripu77/prompt-map/blob/main/components/features/mindmap/views/streaming-mindmap-view.tsx): streaming view · Incremental mind map rendering during generation · `components/features/mindmap/views/streaming-mindmap-view.tsx`
- [Auth UI](https://github.com/kripu77/prompt-map/blob/main/components/features/auth/index.ts): auth feature · Session provider and sign-in form · `components/features/auth/index.ts`

### Client State

Hooks and stores coordinating browser-side behavior

- [Generation hooks](https://github.com/kripu77/prompt-map/blob/main/hooks/use-mindmap-generation.ts): client hooks · Prompt, streaming, and generation orchestration in the browser · `hooks/use-mindmap-generation.ts`
- [Data hooks](https://github.com/kripu77/prompt-map/blob/main/hooks/use-mindmap-data.ts): client hooks · Thread, settings, onboarding, and mind map state bridges · `hooks/use-mindmap-data.ts`
- [App stores](https://github.com/kripu77/prompt-map/blob/main/lib/stores/mindmap-store.ts): state 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](https://github.com/kripu77/prompt-map/blob/main/app/api/mindmap/generate/route.ts): route group · Generation and topic-shift route handlers · `app/api/mindmap/generate/route.ts`
- [Threads API](https://github.com/kripu77/prompt-map/blob/main/app/api/threads/route.ts): route group · Saved mind map and thread CRUD routes · `app/api/threads/route.ts`
- [User API](https://github.com/kripu77/prompt-map/blob/main/app/api/user/settings/route.ts): route group · Onboarding and settings persistence routes · `app/api/user/settings/route.ts`
- [Auth API](https://github.com/kripu77/prompt-map/blob/main/app/api/auth/[...nextauth]/route.ts): auth route · NextAuth session route · `app/api/auth/[...nextauth]/route.ts`
- [Mindmap service](https://github.com/kripu77/prompt-map/blob/main/lib/api/services/mindmap-service.ts): service layer · Core orchestration for generation and formatting · `lib/api/services/mindmap-service.ts`
- [Streaming service](https://github.com/kripu77/prompt-map/blob/main/lib/api/services/streaming-mindmap-service.ts): service layer · Streaming generation orchestration · `lib/api/services/streaming-mindmap-service.ts`
- [Threads service](https://github.com/kripu77/prompt-map/blob/main/lib/api/services/threads-service.ts): service layer · Persistence and retrieval for saved threads · `lib/api/services/threads-service.ts`
- [LLM client](https://github.com/kripu77/prompt-map/blob/main/lib/api/llm/client.ts): ai integration · Model call integration and prompt execution · `lib/api/llm/client.ts`
- [Web search](https://github.com/kripu77/prompt-map/blob/main/lib/tools/web-search-tool.tsx): tooling · Optional search tool used to enrich generation · `lib/tools/web-search-tool.tsx`
- [Graph transform](https://github.com/kripu77/prompt-map/blob/main/lib/parsers/markdown-to-reactflow.ts): transform utils · Markdown and tree/layout conversion into React Flow data · `lib/parsers/markdown-to-reactflow.ts`

### Data

Database schema, migrations, and persistence

- [Postgres schema](https://github.com/kripu77/prompt-map/blob/main/lib/db/schema.ts): database layer · Drizzle schema and DB access boundary · `lib/db/schema.ts`
- [Migrations](https://github.com/kripu77/prompt-map/blob/main/migrations/schema.ts): migration history · Database migration files and schema evolution · `migrations/schema.ts`

### Infra

Authentication, observability, and app-wide providers

- [Auth core](https://github.com/kripu77/prompt-map/blob/main/lib/auth.ts): auth integration · NextAuth configuration and session logic · `lib/auth.ts`
- [App providers](https://github.com/kripu77/prompt-map/blob/main/lib/providers/query-provider.tsx): client providers · Theme, query, auth sidebar, and session providers · `lib/providers/query-provider.tsx`
- [Observability](https://github.com/kripu77/prompt-map/blob/main/instrumentation.ts): cross-cutting · Sentry and runtime instrumentation · `instrumentation.ts`

## Connections

- 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
