# scaredcube/mukyuai architecture

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

- Interactive diagram: https://gitdiagram.com/scaredcube/mukyuai
- Repository: https://github.com/scaredcube/mukyuai

## Overview

Mukyu AI is a learning-focused AI application, delivered through a Next.js interface and optionally wrapped in Electron. The main workflow is to create a learning session, generate a chapter plan, study within a chapter through streamed AI chat, and retain messages and summaries. Separate branches support floating questions, file understanding, and session knowledge-base retrieval. The sampled routes show these orchestration boundaries; several other capabilities are documented in the README but their route implementations were not sampled, so their internal wiring is represented only where supported by the tree.

Main entry points: [`src/lib/db.ts`](https://github.com/scaredcube/mukyuai/blob/main/src/lib/db.ts) (Application state), [`src/lib/llm.ts`](https://github.com/scaredcube/mukyuai/blob/main/src/lib/llm.ts) (Model integration), [`src/lib/context.ts`](https://github.com/scaredcube/mukyuai/blob/main/src/lib/context.ts) (Context assembly), [`src/app/api/planning/route.ts`](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/planning/route.ts) (Planning chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learning experience"]
  node_app["Learning UI<br/>[page.tsx]"]
  node_session_ui["Session views<br/>[page.tsx]"]
  node_plan_ui["Plan view<br/>[page.tsx]"]
  node_chat_ui["Chat interface<br/>[ChatArea.tsx]"]
  node_timeline["Conversation timeline"]
  node_knowledge_ui["Knowledge panel<br/>[KnowledgePanel.tsx]"]
  node_settings["Provider settings<br/>[page.tsx]"]
end

subgraph group_workflows["Learning workflows"]
  node_sessions_api["Session management<br/>[route.ts]"]
  node_planning_api["Planning chat<br/>[route.ts]"]
  node_plan_generation["Chapter plan generation<br/>[route.ts]"]
  node_chapters_api["Chapter management<br/>[route.ts]"]
  node_chat_api["Chapter chat<br/>[route.ts]"]
  node_message_api["Message edits<br/>[route.ts]"]
  node_summarize_api["Chapter summaries<br/>[route.ts]"]
  node_float_api["Floating query<br/>[route.ts]"]
end

subgraph group_knowledge["Knowledge and files"]
  node_upload_api["Attachment upload<br/>[route.ts]"]
  node_document_parser["Document parsing<br/>[document-parser.ts]"]
  node_knowledge_api["Knowledge ingestion<br/>[route.ts]"]
  node_chunker["Text chunking<br/>[chunker.ts]"]
  node_embedding["Embedding service<br/>[embedding.ts]"]
  node_retriever["Context retrieval<br/>[retriever.ts]"]
  node_image_api["Image understanding<br/>[route.ts]"]
end

subgraph group_services["AI and state"]
  node_llm["Model integration<br/>[llm.ts]"]
  node_context["Context assembly<br/>[context.ts]"]
  node_database[("Application state<br/>[db.ts]")]
  node_model_api["Model discovery<br/>[route.ts]"]
end

node_learner(("Learner"))
node_model_providers(("AI providers"))
node_electron["Desktop host<br/>[main.js]"]

node_learner -->|"uses"| node_app
node_app -->|"manages sessions"| node_sessions_api
node_sessions_api -->|"reads and writes"| node_database
node_session_ui -->|"sends planning chat"| node_planning_api
node_planning_api -->|"stores messages"| node_database
node_planning_api -->|"retrieves context"| node_retriever
node_planning_api -->|"assembles prompts"| node_context
node_planning_api -->|"streams response"| node_llm
node_plan_ui -->|"requests plan"| node_plan_generation
node_plan_generation -->|"reads and creates chapters"| node_database
node_plan_generation -->|"assembles plan context"| node_context
node_plan_generation -->|"generates plan"| node_llm
node_session_ui -->|"manages chapters"| node_chapters_api
node_chapters_api -->|"reads and writes"| node_database
node_chat_ui -->|"sends chapter chat"| node_chat_api
node_chat_ui -->|"edits messages"| node_message_api
node_chat_api -->|"stores messages"| node_database
node_chat_api -->|"retrieves context"| node_retriever
node_chat_api -->|"assembles prompts"| node_context
node_chat_api -->|"streams response"| node_llm
node_message_api -->|"reads and updates"| node_database
node_message_api -->|"rebuilds prompts"| node_context
node_message_api -->|"regenerates reply"| node_llm
node_session_ui -->|"requests summary"| node_summarize_api
node_summarize_api -->|"reads messages and saves summary"| node_database
node_summarize_api -->|"assembles summary prompt"| node_context
node_summarize_api -->|"generates summary"| node_llm
node_session_ui -->|"asks quick question"| node_float_api
node_float_api -->|"assembles context"| node_context
node_float_api -->|"streams response"| node_llm
node_chat_ui -->|"uploads attachments"| node_upload_api
node_upload_api -->|"extracts document text"| node_document_parser
node_knowledge_ui -->|"imports study material"| node_knowledge_api
node_knowledge_api -->|"extracts text"| node_document_parser
node_knowledge_api -->|"splits text"| node_chunker
node_knowledge_api -->|"vectorizes chunks"| node_embedding
node_knowledge_api -->|"stores knowledge"| node_database
node_retriever -->|"embeds query"| node_embedding
node_retriever -->|"searches chunks"| node_database
node_chat_ui -.->|"requests image analysis"| node_image_api
node_image_api -->|"interprets image"| node_llm
node_settings -->|"lists models"| node_model_api
node_model_api -->|"queries models"| node_model_providers
node_llm -->|"sends prompts"| node_model_providers
node_electron -->|"hosts interface"| node_app

click node_app "https://github.com/scaredcube/mukyuai/blob/main/src/app/page.tsx"
click node_session_ui "https://github.com/scaredcube/mukyuai/blob/main/src/app/session/%5Bid%5D/page.tsx"
click node_plan_ui "https://github.com/scaredcube/mukyuai/blob/main/src/app/session/%5Bid%5D/plan/page.tsx"
click node_chat_ui "https://github.com/scaredcube/mukyuai/blob/main/src/components/chat/ChatArea.tsx"
click node_timeline "https://github.com/scaredcube/mukyuai/blob/main/src/components/chat/ConversationTimeline.tsx"
click node_knowledge_ui "https://github.com/scaredcube/mukyuai/blob/main/src/components/session/KnowledgePanel.tsx"
click node_settings "https://github.com/scaredcube/mukyuai/blob/main/src/app/settings/page.tsx"
click node_sessions_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/sessions/route.ts"
click node_planning_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/planning/route.ts"
click node_plan_generation "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/generate-plan/route.ts"
click node_chapters_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/chapters/route.ts"
click node_chat_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/chat/route.ts"
click node_message_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/messages/route.ts"
click node_summarize_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/summarize/route.ts"
click node_float_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/float-query/route.ts"
click node_upload_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/upload/route.ts"
click node_document_parser "https://github.com/scaredcube/mukyuai/blob/main/src/lib/document-parser.ts"
click node_knowledge_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/knowledge/route.ts"
click node_chunker "https://github.com/scaredcube/mukyuai/blob/main/src/lib/chunker.ts"
click node_embedding "https://github.com/scaredcube/mukyuai/blob/main/src/lib/embedding.ts"
click node_retriever "https://github.com/scaredcube/mukyuai/blob/main/src/lib/retriever.ts"
click node_image_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/understand-image/route.ts"
click node_llm "https://github.com/scaredcube/mukyuai/blob/main/src/lib/llm.ts"
click node_context "https://github.com/scaredcube/mukyuai/blob/main/src/lib/context.ts"
click node_database "https://github.com/scaredcube/mukyuai/blob/main/src/lib/db.ts"
click node_model_api "https://github.com/scaredcube/mukyuai/blob/main/src/app/api/models/route.ts"
click node_electron "https://github.com/scaredcube/mukyuai/blob/main/electron/main.js"

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,node_session_ui,node_plan_ui,node_chat_ui,node_timeline,node_knowledge_ui,node_settings toneBlue
class node_sessions_api,node_planning_api,node_plan_generation,node_chapters_api,node_chat_api,node_message_api,node_summarize_api,node_float_api toneAmber
class node_upload_api,node_document_parser,node_knowledge_api,node_chunker,node_embedding,node_retriever,node_image_api toneMint
class node_llm,node_context,node_database,node_model_api toneRose
class node_learner,node_model_providers toneIndigo
class node_electron toneTeal
```

## Components

### Learning experience

- [Learning UI](https://github.com/scaredcube/mukyuai/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Session views](https://github.com/scaredcube/mukyuai/blob/main/src/app/session/%5Bid%5D/page.tsx): `src/app/session/[id]/page.tsx`
- [Plan view](https://github.com/scaredcube/mukyuai/blob/main/src/app/session/%5Bid%5D/plan/page.tsx): `src/app/session/[id]/plan/page.tsx`
- [Chat interface](https://github.com/scaredcube/mukyuai/blob/main/src/components/chat/ChatArea.tsx): `src/components/chat/ChatArea.tsx`
- [Conversation timeline](https://github.com/scaredcube/mukyuai/blob/main/src/components/chat/ConversationTimeline.tsx): `src/components/chat/ConversationTimeline.tsx`
- [Knowledge panel](https://github.com/scaredcube/mukyuai/blob/main/src/components/session/KnowledgePanel.tsx): `src/components/session/KnowledgePanel.tsx`
- [Provider settings](https://github.com/scaredcube/mukyuai/blob/main/src/app/settings/page.tsx): `src/app/settings/page.tsx`

### Learning workflows

- [Session management](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/sessions/route.ts): `src/app/api/sessions/route.ts`
- [Planning chat](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/planning/route.ts): `src/app/api/planning/route.ts`
- [Chapter plan generation](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/generate-plan/route.ts): `src/app/api/generate-plan/route.ts`
- [Chapter management](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/chapters/route.ts): `src/app/api/chapters/route.ts`
- [Chapter chat](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Message edits](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/messages/route.ts): `src/app/api/messages/route.ts`
- [Chapter summaries](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/summarize/route.ts): `src/app/api/summarize/route.ts`
- [Floating query](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/float-query/route.ts): `src/app/api/float-query/route.ts`

### Knowledge and files

- [Attachment upload](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/upload/route.ts): `src/app/api/upload/route.ts`
- [Document parsing](https://github.com/scaredcube/mukyuai/blob/main/src/lib/document-parser.ts): `src/lib/document-parser.ts`
- [Knowledge ingestion](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/knowledge/route.ts): `src/app/api/knowledge/route.ts`
- [Text chunking](https://github.com/scaredcube/mukyuai/blob/main/src/lib/chunker.ts): `src/lib/chunker.ts`
- [Embedding service](https://github.com/scaredcube/mukyuai/blob/main/src/lib/embedding.ts): `src/lib/embedding.ts`
- [Context retrieval](https://github.com/scaredcube/mukyuai/blob/main/src/lib/retriever.ts): `src/lib/retriever.ts`
- [Image understanding](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/understand-image/route.ts): `src/app/api/understand-image/route.ts`

### AI and state

- [Model integration](https://github.com/scaredcube/mukyuai/blob/main/src/lib/llm.ts): `src/lib/llm.ts`
- [Context assembly](https://github.com/scaredcube/mukyuai/blob/main/src/lib/context.ts): `src/lib/context.ts`
- [Application state](https://github.com/scaredcube/mukyuai/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Model discovery](https://github.com/scaredcube/mukyuai/blob/main/src/app/api/models/route.ts): `src/app/api/models/route.ts`

### Other components

- **Learner**
- **AI providers**
- [Desktop host](https://github.com/scaredcube/mukyuai/blob/main/electron/main.js): `electron/main.js`

## Connections

- Learner → Learning UI: uses
- Learning UI → Session management: manages sessions
- Session management → Application state: reads and writes
- Session views → Planning chat: sends planning chat
- Planning chat → Application state: stores messages
- Planning chat → Context retrieval: retrieves context
- Planning chat → Context assembly: assembles prompts
- Planning chat → Model integration: streams response
- Plan view → Chapter plan generation: requests plan
- Chapter plan generation → Application state: reads and creates chapters
- Chapter plan generation → Context assembly: assembles plan context
- Chapter plan generation → Model integration: generates plan
- Session views → Chapter management: manages chapters
- Chapter management → Application state: reads and writes
- Chat interface → Chapter chat: sends chapter chat
- Chat interface → Message edits: edits messages
- Chapter chat → Application state: stores messages
- Chapter chat → Context retrieval: retrieves context
- Chapter chat → Context assembly: assembles prompts
- Chapter chat → Model integration: streams response
- Message edits → Application state: reads and updates
- Message edits → Context assembly: rebuilds prompts
- Message edits → Model integration: regenerates reply
- Session views → Chapter summaries: requests summary
- Chapter summaries → Application state: reads messages and saves summary
- Chapter summaries → Context assembly: assembles summary prompt
- Chapter summaries → Model integration: generates summary
- Session views → Floating query: asks quick question
- Floating query → Context assembly: assembles context
- Floating query → Model integration: streams response
- Chat interface → Attachment upload: uploads attachments
- Attachment upload → Document parsing: extracts document text
- Knowledge panel → Knowledge ingestion: imports study material
- Knowledge ingestion → Document parsing: extracts text
- Knowledge ingestion → Text chunking: splits text
- Knowledge ingestion → Embedding service: vectorizes chunks
- Knowledge ingestion → Application state: stores knowledge
- Context retrieval → Embedding service: embeds query
- Context retrieval → Application state: searches chunks
- Chat interface → Image understanding: requests image analysis
- Image understanding → Model integration: interprets image
- Provider settings → Model discovery: lists models
- Model discovery → AI providers: queries models
- Model integration → AI providers: sends prompts
- Desktop host → Learning UI: hosts interface