# alikarpykov/fs-linker architecture

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

- Interactive diagram: https://gitdiagram.com/alikarpykov/fs-linker
- Repository: https://github.com/alikarpykov/fs-linker

## Overview

FS-Linker is an interactive terminal tool for moving selected files or directories while preserving their original paths as symbolic links. The principal workflow is to browse source and target panels, select entries, preview an audited Link Plan, then execute safe links or migrations; unlinking removes selected source symlinks without touching target data. The graph separates browsing, workspace interaction, planning/audit, and filesystem operations. Relationships reflect the excerpts, SOURCE INDEX references, and README; unsampled implementation details are not inferred.

Main entry points: [`src/widgets/linking-workspace/model/useLinkingWorkspace.ts`](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkingWorkspace.ts) (Workspace State), [`src/widgets/linking-workspace/ui/LinkingWorkspace.tsx`](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/ui/LinkingWorkspace.tsx) (Workspace UI), [`src/widgets/linking-workspace/model/usePanel.ts`](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/usePanel.ts) (Panel State), [`src/entities/file-system-entry/api/fileSystemEntry.ts`](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/file-system-entry/api/fileSystemEntry.ts) (Directory Entries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browse["File Browsing"]
  node_panels_ui["Panel Views<br/>[Panel.tsx]"]
  node_panel_state["Panel State<br/>[usePanel.ts]"]
  node_directory_watch["Directory Watch"]
  node_entry_api["Directory Entries<br/>[fileSystemEntry.ts]"]
  node_entry_model["Entry Model<br/>[entry.ts]"]
end

subgraph group_workspace["Terminal Workspace"]
  node_cli["CLI Entry<br/>[cli.ts]"]
  node_commands["App Commands<br/>[index.tsx]"]
  node_workspace_ui["Workspace UI"]
  node_keyboard["Keyboard Controls"]
  node_workspace_state["Workspace State"]
end

subgraph group_planning["Planning And Audit"]
  node_plan_state["Plan State<br/>[useLinkPlan.ts]"]
  node_plan_navigation["Plan Navigation"]
  node_plan_view["Plan View<br/>[LinkPlan.tsx]"]
  node_plan_builder["Plan Builder"]
  node_entry_iteration["Entry Audit Loop"]
  node_audit["Safety Audit<br/>[audit.ts]"]
end

subgraph group_operations["Link Operations"]
  node_link_execution["Link Execution<br/>[linkEntries.ts]"]
  node_linker["Filesystem Linker<br/>[linker.ts]"]
  node_unlink["Unlink Operation<br/>[unlinkEntries.ts]"]
end

node_developer(("Developer"))
node_filesystem[("Local Filesystem")]

node_developer -->|"launches"| node_cli
node_commands -->|"renders"| node_workspace_ui
node_workspace_ui -->|"uses state"| node_workspace_state
node_workspace_ui -->|"registers controls"| node_keyboard
node_workspace_ui -.->|"renders panels"| node_panels_ui
node_workspace_state -->|"creates panels"| node_panel_state
node_workspace_state -->|"builds plan state"| node_plan_state
node_workspace_state -->|"tracks plan focus"| node_plan_navigation
node_panel_state -->|"loads entries"| node_entry_api
node_panel_state -->|"watches directory"| node_directory_watch
node_entry_api -->|"uses entry model"| node_entry_model
node_entry_api -->|"reads entries"| node_filesystem
node_plan_state -->|"requests plan"| node_plan_builder
node_plan_view -->|"reads plan entries"| node_plan_builder
node_plan_builder -->|"iterates sources"| node_entry_iteration
node_entry_iteration -->|"audits paths"| node_audit
node_audit -->|"inspects paths"| node_filesystem
node_workspace_state -->|"executes selections"| node_link_execution
node_workspace_state -->|"unlinks selections"| node_unlink
node_link_execution -->|"processes entries"| node_entry_iteration
node_link_execution -->|"delegates operations"| node_linker
node_linker -.->|"moves and links"| node_filesystem
node_unlink -.->|"removes symlinks"| node_filesystem

click node_cli "https://github.com/alikarpykov/fs-linker/blob/main/src/app/cli.ts"
click node_commands "https://github.com/alikarpykov/fs-linker/blob/main/src/app/commands/index.tsx"
click node_workspace_ui "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/ui/LinkingWorkspace.tsx"
click node_keyboard "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkingKeyboard.ts"
click node_workspace_state "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkingWorkspace.ts"
click node_panels_ui "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/ui/Panel.tsx"
click node_panel_state "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/usePanel.ts"
click node_directory_watch "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useWatchDirectory.ts"
click node_entry_api "https://github.com/alikarpykov/fs-linker/blob/main/src/entities/file-system-entry/api/fileSystemEntry.ts"
click node_entry_model "https://github.com/alikarpykov/fs-linker/blob/main/src/entities/file-system-entry/model/entry.ts"
click node_plan_state "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkPlan.ts"
click node_plan_navigation "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkPlanNavigation.ts"
click node_plan_view "https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/ui/LinkPlan.tsx"
click node_plan_builder "https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/getLinkPlanEntries.ts"
click node_entry_iteration "https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/forEachLinkEntry.ts"
click node_audit "https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/audit.ts"
click node_link_execution "https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/linkEntries.ts"
click node_linker "https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/linker.ts"
click node_unlink "https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/unlinkEntries.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_panels_ui,node_panel_state,node_directory_watch,node_entry_api,node_entry_model toneBlue
class node_cli,node_commands,node_workspace_ui,node_keyboard,node_workspace_state,node_filesystem toneAmber
class node_plan_state,node_plan_navigation,node_plan_view,node_plan_builder,node_entry_iteration,node_audit toneMint
class node_link_execution,node_linker,node_unlink toneRose
class node_developer toneIndigo
```

## Components

### File Browsing

- [Panel Views](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/ui/Panel.tsx): `src/widgets/linking-workspace/ui/Panel.tsx`
- [Panel State](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/usePanel.ts): `src/widgets/linking-workspace/model/usePanel.ts`
- [Directory Watch](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useWatchDirectory.ts): `src/widgets/linking-workspace/model/useWatchDirectory.ts`
- [Directory Entries](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/file-system-entry/api/fileSystemEntry.ts): `src/entities/file-system-entry/api/fileSystemEntry.ts`
- [Entry Model](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/file-system-entry/model/entry.ts): `src/entities/file-system-entry/model/entry.ts`

### Terminal Workspace

- [CLI Entry](https://github.com/alikarpykov/fs-linker/blob/main/src/app/cli.ts): `src/app/cli.ts`
- [App Commands](https://github.com/alikarpykov/fs-linker/blob/main/src/app/commands/index.tsx): `src/app/commands/index.tsx`
- [Workspace UI](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/ui/LinkingWorkspace.tsx): `src/widgets/linking-workspace/ui/LinkingWorkspace.tsx`
- [Keyboard Controls](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkingKeyboard.ts): `src/widgets/linking-workspace/model/useLinkingKeyboard.ts`
- [Workspace State](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkingWorkspace.ts): `src/widgets/linking-workspace/model/useLinkingWorkspace.ts`

### Planning And Audit

- [Plan State](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkPlan.ts): `src/widgets/linking-workspace/model/useLinkPlan.ts`
- [Plan Navigation](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/model/useLinkPlanNavigation.ts): `src/widgets/linking-workspace/model/useLinkPlanNavigation.ts`
- [Plan View](https://github.com/alikarpykov/fs-linker/blob/main/src/widgets/linking-workspace/ui/LinkPlan.tsx): `src/widgets/linking-workspace/ui/LinkPlan.tsx`
- [Plan Builder](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/getLinkPlanEntries.ts): `src/entities/link/model/getLinkPlanEntries.ts`
- [Entry Audit Loop](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/forEachLinkEntry.ts): `src/entities/link/model/forEachLinkEntry.ts`
- [Safety Audit](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/audit.ts): `src/entities/link/model/audit.ts`

### Link Operations

- [Link Execution](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/linkEntries.ts): `src/entities/link/model/linkEntries.ts`
- [Filesystem Linker](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/linker.ts): `src/entities/link/model/linker.ts`
- [Unlink Operation](https://github.com/alikarpykov/fs-linker/blob/main/src/entities/link/model/unlinkEntries.ts): `src/entities/link/model/unlinkEntries.ts`

### Other components

- **Developer**
- **Local Filesystem**

## Connections

- Developer → CLI Entry: launches (evidence: `README.md`)
- App Commands → Workspace UI: renders (evidence: `src/app/commands/index.tsx`)
- Workspace UI → Workspace State: uses state (evidence: `src/widgets/linking-workspace/ui/LinkingWorkspace.tsx`)
- Workspace UI → Keyboard Controls: registers controls (evidence: `src/widgets/linking-workspace/ui/LinkingWorkspace.tsx`)
- Workspace UI → Panel Views: renders panels
- Workspace State → Panel State: creates panels (evidence: `src/widgets/linking-workspace/model/useLinkingWorkspace.ts`)
- Workspace State → Plan State: builds plan state (evidence: `src/widgets/linking-workspace/model/useLinkingWorkspace.ts`)
- Workspace State → Plan Navigation: tracks plan focus (evidence: `src/widgets/linking-workspace/model/useLinkingWorkspace.ts`)
- Panel State → Directory Entries: loads entries (evidence: `src/widgets/linking-workspace/model/usePanel.ts`)
- Panel State → Directory Watch: watches directory (evidence: `src/widgets/linking-workspace/model/usePanel.ts`)
- Directory Entries → Entry Model: uses entry model (evidence: `src/entities/file-system-entry/api/fileSystemEntry.ts`)
- Directory Entries → Local Filesystem: reads entries (evidence: `src/entities/file-system-entry/api/fileSystemEntry.ts`)
- Plan State → Plan Builder: requests plan (evidence: `src/widgets/linking-workspace/model/useLinkPlan.ts`)
- Plan View → Plan Builder: reads plan entries (evidence: `src/widgets/linking-workspace/ui/LinkPlan.tsx`)
- Plan Builder → Entry Audit Loop: iterates sources (evidence: `src/entities/link/model/getLinkPlanEntries.ts`)
- Entry Audit Loop → Safety Audit: audits paths (evidence: `src/entities/link/model/forEachLinkEntry.ts`)
- Safety Audit → Local Filesystem: inspects paths (evidence: `src/entities/link/model/audit.ts`)
- Workspace State → Link Execution: executes selections (evidence: `src/widgets/linking-workspace/model/useLinkingWorkspace.ts`)
- Workspace State → Unlink Operation: unlinks selections (evidence: `src/widgets/linking-workspace/model/useLinkingWorkspace.ts`)
- Link Execution → Entry Audit Loop: processes entries (evidence: `src/entities/link/model/linkEntries.ts`)
- Link Execution → Filesystem Linker: delegates operations (evidence: `src/entities/link/model/linkEntries.ts`)
- Filesystem Linker → Local Filesystem: moves and links
- Unlink Operation → Local Filesystem: removes symlinks
