# mpratyush54/nexus architecture

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

- Interactive diagram: https://gitdiagram.com/mpratyush54/nexus
- Repository: https://github.com/mpratyush54/nexus

## Overview

Nexus is a local-first memory and collaboration system: workspace activity is captured by a daemon, processed into searchable sessions and memories, and exposed through server APIs to web and native clients. The tree also shows branches, MCP tools, agent integrations, teleport/handoff, and organization features. The README is a decision-log index rather than a product overview; several subsystem paths are therefore mapped from their names, with unverified relationships left dashed. Sampled excerpts establish the Windows and macOS client-call paths and some server routing, but not the full runtime wiring.

Main entry points: [`internal/server/server.go`](https://github.com/mpratyush54/nexus/blob/master/internal/server/server.go) (API server), [`internal/store/store.go`](https://github.com/mpratyush54/nexus/blob/master/internal/store/store.go) (Persistent store), [`internal/daemon/harvester.go`](https://github.com/mpratyush54/nexus/blob/master/internal/daemon/harvester.go) (Harvest watcher), [`desktop/macos/Nexus/ShellModel.swift`](https://github.com/mpratyush54/nexus/blob/master/desktop/macos/Nexus/ShellModel.swift) (macOS shell model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and daemon"]
  node_daemon["Local daemon<br/>[daemon.go]"]
  node_harvest["Harvest watcher<br/>[harvester.go]"]
  node_processor["Activity processor<br/>[processor.go]"]
  node_adapters["Source adapters<br/>[walk.go]"]
end

subgraph group_memory["Memory and retrieval"]
  node_extract["Memory extraction<br/>[extract.go]"]
  node_context["Search and context<br/>[search.go]"]
  node_store[("Persistent store<br/>[store.go]")]
  node_blobs[("Session blobs<br/>[store.go]")]
  node_branches["Branch operations<br/>[merge.go]"]
end

subgraph group_service["API and collaboration"]
  node_server["API server<br/>[server.go]"]
  node_routes["Session and branch routes<br/>[routes_extra.go]"]
  node_auth["Authentication routes<br/>[auth_routes.go]"]
  node_orgs["Organizations and sharing<br/>[org_routes.go]"]
end

subgraph group_clients["User clients"]
  node_web["Web dashboard<br/>[app.js]"]
  node_frontend["Web application<br/>[App.tsx]"]
  node_winapp["Windows desktop<br/>[App.xaml.cs]"]
  node_winclient["Windows core client<br/>[NxClient.cs]"]
  node_native["Native core bridge<br/>[NxNative.cs]"]
  node_macmodel["macOS shell model<br/>[ShellModel.swift]"]
  node_methods["Core method bindings<br/>[NxMethods.swift]"]
end

subgraph group_integrations["Agents and extensions"]
  node_agents["Agent integrations<br/>[configure.go]"]
  node_mcp["MCP server<br/>[server.go]"]
  node_teleport["Teleport and handoff<br/>[prepare.go]"]
end

node_user(("User"))
node_workspace["Workspace"]

node_user -->|"works in"| node_workspace
node_workspace -.->|"watched by"| node_harvest
node_daemon -.->|"runs"| node_harvest
node_harvest -.->|"scans through"| node_adapters
node_harvest -.->|"submits activity"| node_processor
node_processor -.->|"produces candidates"| node_extract
node_extract -.->|"persists memories"| node_store
node_context -.->|"searches"| node_store
node_store -.->|"uses for content"| node_blobs
node_server -.->|"serves routes"| node_routes
node_routes -->|"reads and writes"| node_store
node_server -.->|"serves routes"| node_auth
node_web -->|"REST and WebSocket"| node_server
node_frontend -.->|"calls API"| node_server
node_user -.->|"uses"| node_web
node_user -.->|"uses"| node_frontend
node_user -->|"uses"| node_winapp
node_winapp -->|"initializes"| node_winclient
node_winclient -->|"calls native shim"| node_native
node_user -.->|"uses"| node_macmodel
node_macmodel -->|"dispatches methods"| node_methods
node_macmodel -->|"loads catalog"| node_agents
node_agents -.->|"configures"| node_mcp
node_mcp -.->|"retrieves context"| node_context
node_user -.->|"requests handoff"| node_teleport
node_server -.->|"exposes collaboration"| node_orgs
node_store -.->|"supports branch data"| node_branches

click node_daemon "https://github.com/mpratyush54/nexus/blob/master/internal/daemon/daemon.go"
click node_harvest "https://github.com/mpratyush54/nexus/blob/master/internal/daemon/harvester.go"
click node_processor "https://github.com/mpratyush54/nexus/blob/master/internal/daemon/processor.go"
click node_adapters "https://github.com/mpratyush54/nexus/blob/master/adapters/walk.go"
click node_extract "https://github.com/mpratyush54/nexus/blob/master/internal/extract/extract.go"
click node_context "https://github.com/mpratyush54/nexus/blob/master/internal/context/search.go"
click node_store "https://github.com/mpratyush54/nexus/blob/master/internal/store/store.go"
click node_blobs "https://github.com/mpratyush54/nexus/blob/master/internal/blobs/store.go"
click node_branches "https://github.com/mpratyush54/nexus/blob/master/internal/branches/merge.go"
click node_server "https://github.com/mpratyush54/nexus/blob/master/internal/server/server.go"
click node_routes "https://github.com/mpratyush54/nexus/blob/master/internal/server/routes_extra.go"
click node_auth "https://github.com/mpratyush54/nexus/blob/master/internal/server/auth_routes.go"
click node_web "https://github.com/mpratyush54/nexus/blob/master/web/app.js"
click node_frontend "https://github.com/mpratyush54/nexus/blob/master/frontend/src/App.tsx"
click node_winapp "https://github.com/mpratyush54/nexus/blob/master/desktop/windows/App.xaml.cs"
click node_winclient "https://github.com/mpratyush54/nexus/blob/master/desktop/windows/Core/NxClient.cs"
click node_native "https://github.com/mpratyush54/nexus/blob/master/desktop/windows/Core/NxNative.cs"
click node_macmodel "https://github.com/mpratyush54/nexus/blob/master/desktop/macos/Nexus/ShellModel.swift"
click node_methods "https://github.com/mpratyush54/nexus/blob/master/bindings/swift/NxMethods.swift"
click node_agents "https://github.com/mpratyush54/nexus/blob/master/internal/agents/mcpconfig/configure.go"
click node_mcp "https://github.com/mpratyush54/nexus/blob/master/internal/mcp/server.go"
click node_teleport "https://github.com/mpratyush54/nexus/blob/master/internal/teleport/prepare.go"
click node_orgs "https://github.com/mpratyush54/nexus/blob/master/internal/server/org_routes.go"

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_daemon,node_harvest,node_processor,node_adapters,node_user toneBlue
class node_extract,node_context,node_store,node_blobs,node_branches toneAmber
class node_server,node_routes,node_auth,node_orgs toneMint
class node_web,node_frontend,node_winapp,node_winclient,node_native,node_macmodel,node_methods toneRose
class node_agents,node_mcp,node_teleport,node_workspace toneIndigo
```

## Components

### Capture and daemon

- [Local daemon](https://github.com/mpratyush54/nexus/blob/master/internal/daemon/daemon.go): `internal/daemon/daemon.go`
- [Harvest watcher](https://github.com/mpratyush54/nexus/blob/master/internal/daemon/harvester.go): `internal/daemon/harvester.go`
- [Activity processor](https://github.com/mpratyush54/nexus/blob/master/internal/daemon/processor.go): `internal/daemon/processor.go`
- [Source adapters](https://github.com/mpratyush54/nexus/blob/master/adapters/walk.go): `adapters/walk.go`

### Memory and retrieval

- [Memory extraction](https://github.com/mpratyush54/nexus/blob/master/internal/extract/extract.go): `internal/extract/extract.go`
- [Search and context](https://github.com/mpratyush54/nexus/blob/master/internal/context/search.go): `internal/context/search.go`
- [Persistent store](https://github.com/mpratyush54/nexus/blob/master/internal/store/store.go): `internal/store/store.go`
- [Session blobs](https://github.com/mpratyush54/nexus/blob/master/internal/blobs/store.go): `internal/blobs/store.go`
- [Branch operations](https://github.com/mpratyush54/nexus/blob/master/internal/branches/merge.go): `internal/branches/merge.go`

### API and collaboration

- [API server](https://github.com/mpratyush54/nexus/blob/master/internal/server/server.go): `internal/server/server.go`
- [Session and branch routes](https://github.com/mpratyush54/nexus/blob/master/internal/server/routes_extra.go): `internal/server/routes_extra.go`
- [Authentication routes](https://github.com/mpratyush54/nexus/blob/master/internal/server/auth_routes.go): `internal/server/auth_routes.go`
- [Organizations and sharing](https://github.com/mpratyush54/nexus/blob/master/internal/server/org_routes.go): `internal/server/org_routes.go`

### User clients

- [Web dashboard](https://github.com/mpratyush54/nexus/blob/master/web/app.js): `web/app.js`
- [Web application](https://github.com/mpratyush54/nexus/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Windows desktop](https://github.com/mpratyush54/nexus/blob/master/desktop/windows/App.xaml.cs): `desktop/windows/App.xaml.cs`
- [Windows core client](https://github.com/mpratyush54/nexus/blob/master/desktop/windows/Core/NxClient.cs): `desktop/windows/Core/NxClient.cs`
- [Native core bridge](https://github.com/mpratyush54/nexus/blob/master/desktop/windows/Core/NxNative.cs): `desktop/windows/Core/NxNative.cs`
- [macOS shell model](https://github.com/mpratyush54/nexus/blob/master/desktop/macos/Nexus/ShellModel.swift): `desktop/macos/Nexus/ShellModel.swift`
- [Core method bindings](https://github.com/mpratyush54/nexus/blob/master/bindings/swift/NxMethods.swift): `bindings/swift/NxMethods.swift`

### Agents and extensions

- [Agent integrations](https://github.com/mpratyush54/nexus/blob/master/internal/agents/mcpconfig/configure.go): `internal/agents/mcpconfig/configure.go`
- [MCP server](https://github.com/mpratyush54/nexus/blob/master/internal/mcp/server.go): `internal/mcp/server.go`
- [Teleport and handoff](https://github.com/mpratyush54/nexus/blob/master/internal/teleport/prepare.go): `internal/teleport/prepare.go`

### Other components

- **User**
- **Workspace**

## Connections

- User → Workspace: works in
- Workspace → Harvest watcher: watched by
- Local daemon → Harvest watcher: runs
- Harvest watcher → Source adapters: scans through
- Harvest watcher → Activity processor: submits activity
- Activity processor → Memory extraction: produces candidates
- Memory extraction → Persistent store: persists memories
- Search and context → Persistent store: searches
- Persistent store → Session blobs: uses for content
- API server → Session and branch routes: serves routes
- Session and branch routes → Persistent store: reads and writes (evidence: `internal/server/routes_extra.go`)
- API server → Authentication routes: serves routes
- Web dashboard → API server: REST and WebSocket (evidence: `web/app.js`)
- Web application → API server: calls API
- User → Web dashboard: uses
- User → Web application: uses
- User → Windows desktop: uses (evidence: `desktop/windows/App.xaml.cs`)
- Windows desktop → Windows core client: initializes (evidence: `desktop/windows/App.xaml.cs`)
- Windows core client → Native core bridge: calls native shim (evidence: `desktop/windows/Core/NxClient.cs`)
- User → macOS shell model: uses
- macOS shell model → Core method bindings: dispatches methods (evidence: `desktop/macos/Nexus/ShellModel.swift`)
- macOS shell model → Agent integrations: loads catalog (evidence: `desktop/macos/Nexus/ShellModel.swift`)
- Agent integrations → MCP server: configures
- MCP server → Search and context: retrieves context
- User → Teleport and handoff: requests handoff
- API server → Organizations and sharing: exposes collaboration
- Persistent store → Branch operations: supports branch data
