# mahnduc/studymind-local-first architecture

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

- Interactive diagram: https://gitdiagram.com/mahnduc/studymind-local-first
- Repository: https://github.com/mahnduc/studymind-local-first

## Overview

1. **Overall shape**
   - This is a **Next.js + TypeScript** application built around a **local-first knowledge-management workflow**.
   - The core product flow is: ingest documents in the browser, store/manage them locally, search them semantically/lexically, generate quizzes and flashcards, then review progress with an AI assistant.

2. **Top-level runtime boundaries**
   - The app is organized as a **route-based UI** under `src/app`, using the Next.js App Router.
   - Most of the “data plane” appears to run **in the browser**, not on a traditional server backend: note taking, file storage, quiz history, and search all have local-oriented modules.
   - AI-assisted features are separated into service/hook layers so the UI can stay mostly declarative.

3. **Primary user-facing surfaces**
   - `src/app/dashboard` is the main product shell, with sections for **discover**, **collections**, **notes**, **notifications**, **OPFS explorer**, **timetable**, and **settings**.
   - `src/app/simple` is a separate **editor-centric sandbox/demo area**, centered on Tiptap-based rich text editing.
   - `src/app/intro` and the root landing pages provide onboarding and entry experience.

4. **Document ingestion and local file storage**
   - The repository strongly centers on **OPFS (Origin Private File System)** via `src/lib/opfs` and related hooks in `src/app/dashboard/discover/_hooks`.
   - Uploaded or ingested files are managed through browser-local APIs, then surfaced in file lists/viewers and likely persisted as local project assets.
   - This is the main boundary where external user content enters the system: file upload → local storage → parsing/search/quiz generation.

5. **Knowledge retrieval / RAG subsystem**
   - `src/lib/rag` contains the retrieval pipeline: **BM25 search**, markdown chunking, document-to-markdown conversion, QA generation, and a search API layer.
   - `src/hooks/useHybridSearch.ts` and `src/services/local-knowledge-search.service.ts` suggest a **hybrid retrieval strategy**, combining lexical search with higher-level query expansion or AI assistance.
   - `src/services/query-expand.service.ts` indicates query rewriting/expansion as part of search or assistant workflows.
   - Architecturally, this is the core “knowledge layer” connecting raw documents to answer generation and quiz creation.

6. **Quiz and practice loop**
   - Quiz functionality is split between reusable components in `src/components/quiz` and history/data helpers in `src/lib/quiz`.
   - The dashboard’s discover/collections areas include quiz summaries, quiz practice screens, and history views.
   - The flow is: document content or collections → quiz generation → practice UI → stored history → analytics/review.

7. **Learning assistant / agent subsystem**
   - `src/agent` contains a distinct agent architecture with **core orchestration**, **context**, **gateway**, and member logic such as `learning-strategist.ts`.
   - This is the system that analyzes outcomes and produces coaching-style feedback, consistent with the README’s “virtual companion” behavior.
   - UI-facing components like `LearningCoachPopup` and floating chat/history components connect the agent output back to the learner experience.

8. **Notes, graphing, and knowledge organization**
   - Notes and knowledge structure are handled through `src/components/floatingchat/knowledge-graph` and note-related dashboard pages.
   - The app turns study notes into a **knowledge graph / tree of knowledge** rather than a flat note list.
   - This subsystem sits between authoring and review: it organizes extracted concepts, relationships, and study artifacts into a navigable structure.

9. **Rich-text editor subsystem**
   - `src/app/simple` is a large self-contained editor stack based on **Tiptap**, with custom nodes, toolbar primitives, icons, hooks, and UI patterns.
   - This area includes image upload, markdown handling, theme toggles, and editor utility hooks.
   - It is architecturally separate from the learning dashboard, but likely serves as the composition layer for note creation and content authoring.

10. **State management and shared client-side services**
   - Shared state is kept in `src/stores` and reusable hooks under `src/hooks` and `src/app/.../_hooks`.
   - `editorStore.ts` and `profileStore.ts` suggest lightweight global client state rather than a heavy centralized backend model.
   - `src/utils/eventEmitter.ts` and `src/components/EventEmitterInitializer.tsx` indicate cross-component signaling, likely used to coordinate floating panels, notifications, or editor actions.

11. **Settings and API key handling**
   - `src/app/dashboard/settings/api-key` includes an API key API/service pair, which suggests credential management is a first-class concern.
   - This is important architecturally because it separates user-configured AI credentials from the rest of the local app state.
   - Settings pages for preferences and security imply the app expects per-user personalization and local privacy controls.

12. **Static assets, generated content, and docs**
   - `public/flashcards`, `public/info.json`, and `scripts/generate-manifest.mjs` show that some content is **prebuilt/generated** and shipped as static browser assets.
   - `public/docs` is a bundled documentation site, likely served as a static reference/manual alongside the app.
   - `public/coi-serviceworker.js` also suggests browser capability tuning for local file/worker behavior, which matters for offline or advanced browser APIs.

13. **Deployment and delivery**
   - `.github/workflows/deploy.yml` indicates an automated deployment pipeline, likely to a static hosting target.
   - Because the architecture is largely client-side and asset-driven, deployment is probably optimized for static distribution with browser-local persistence rather than server-side application state.

14. **How data moves through the system**
   - The key flow is: **user imports content → browser-local storage/OPFS → parsing/chunking/indexing → search/quiz generation → dashboard review → agent feedback and progress tracking**.
   - The main architectural boundary is between **local content management** and **AI-assisted computation**.
   - A good diagram should show the dashboard/UI on top, local browser storage and search/indexing in the middle, and agent/AI services as a separate computation layer fed by user content and quiz results.

Main entry points: [`src/app/dashboard/page.tsx`](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/page.tsx) (Dashboard), [`src/app/dashboard/discover/page.tsx`](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/discover/page.tsx) (Discover), [`src/components/LearningCoachPopup.tsx`](https://github.com/mahnduc/studymind-local-first/blob/main/src/components/LearningCoachPopup.tsx) (Coach UI), [`src/app/layout.tsx`](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/layout.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App surfaces"]
  node_root["App shell<br/>next-app-router<br/>[layout.tsx]"]
  node_landing["Landing<br/>entry pages<br/>[page.tsx]"]
  node_intro["Intro<br/>onboarding route<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>product shell<br/>[page.tsx]"]
  node_discover["Discover<br/>ingest + review UI<br/>[page.tsx]"]
  node_collections["Collections<br/>study library<br/>[page.tsx]"]
  node_notes["Notes<br/>note surface<br/>[page.tsx]"]
  node_settings["Settings<br/>preferences area<br/>[page.tsx]"]
end

subgraph group_data["Local knowledge"]
  node_opfs[("OPFS<br/>browser storage<br/>[opfsApis.ts]")]
  node_ingest["Ingest hooks<br/>file pipeline<br/>[useIngestFile.ts]"]
  node_rag["RAG layer<br/>retrieval pipeline<br/>[api.ts]"]
  node_hybrid["Hybrid search<br/>search service<br/>[useHybridSearch.ts]"]
  node_quiz["Quiz engine<br/>practice loop<br/>[history.ts]"]
end

subgraph group_agent["Assistant layer"]
  node_agentcore["Agent core<br/>orchestration<br/>[orchestrator.ts]"]
  node_strategist["Learning strategist<br/>coach member"]
  node_coach["Coach UI<br/>assistant surface"]
end

subgraph group_editor["Editor stack"]
  node_simple["Simple editor<br/>editor sandbox<br/>[page.tsx]"]
  node_tiptap["Tiptap UI<br/>rich-text stack<br/>[simple-editor.tsx]"]
end

subgraph group_shared["Shared client state"]
  node_knowledgegraph["Knowledge graph<br/>note structure<br/>[index.tsx]"]
  node_stores["Client stores<br/>global state<br/>[editorStore.ts]"]
  node_events(("Event bus<br/>signals<br/>[eventEmitter.ts]"))
end

node_root -->|"routes"| node_landing
node_root -->|"routes"| node_intro
node_root -->|"routes"| node_dashboard
node_dashboard -->|"section"| node_discover
node_dashboard -->|"section"| node_collections
node_dashboard -->|"section"| node_notes
node_dashboard -->|"section"| node_settings
node_dashboard -.->|"sandbox"| node_simple
node_simple -->|"uses"| node_tiptap
node_discover -->|"uses"| node_ingest
node_ingest -->|"stores"| node_opfs
node_discover -->|"indexes"| node_rag
node_rag -->|"powers"| node_hybrid
node_hybrid -->|"feeds"| node_quiz
node_collections -->|"shows"| node_quiz
node_notes -->|"organizes"| node_knowledgegraph
node_quiz -->|"reviews"| node_coach
node_coach -->|"delegates"| node_agentcore
node_agentcore -->|"runs"| node_strategist
node_discover -.->|"assist"| node_coach
node_settings -->|"configures"| node_stores
node_simple -.->|"shares state"| node_stores
node_coach -->|"signals"| node_events
node_knowledgegraph -.->|"signals"| node_events

click node_root "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/layout.tsx"
click node_landing "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/page.tsx"
click node_intro "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/intro/page.tsx"
click node_dashboard "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/page.tsx"
click node_discover "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/discover/page.tsx"
click node_collections "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/collections/page.tsx"
click node_notes "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/note/page.tsx"
click node_settings "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/settings/page.tsx"
click node_simple "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/simple/page.tsx"
click node_tiptap "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/simple/components/tiptap-templates/simple/simple-editor.tsx"
click node_opfs "https://github.com/mahnduc/studymind-local-first/blob/main/src/lib/opfs/opfsApis.ts"
click node_ingest "https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/discover/_hooks/useIngestFile.ts"
click node_rag "https://github.com/mahnduc/studymind-local-first/blob/main/src/lib/rag/api.ts"
click node_hybrid "https://github.com/mahnduc/studymind-local-first/blob/main/src/hooks/useHybridSearch.ts"
click node_quiz "https://github.com/mahnduc/studymind-local-first/blob/main/src/lib/quiz/history.ts"
click node_agentcore "https://github.com/mahnduc/studymind-local-first/blob/main/src/agent/core/orchestrator.ts"
click node_strategist "https://github.com/mahnduc/studymind-local-first/blob/main/src/agent/members/learning-strategist.ts"
click node_coach "https://github.com/mahnduc/studymind-local-first/blob/main/src/components/LearningCoachPopup.tsx"
click node_knowledgegraph "https://github.com/mahnduc/studymind-local-first/blob/main/src/components/floatingchat/knowledge-graph/index.tsx"
click node_stores "https://github.com/mahnduc/studymind-local-first/blob/main/src/stores/editorStore.ts"
click node_events "https://github.com/mahnduc/studymind-local-first/blob/main/src/utils/eventEmitter.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_root,node_landing,node_intro,node_dashboard,node_discover,node_collections,node_notes,node_settings toneBlue
class node_opfs,node_ingest,node_rag,node_hybrid,node_quiz toneAmber
class node_agentcore,node_strategist,node_coach toneMint
class node_simple,node_tiptap toneRose
class node_knowledgegraph,node_stores,node_events toneIndigo
```

## Components

### App surfaces

Route-based product UI and entry points.

- [App shell](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/layout.tsx): next-app-router · Top-level Next.js App Router entry and global layout. · `src/app/layout.tsx`
- [Landing](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/page.tsx): entry pages · Root landing and onboarding entry points. · `src/app/page.tsx`
- [Intro](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/intro/page.tsx): onboarding route · Introductory onboarding experience. · `src/app/intro/page.tsx`
- [Dashboard](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/page.tsx): product shell · Main product area with discover, collections, notes, notifications, OPFS explorer, timetable, and settings. · `src/app/dashboard/page.tsx`
- [Discover](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/discover/page.tsx): ingest + review UI · Browser workflow for importing files, browsing local content, and starting quizzes. · `src/app/dashboard/discover/page.tsx`
- [Collections](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/collections/page.tsx): study library · Collection views for quiz cards, vocabulary, and flashcards. · `src/app/dashboard/collections/page.tsx`
- [Notes](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/note/page.tsx): note surface · Dashboard notes area for study content and organization. · `src/app/dashboard/note/page.tsx`
- [Settings](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/settings/page.tsx): preferences area · Preferences, security, and API key management. · `src/app/dashboard/settings/page.tsx`

### Local knowledge

Browser-local storage, ingestion, search, and quiz generation.

- [OPFS](https://github.com/mahnduc/studymind-local-first/blob/main/src/lib/opfs/opfsApis.ts): browser storage · Origin Private File System access and persistence services. · `src/lib/opfs/opfsApis.ts`
- [Ingest hooks](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/dashboard/discover/_hooks/useIngestFile.ts): file pipeline · Upload, ingest, list, and fetch local files in the dashboard. · `src/app/dashboard/discover/_hooks/useIngestFile.ts`
- [RAG layer](https://github.com/mahnduc/studymind-local-first/blob/main/src/lib/rag/api.ts): retrieval pipeline · Chunking, BM25 search, docx-to-markdown conversion, QA generation, and search API surface. · `src/lib/rag/api.ts`
- [Hybrid search](https://github.com/mahnduc/studymind-local-first/blob/main/src/hooks/useHybridSearch.ts): search service · Hybrid lexical and AI-assisted knowledge search. · `src/hooks/useHybridSearch.ts`
- [Quiz engine](https://github.com/mahnduc/studymind-local-first/blob/main/src/lib/quiz/history.ts): practice loop · Quiz generation, practice, and history storage for study review. · `src/lib/quiz/history.ts`

### Assistant layer

Coaching and feedback orchestration.

- [Agent core](https://github.com/mahnduc/studymind-local-first/blob/main/src/agent/core/orchestrator.ts): orchestration · Core orchestration, context, gateway, and typed agent interfaces. · `src/agent/core/orchestrator.ts`
- [Learning strategist](https://github.com/mahnduc/studymind-local-first/blob/main/src/agent/members/learning-strategist.ts): coach member · Agent member that analyzes outcomes and produces learning guidance. · `src/agent/members/learning-strategist.ts`
- [Coach UI](https://github.com/mahnduc/studymind-local-first/blob/main/src/components/LearningCoachPopup.tsx): assistant surface · Floating assistant and learning coach popups connected to study progress. · `src/components/LearningCoachPopup.tsx`

### Editor stack

Standalone Tiptap-based authoring environment.

- [Simple editor](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/simple/page.tsx): editor sandbox · Standalone Tiptap-centric authoring sandbox. · `src/app/simple/page.tsx`
- [Tiptap UI](https://github.com/mahnduc/studymind-local-first/blob/main/src/app/simple/components/tiptap-templates/simple/simple-editor.tsx): rich-text stack · Custom nodes, toolbar primitives, editor hooks, and templates for rich-text editing. · `src/app/simple/components/tiptap-templates/simple/simple-editor.tsx`

### Shared client state

Reusable hooks, stores, and cross-component utilities.

- [Knowledge graph](https://github.com/mahnduc/studymind-local-first/blob/main/src/components/floatingchat/knowledge-graph/index.tsx): note structure · Graph/tree view for organizing notes and study concepts. · `src/components/floatingchat/knowledge-graph/index.tsx`
- [Client stores](https://github.com/mahnduc/studymind-local-first/blob/main/src/stores/editorStore.ts): global state · Lightweight app state for editor and profile concerns. · `src/stores/editorStore.ts`
- [Event bus](https://github.com/mahnduc/studymind-local-first/blob/main/src/utils/eventEmitter.ts): signals · Cross-component signaling for floating panels and coordinated UI actions. · `src/utils/eventEmitter.ts`

## Connections

- App shell → Landing: routes · Global app shell contains the public landing flow.
- App shell → Intro: routes · Global app shell contains onboarding routes.
- App shell → Dashboard: routes · Global app shell contains the main product area.
- Dashboard → Discover: section · Main shell opens into discover for ingestion and review.
- Dashboard → Collections: section · Main shell opens into collections for study artifacts.
- Dashboard → Notes: section · Main shell exposes note management.
- Dashboard → Settings: section · Main shell exposes settings and account controls.
- Dashboard → Simple editor: sandbox · Editor sandbox is a separate route family.
- Simple editor → Tiptap UI: uses · The simple route is built on the custom Tiptap stack.
- Discover → Ingest hooks: uses · Discover UI drives upload, ingest, and file browsing hooks.
- Ingest hooks → OPFS: stores · Ingested content is persisted in browser-local OPFS storage.
- Discover → RAG layer: indexes · Imported content is prepared for retrieval and quiz generation.
- RAG layer → Hybrid search: powers · Retrieval layer backs hybrid semantic/lexical search.
- Hybrid search → Quiz engine: feeds · Search and content understanding feed the practice loop.
- Collections → Quiz engine: shows · Collections presents quiz cards, flashcards, and practice history.
- Notes → Knowledge graph: organizes · Notes are surfaced as a navigable knowledge graph.
- Quiz engine → Coach UI: reviews · Quiz outcomes are summarized back to the learner assistant.
- Coach UI → Agent core: delegates · The coach UI is backed by the agent orchestration layer.
- Agent core → Learning strategist: runs · Orchestration invokes the learning strategist member.
- Discover → Coach UI: assist · Discovery and review screens can surface assistant guidance.
- Settings → Client stores: configures · Settings interact with client-side state such as profile and editor preferences.
- Simple editor → Client stores: shares state · The editor stack reuses global client stores and hooks.
- Coach UI → Event bus: signals · Floating assistant components coordinate through the event bus.
- Knowledge graph → Event bus: signals · Graph UI participates in cross-panel coordination.
