How mahnduc/studymind-local-first works
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: dashboard/page.tsx Dashboard · discover/page.tsx Discover · LearningCoachPopup.tsx Coach UI · layout.tsx App shell
Components 21
App surfaces
Route-based product UI and entry points.
- App shell · Top-level Next.js App Router entry and global layout.
src/app/layout.tsx - Landing · Root landing and onboarding entry points.
src/app/page.tsx - Intro · Introductory onboarding experience.
src/app/intro/page.tsx - Dashboard · Main product area with discover, collections, notes, notifications, OPFS explorer, timetable, and settings.
src/app/dashboard/page.tsx - Discover · Browser workflow for importing files, browsing local content, and starting quizzes.
src/app/dashboard/discover/page.tsx - Collections · Collection views for quiz cards, vocabulary, and flashcards.
src/app/dashboard/collections/page.tsx - Notes · Dashboard notes area for study content and organization.
src/app/dashboard/note/page.tsx - Settings · Preferences, security, and API key management.
src/app/dashboard/settings/page.tsx
Local knowledge
Browser-local storage, ingestion, search, and quiz generation.
- OPFS · Origin Private File System access and persistence services.
src/lib/opfs/opfsApis.ts - Ingest hooks · Upload, ingest, list, and fetch local files in the dashboard.
src/app/dashboard/discover/_hooks/useIngestFile.ts - RAG layer · Chunking, BM25 search, docx-to-markdown conversion, QA generation, and search API surface.
src/lib/rag/api.ts - Hybrid search · Hybrid lexical and AI-assisted knowledge search.
src/hooks/useHybridSearch.ts - Quiz engine · Quiz generation, practice, and history storage for study review.
src/lib/quiz/history.ts
Assistant layer
Coaching and feedback orchestration.
- Agent core · Core orchestration, context, gateway, and typed agent interfaces.
src/agent/core/orchestrator.ts - Learning strategist · Agent member that analyzes outcomes and produces learning guidance.
src/agent/members/learning-strategist.ts - Coach UI · Floating assistant and learning coach popups connected to study progress.
src/components/LearningCoachPopup.tsx
Editor stack
Standalone Tiptap-based authoring environment.
- Simple editor · Standalone Tiptap-centric authoring sandbox.
src/app/simple/page.tsx - Tiptap UI · 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 · Graph/tree view for organizing notes and study concepts.
src/components/floatingchat/knowledge-graph/index.tsx - Client stores · Lightweight app state for editor and profile concerns.
src/stores/editorStore.ts - Event bus · Cross-component signaling for floating panels and coordinated UI actions.
src/utils/eventEmitter.ts
Connections 24
- 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.