# navskh/im architecture

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

- Interactive diagram: https://gitdiagram.com/navskh/im
- Repository: https://github.com/navskh/im

## Overview

1. **Overall shape**
   - This is a **local-first task management system** built as a **Next.js 16 + React 19 web app**, plus a **Node-based CLI** and a **stdio MCP server**.
   - The architecture is centered around a single local data store and a set of shared server-side libraries that power the UI, CLI commands, sync, AI automation, and external agent integration.

2. **Primary entrypoints**
   - `bin/im.js` is the installed CLI entrypoint (`im start`, `im watch`, `im sync`, `im mcp`).
   - The browser UI is served from the Next.js App Router under `src/app`.
   - `src/lib/mcp/server.ts` exposes the MCP server for external AI clients.
   - `src/lib/watcher.ts` and `src/lib/scheduler.ts` support background automation from the CLI side.

3. **User interface boundary**
   - The UI is organized as a **dashboard/workspace system** with reusable panels and tabs.
   - Major UI areas include:
     - dashboard views for projects and status summaries,
     - a workspace with brainstorming, project tree, and task detail panes,
     - task-specific chat and prompt editing,
     - modals for AI policy, auto-distribution, sync results, and confirmations.
   - The architecture is intentionally **panel-driven**, so a single project can be opened in a tabbed workspace while multiple projects remain accessible.

4. **Core domain model**
   - The main domain hierarchy is:
     - **Project**
     - **Sub-project**
     - **Task**
     - **Task prompt**
     - **Task conversation**
     - **Brainstorm notes**
     - **Global memo**
   - Task status is a workflow state machine: idea → writing → submitted → testing → done/problem.
   - Archived tasks are preserved as a distinct lifecycle branch rather than being hard-deleted immediately.

5. **Persistence layer**
   - Data is stored locally in **SQLite via sql.js** under `~/.idea-manager/data/`, so the app is designed to work offline and without native DB bindings.
   - `src/lib/db/schema.ts` defines the schema, while `src/lib/db/queries/*` separates persistence concerns by entity:
     - projects, sub-projects, tasks,
     - task prompts,
     - task conversations,
     - brainstorms,
     - global memo.
   - This makes the database layer the primary boundary between UI/API logic and durable state.

6. **API layer**
   - Server functionality is exposed through Next.js API routes under `src/app/api`.
   - The route set is organized by capability rather than by page:
     - project CRUD and nested project/task operations,
     - brainstorming and task distribution,
     - archive handling,
     - filesystem/tree inspection,
     - global memo,
     - health and sync endpoints.
   - These route handlers are the main server-side façade for the UI and likely the only HTTP surface the browser talks to.

7. **Brainstorming → task structuring workflow**
   - A key flow is converting free-form brainstorming into structured work:
     - brainstorm content is captured in the workspace,
     - AI-assisted distribution proposes sub-project/task placement,
     - the user previews/edits the result,
     - tasks receive prompts and can then be executed by an agent.
   - This flow is reflected in both the UI components and API routes for `brainstorm`, `auto-distribute`, and `apply-distribute`.

8. **AI agent integration**
   - `src/lib/ai/client.ts` and `src/lib/ai/agents.ts` abstract over multiple AI CLIs, specifically **Claude**, **Gemini**, and **Codex**.
   - The project can select an agent per project, and that choice affects:
     - AI chat inside task context,
     - watch-mode execution,
     - prompt refinement and distribution workflows.
   - The system is built around invoking external CLI agents rather than hosting model inference itself.

9. **MCP server boundary**
   - The MCP layer exposes task/project context to outside tools through standard MCP tools like listing projects, retrieving context, fetching the next task, updating status, and reporting completion.
   - Conceptually, MCP is an integration boundary that lets autonomous agents operate on the same underlying task database as the UI and CLI.

10. **Sync and portability**
   - Cross-machine sync is implemented as **data export/import over Git** rather than a centralized backend.
   - `src/lib/sync/exporter.ts`, `importer.ts`, `git.ts`, and `index.ts` form the sync subsystem.
   - The workflow is:
     - export local state,
     - commit/push to a private repo,
     - pull on another machine,
     - import into the local SQLite store.
   - This preserves the local-first model while allowing multi-PC use.

11. **File system / workspace linkage**
   - The app can link projects to real directories on disk.
   - `src/app/api/filesystem/*`, `src/lib/utils/paths.ts`, and the directory-picker/file-tree UI indicate a clear boundary between managed metadata in SQLite and the actual project files on disk.
   - The linked filesystem context is important for task execution, AI chat working directory, and tree browsing.

12. **Background automation**
   - Two automation paths exist outside the UI:
     - **watch mode** auto-executes submitted tasks through AI CLI tooling,
     - **scheduler** sends daily morning notifications and other time-based triggers.
   - These are part of the product’s operational layer, separate from interactive UI flows.

13. **Application shell and PWA-like delivery**
   - The app ships with a manifest and service worker in `public/`, and the README describes launching in Chrome/Edge `--app` mode.
   - That means the “desktop-like” experience is delivered as a browser app with lightweight app-shell behavior, not a native desktop runtime.

14. **How to think about the main boundaries**
   - There are three important architectural boundaries:
     - **presentation**: Next.js pages/components,
     - **domain/data**: shared DB queries and sync logic,
     - **automation/integration**: AI CLIs, MCP server, watcher, scheduler, and Git sync.
   - Almost every feature flows through local persistence first, then through one of those integration layers when external action is needed.

Main entry points: [`src/lib/db/index.ts`](https://github.com/navskh/im/blob/main/src/lib/db/index.ts) (Queries), [`src/components/workspace/WorkspacePanel.tsx`](https://github.com/navskh/im/blob/main/src/components/workspace/WorkspacePanel.tsx) (Workspace), [`bin/im.js`](https://github.com/navskh/im/blob/main/bin/im.js) (CLI entry), [`src/lib/mcp/server.ts`](https://github.com/navskh/im/blob/main/src/lib/mcp/server.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["Presentation"]
  node_next_app["Web app<br/>nextjs app<br/>[page.tsx]"]
  node_project_page["Project page<br/>route<br/>[page.tsx]"]
  node_dashboard_panel["Dashboard<br/>panel<br/>[DashboardPanel.tsx]"]
  node_workspace_panel["Workspace<br/>panel<br/>[WorkspacePanel.tsx]"]
  node_task_panels["Task panels<br/>ui bundle<br/>[TaskDetail.tsx]"]
  node_brainstorm_editor["Brainstorming<br/>editor<br/>[Editor.tsx]"]
  node_modals["Modals<br/>dialog bundle"]
end

subgraph group_group_api["HTTP API"]
  node_api_projects["Projects API<br/>route group<br/>[route.ts]"]
  node_api_brainstorm["Brainstorm API<br/>route<br/>[route.ts]"]
  node_api_archive["Archive API<br/>route<br/>[route.ts]"]
  node_api_filesystem["Filesystem API<br/>route group<br/>[route.ts]"]
  node_api_sync["Sync API<br/>route<br/>[route.ts]"]
end

subgraph group_group_domain["Domain & Data"]
  node_db_schema[("Schema<br/>[schema.ts]")]
  node_db_queries[("Queries<br/>persistence layer<br/>[index.ts]")]
  node_sync_engine["Sync engine<br/>git sync<br/>[index.ts]"]
end

subgraph group_group_integration["Automation & Integration"]
  node_cli_entry["CLI entry<br/>command<br/>[im.js]"]
  node_ai_layer["AI layer<br/>cli adapter<br/>[client.ts]"]
  node_mcp_server["MCP server<br/>stdio server<br/>[server.ts]"]
  node_watcher["Watcher<br/>automation<br/>[watcher.ts]"]
  node_scheduler["Scheduler<br/>timer automation<br/>[scheduler.ts]"]
end

node_cli_entry -->|"start/watch"| node_watcher
node_cli_entry -->|"mcp"| node_mcp_server
node_cli_entry -.->|"sync"| node_api_sync
node_next_app -->|"renders"| node_dashboard_panel
node_next_app -->|"routes to"| node_project_page
node_project_page -->|"hosts"| node_workspace_panel
node_workspace_panel -->|"shows"| node_task_panels
node_workspace_panel -->|"includes"| node_brainstorm_editor
node_workspace_panel -->|"opens"| node_modals
node_api_projects -->|"reads/writes"| node_db_queries
node_api_brainstorm -->|"updates"| node_db_queries
node_api_archive -->|"archives"| node_db_queries
node_api_filesystem -.->|"links context"| node_db_queries
node_api_sync -->|"uses"| node_sync_engine
node_db_queries -->|"implements"| node_db_schema
node_sync_engine -->|"exports/imports"| node_db_schema
node_mcp_server -->|"context tools"| node_db_queries
node_mcp_server -.->|"agent actions"| node_ai_layer
node_watcher -->|"executes"| node_ai_layer
node_scheduler -.->|"triggers"| node_db_queries
node_task_panels -->|"manages"| node_db_queries
node_brainstorm_editor -->|"submits"| node_api_brainstorm

click node_cli_entry "https://github.com/navskh/im/blob/main/bin/im.js"
click node_next_app "https://github.com/navskh/im/blob/main/src/app/page.tsx"
click node_project_page "https://github.com/navskh/im/blob/main/src/app/projects/[id]/page.tsx"
click node_dashboard_panel "https://github.com/navskh/im/blob/main/src/components/dashboard/DashboardPanel.tsx"
click node_workspace_panel "https://github.com/navskh/im/blob/main/src/components/workspace/WorkspacePanel.tsx"
click node_task_panels "https://github.com/navskh/im/blob/main/src/components/task/TaskDetail.tsx"
click node_brainstorm_editor "https://github.com/navskh/im/blob/main/src/components/brainstorm/Editor.tsx"
click node_modals "https://github.com/navskh/im/blob/main/src/components/ui/AutoDistributeModal.tsx"
click node_api_projects "https://github.com/navskh/im/blob/main/src/app/api/projects/route.ts"
click node_api_brainstorm "https://github.com/navskh/im/blob/main/src/app/api/projects/[id]/brainstorm/route.ts"
click node_api_archive "https://github.com/navskh/im/blob/main/src/app/api/archive/route.ts"
click node_api_filesystem "https://github.com/navskh/im/blob/main/src/app/api/filesystem/route.ts"
click node_api_sync "https://github.com/navskh/im/blob/main/src/app/api/sync/route.ts"
click node_db_schema "https://github.com/navskh/im/blob/main/src/lib/db/schema.ts"
click node_db_queries "https://github.com/navskh/im/blob/main/src/lib/db/index.ts"
click node_sync_engine "https://github.com/navskh/im/blob/main/src/lib/sync/index.ts"
click node_ai_layer "https://github.com/navskh/im/blob/main/src/lib/ai/client.ts"
click node_mcp_server "https://github.com/navskh/im/blob/main/src/lib/mcp/server.ts"
click node_watcher "https://github.com/navskh/im/blob/main/src/lib/watcher.ts"
click node_scheduler "https://github.com/navskh/im/blob/main/src/lib/scheduler.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_next_app,node_project_page,node_dashboard_panel,node_workspace_panel,node_task_panels,node_brainstorm_editor,node_modals toneBlue
class node_api_projects,node_api_brainstorm,node_api_archive,node_api_filesystem,node_api_sync toneAmber
class node_db_schema,node_db_queries,node_sync_engine toneMint
class node_cli_entry,node_ai_layer,node_mcp_server,node_watcher,node_scheduler toneRose
```

## Components

### Presentation

Next.js app shell and reusable workspace panels

- [Web app](https://github.com/navskh/im/blob/main/src/app/page.tsx): nextjs app · Browser-delivered app shell and routing entry · `src/app/page.tsx`
- [Project page](https://github.com/navskh/im/blob/main/src/app/projects/[id]/page.tsx): route · Project workspace page for a single opened project · `src/app/projects/[id]/page.tsx`
- [Dashboard](https://github.com/navskh/im/blob/main/src/components/dashboard/DashboardPanel.tsx): panel · Projects and status overview surface · `src/components/dashboard/DashboardPanel.tsx`
- [Workspace](https://github.com/navskh/im/blob/main/src/components/workspace/WorkspacePanel.tsx): panel · Tabbed workspace container for project-focused panels · `src/components/workspace/WorkspacePanel.tsx`
- [Task panels](https://github.com/navskh/im/blob/main/src/components/task/TaskDetail.tsx): ui bundle · Project tree, task detail, prompt editing, status flow, and task chat · `src/components/task/TaskDetail.tsx`
- [Brainstorming](https://github.com/navskh/im/blob/main/src/components/brainstorm/Editor.tsx): editor · Free-form idea capture and resizing editor · `src/components/brainstorm/Editor.tsx`
- [Modals](https://github.com/navskh/im/blob/main/src/components/ui/AutoDistributeModal.tsx): dialog bundle · AI policy, auto-distribute, sync results, and confirmation dialogs · `src/components/ui/AutoDistributeModal.tsx`

### HTTP API

Route handlers that expose server capabilities to the UI

- [Projects API](https://github.com/navskh/im/blob/main/src/app/api/projects/route.ts): route group · Project CRUD and nested sub-project/task operations · `src/app/api/projects/route.ts`
- [Brainstorm API](https://github.com/navskh/im/blob/main/src/app/api/projects/[id]/brainstorm/route.ts): route · Brainstorm capture and task distribution endpoints · `src/app/api/projects/[id]/brainstorm/route.ts`
- [Archive API](https://github.com/navskh/im/blob/main/src/app/api/archive/route.ts): route · Archive lifecycle operations for tasks and records · `src/app/api/archive/route.ts`
- [Filesystem API](https://github.com/navskh/im/blob/main/src/app/api/filesystem/route.ts): route group · Linked directory access and tree inspection · `src/app/api/filesystem/route.ts`
- [Sync API](https://github.com/navskh/im/blob/main/src/app/api/sync/route.ts): route · Export/import sync operations exposed to the UI · `src/app/api/sync/route.ts`

### Domain & Data

Shared local-first persistence, sync, and app logic

- [Schema](https://github.com/navskh/im/blob/main/src/lib/db/schema.ts): sqlite schema · Local sql.js schema for projects, tasks, prompts, conversations, brainstorms, and memo · `src/lib/db/schema.ts`
- [Queries](https://github.com/navskh/im/blob/main/src/lib/db/index.ts): persistence layer · Entity-specific database access for projects, sub-projects, tasks, prompts, conversations, brainstorms, and memo · `src/lib/db/index.ts`
- [Sync engine](https://github.com/navskh/im/blob/main/src/lib/sync/index.ts): git sync · Export/import and Git-based portability workflow · `src/lib/sync/index.ts`

### Automation & Integration

CLI entrypoints and external agent boundaries

- [CLI entry](https://github.com/navskh/im/blob/main/bin/im.js): command · Installed command for start, watch, sync, and MCP modes · `bin/im.js`
- [AI layer](https://github.com/navskh/im/blob/main/src/lib/ai/client.ts): cli adapter · Abstraction over Claude, Gemini, and Codex CLI agents · `src/lib/ai/client.ts`
- [MCP server](https://github.com/navskh/im/blob/main/src/lib/mcp/server.ts): stdio server · External agent integration over MCP tools · `src/lib/mcp/server.ts`
- [Watcher](https://github.com/navskh/im/blob/main/src/lib/watcher.ts): automation · Background execution for submitted tasks · `src/lib/watcher.ts`
- [Scheduler](https://github.com/navskh/im/blob/main/src/lib/scheduler.ts): timer automation · Time-based triggers such as morning notifications · `src/lib/scheduler.ts`

## Connections

- CLI entry → Watcher: start/watch · CLI launches background task automation
- CLI entry → MCP server: mcp · CLI exposes the stdio MCP mode
- CLI entry → Sync API: sync · CLI can drive sync workflows through shared logic
- Web app → Dashboard: renders · App shell presents the dashboard surface
- Web app → Project page: routes to · App Router serves the project workspace page
- Project page → Workspace: hosts · Project page contains the tabbed workspace
- Workspace → Task panels: shows · Workspace organizes project tree and task-centric panels
- Workspace → Brainstorming: includes · Workspace supports brainstorming capture
- Workspace → Modals: opens · Workspace uses modal dialogs for actions and results
- Projects API → Queries: reads/writes · Project and nested entity routes persist through queries
- Brainstorm API → Queries: updates · Brainstorm and distribution endpoints persist structured work
- Archive API → Queries: archives · Archive routes change task lifecycle state
- Filesystem API → Queries: links context · Filesystem routes coordinate metadata with local project context
- Sync API → Sync engine: uses · HTTP sync surface delegates to export/import engine
- Queries → Schema: implements · Query layer operates on the local SQLite schema
- Sync engine → Schema: exports/imports · Sync reads and restores the same local store
- MCP server → Queries: context tools · MCP tools read and update the shared task database
- MCP server → AI layer: agent actions · External agents operate through the same AI abstraction
- Watcher → AI layer: executes · Watch mode runs submitted tasks via CLI agents
- Scheduler → Queries: triggers · Scheduler reads local state for notifications and automation
- Task panels → Queries: manages · Task UI is backed by shared persistence
- Brainstorming → Brainstorm API: submits · Brainstorm content flows into distribution and structuring routes
