# codestrate/wefty architecture

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

- Interactive diagram: https://gitdiagram.com/codestrate/wefty
- Repository: https://github.com/codestrate/wefty

## Overview

Wefty is a local-first desktop library for coding-agent sessions, memories, and project context. Its main workflow scans enabled harnesses, normalizes their data into a shared library, then presents it in timeline, graph, and list views with search and detail editors. Users can resume work in embedded terminals or create Markdown handoffs. The graph preserves documented capabilities, but some links—especially renderer-to-preload IPC wiring and unsampled subsystems—are shown only where the README or source index supports them.

Main entry points: [`renderer/main/home-view.tsx`](https://github.com/codestrate/wefty/blob/dev/renderer/main/home-view.tsx) (Library home), [`main/services/library.ts`](https://github.com/codestrate/wefty/blob/dev/main/services/library.ts) (Library scanner), [`renderer/lib/terminal-context.tsx`](https://github.com/codestrate/wefty/blob/dev/renderer/lib/terminal-context.tsx) (Terminal state), [`renderer/lib/library-api.ts`](https://github.com/codestrate/wefty/blob/dev/renderer/lib/library-api.ts) (Library API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Library collection"]
  node_contract["Library contract<br/>[types.ts]"]
  node_library["Library scanner<br/>[library.ts]"]
  node_harnessreaders["Harness readers"]
  node_memoryfiles["Memory files<br/>[memory-files.ts]"]
  node_preferences[("Preferences<br/>[preferences.ts]")]
  node_platform["Platform paths<br/>[platform.ts]"]
  node_util["File utilities<br/>[util.ts]"]
end

subgraph group_workspace["Library workspace"]
  node_home["Library home<br/>[home-view.tsx]"]
  node_timeline["Timeline view<br/>[river-pane.tsx]"]
  node_graph["Graph view<br/>[graph-pane.tsx]"]
  node_list["List view<br/>[list-pane.tsx]"]
  node_sessiondetail["Transcript reader<br/>[session-detail.tsx]"]
  node_memorydetail["Memory editor<br/>[memory-detail.tsx]"]
  node_libraryapi["Library API<br/>[library-api.ts]"]
  node_search["Search state<br/>[search.ts]"]
end

subgraph group_continuation["Work continuation"]
  node_handoff["Handoff builder<br/>[handoff.ts]"]
  node_terminalservice["PTY terminal<br/>[terminal.ts]"]
  node_terminalcontext["Terminal state"]
  node_terminaldock["Terminal panel<br/>[terminal-dock.tsx]"]
end

subgraph group_runtime["App runtime"]
  node_handlers["IPC registration<br/>[index.ts]"]
  node_libraryhandlers["Library handlers<br/>[library.ts]"]
  node_terminalhandlers["Terminal handlers<br/>[terminal.ts]"]
  node_preload["Preload bridge<br/>[preload.ts]"]
  node_settings["Settings view<br/>[settings-view.tsx]"]
end

node_user(("Developer"))
node_agentfiles["Agent files"]

node_agentfiles -->|"scanned by"| node_library
node_library -->|"dispatches scans"| node_harnessreaders
node_library -->|"reads settings"| node_preferences
node_library -->|"uses"| node_memoryfiles
node_library -->|"produces"| node_contract
node_harnessreaders -->|"normalizes to"| node_contract
node_util -->|"uses paths"| node_platform
node_handlers -->|"registers"| node_libraryhandlers
node_handlers -->|"registers"| node_terminalhandlers
node_libraryhandlers -->|"serves library"| node_library
node_terminalhandlers -->|"serves terminals"| node_terminalservice
node_home -->|"renders"| node_timeline
node_home -->|"renders"| node_graph
node_home -->|"renders"| node_list
node_home -->|"renders"| node_sessiondetail
node_home -->|"renders"| node_memorydetail
node_home -->|"reads and mutates"| node_libraryapi
node_home -->|"uses route state"| node_search
node_timeline -->|"shows activity"| node_user
node_graph -->|"shows relationships"| node_user
node_list -->|"shows items"| node_user
node_sessiondetail -->|"requests handoff"| node_libraryapi
node_library -->|"builds handoff"| node_handoff
node_user -->|"resumes work"| node_terminaldock
node_terminaldock -->|"uses tabs"| node_terminalcontext
node_terminalcontext -->|"opens and writes"| node_terminalservice
node_libraryapi -.->|"IPC bridge"| node_preload
node_terminalcontext -.->|"IPC bridge"| node_preload
node_user -->|"configures harnesses"| node_settings

click node_contract "https://github.com/codestrate/wefty/blob/dev/main/shared/types.ts"
click node_library "https://github.com/codestrate/wefty/blob/dev/main/services/library.ts"
click node_harnessreaders "https://github.com/codestrate/wefty/tree/dev/main/services/harnesses"
click node_memoryfiles "https://github.com/codestrate/wefty/blob/dev/main/services/memory-files.ts"
click node_preferences "https://github.com/codestrate/wefty/blob/dev/main/services/preferences.ts"
click node_platform "https://github.com/codestrate/wefty/blob/dev/main/services/platform.ts"
click node_util "https://github.com/codestrate/wefty/blob/dev/main/services/util.ts"
click node_home "https://github.com/codestrate/wefty/blob/dev/renderer/main/home-view.tsx"
click node_timeline "https://github.com/codestrate/wefty/blob/dev/renderer/components/river-pane.tsx"
click node_graph "https://github.com/codestrate/wefty/blob/dev/renderer/components/graph-pane.tsx"
click node_list "https://github.com/codestrate/wefty/blob/dev/renderer/components/list-pane.tsx"
click node_sessiondetail "https://github.com/codestrate/wefty/blob/dev/renderer/components/detail/session-detail.tsx"
click node_memorydetail "https://github.com/codestrate/wefty/blob/dev/renderer/components/detail/memory-detail.tsx"
click node_libraryapi "https://github.com/codestrate/wefty/blob/dev/renderer/lib/library-api.ts"
click node_search "https://github.com/codestrate/wefty/blob/dev/renderer/lib/search.ts"
click node_handoff "https://github.com/codestrate/wefty/blob/dev/main/services/handoff.ts"
click node_terminalservice "https://github.com/codestrate/wefty/blob/dev/main/services/terminal.ts"
click node_terminalcontext "https://github.com/codestrate/wefty/blob/dev/renderer/lib/terminal-context.tsx"
click node_terminaldock "https://github.com/codestrate/wefty/blob/dev/renderer/components/terminal/terminal-dock.tsx"
click node_handlers "https://github.com/codestrate/wefty/blob/dev/main/handlers/index.ts"
click node_libraryhandlers "https://github.com/codestrate/wefty/blob/dev/main/handlers/library.ts"
click node_terminalhandlers "https://github.com/codestrate/wefty/blob/dev/main/handlers/terminal.ts"
click node_preload "https://github.com/codestrate/wefty/blob/dev/renderer/preload.ts"
click node_settings "https://github.com/codestrate/wefty/blob/dev/renderer/settings/settings-view.tsx"

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_contract,node_library,node_harnessreaders,node_memoryfiles,node_preferences,node_platform,node_util toneBlue
class node_home,node_timeline,node_graph,node_list,node_sessiondetail,node_memorydetail,node_libraryapi,node_search toneAmber
class node_handoff,node_terminalservice,node_terminalcontext,node_terminaldock toneMint
class node_handlers,node_libraryhandlers,node_terminalhandlers,node_preload,node_settings toneRose
class node_user,node_agentfiles toneIndigo
```

## Components

### Library collection

- [Library contract](https://github.com/codestrate/wefty/blob/dev/main/shared/types.ts): `main/shared/types.ts`
- [Library scanner](https://github.com/codestrate/wefty/blob/dev/main/services/library.ts): `main/services/library.ts`
- [Harness readers](https://github.com/codestrate/wefty/tree/dev/main/services/harnesses): `main/services/harnesses`
- [Memory files](https://github.com/codestrate/wefty/blob/dev/main/services/memory-files.ts): `main/services/memory-files.ts`
- [Preferences](https://github.com/codestrate/wefty/blob/dev/main/services/preferences.ts): `main/services/preferences.ts`
- [Platform paths](https://github.com/codestrate/wefty/blob/dev/main/services/platform.ts): `main/services/platform.ts`
- [File utilities](https://github.com/codestrate/wefty/blob/dev/main/services/util.ts): `main/services/util.ts`

### Library workspace

- [Library home](https://github.com/codestrate/wefty/blob/dev/renderer/main/home-view.tsx): `renderer/main/home-view.tsx`
- [Timeline view](https://github.com/codestrate/wefty/blob/dev/renderer/components/river-pane.tsx): `renderer/components/river-pane.tsx`
- [Graph view](https://github.com/codestrate/wefty/blob/dev/renderer/components/graph-pane.tsx): `renderer/components/graph-pane.tsx`
- [List view](https://github.com/codestrate/wefty/blob/dev/renderer/components/list-pane.tsx): `renderer/components/list-pane.tsx`
- [Transcript reader](https://github.com/codestrate/wefty/blob/dev/renderer/components/detail/session-detail.tsx): `renderer/components/detail/session-detail.tsx`
- [Memory editor](https://github.com/codestrate/wefty/blob/dev/renderer/components/detail/memory-detail.tsx): `renderer/components/detail/memory-detail.tsx`
- [Library API](https://github.com/codestrate/wefty/blob/dev/renderer/lib/library-api.ts): `renderer/lib/library-api.ts`
- [Search state](https://github.com/codestrate/wefty/blob/dev/renderer/lib/search.ts): `renderer/lib/search.ts`

### Work continuation

- [Handoff builder](https://github.com/codestrate/wefty/blob/dev/main/services/handoff.ts): `main/services/handoff.ts`
- [PTY terminal](https://github.com/codestrate/wefty/blob/dev/main/services/terminal.ts): `main/services/terminal.ts`
- [Terminal state](https://github.com/codestrate/wefty/blob/dev/renderer/lib/terminal-context.tsx): `renderer/lib/terminal-context.tsx`
- [Terminal panel](https://github.com/codestrate/wefty/blob/dev/renderer/components/terminal/terminal-dock.tsx): `renderer/components/terminal/terminal-dock.tsx`

### App runtime

- [IPC registration](https://github.com/codestrate/wefty/blob/dev/main/handlers/index.ts): `main/handlers/index.ts`
- [Library handlers](https://github.com/codestrate/wefty/blob/dev/main/handlers/library.ts): `main/handlers/library.ts`
- [Terminal handlers](https://github.com/codestrate/wefty/blob/dev/main/handlers/terminal.ts): `main/handlers/terminal.ts`
- [Preload bridge](https://github.com/codestrate/wefty/blob/dev/renderer/preload.ts): `renderer/preload.ts`
- [Settings view](https://github.com/codestrate/wefty/blob/dev/renderer/settings/settings-view.tsx): `renderer/settings/settings-view.tsx`

### Other components

- **Developer**
- **Agent files**

## Connections

- Agent files → Library scanner: scanned by (evidence: `README.md`)
- Library scanner → Harness readers: dispatches scans (evidence: `main/services/library.ts`)
- Library scanner → Preferences: reads settings (evidence: `main/services/library.ts`)
- Library scanner → Memory files: uses (evidence: `main/services/library.ts`)
- Library scanner → Library contract: produces (evidence: `main/shared/types.ts`)
- Harness readers → Library contract: normalizes to (evidence: `README.md`)
- File utilities → Platform paths: uses paths (evidence: `main/services/util.ts`)
- IPC registration → Library handlers: registers (evidence: `main/handlers/index.ts`)
- IPC registration → Terminal handlers: registers (evidence: `main/handlers/index.ts`)
- Library handlers → Library scanner: serves library (evidence: `main/handlers/library.ts`)
- Terminal handlers → PTY terminal: serves terminals (evidence: `main/handlers/terminal.ts`)
- Library home → Timeline view: renders (evidence: `renderer/main/home-view.tsx`)
- Library home → Graph view: renders (evidence: `renderer/main/home-view.tsx`)
- Library home → List view: renders (evidence: `renderer/main/home-view.tsx`)
- Library home → Transcript reader: renders (evidence: `renderer/main/home-view.tsx`)
- Library home → Memory editor: renders (evidence: `renderer/main/home-view.tsx`)
- Library home → Library API: reads and mutates (evidence: `renderer/main/home-view.tsx`)
- Library home → Search state: uses route state (evidence: `renderer/main/router.tsx`)
- Timeline view → Developer: shows activity (evidence: `README.md`)
- Graph view → Developer: shows relationships (evidence: `README.md`)
- List view → Developer: shows items (evidence: `README.md`)
- Transcript reader → Library API: requests handoff (evidence: `renderer/components/detail/session-detail.tsx`)
- Library scanner → Handoff builder: builds handoff (evidence: `main/services/library.ts`)
- Developer → Terminal panel: resumes work (evidence: `README.md`)
- Terminal panel → Terminal state: uses tabs (evidence: `renderer/components/terminal/terminal-dock.tsx`)
- Terminal state → PTY terminal: opens and writes (evidence: `README.md`)
- Library API → Preload bridge: IPC bridge
- Terminal state → Preload bridge: IPC bridge
- Developer → Settings view: configures harnesses (evidence: `README.md`)
