# mdfyslsany-devobs/codepilot-local architecture

> Architecture diagram of the GitHub repository mdfyslsany-devobs/codepilot-local, 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/mdfyslsany-devobs/codepilot-local
- Repository: https://github.com/mdfyslsany-devobs/codepilot-local

## Overview

CodePilot Local turns user-supplied AI instructions into reviewed and approved project-file changes, with local storage and recovery. The desktop workflow selects a project, submits instructions, reviews a manifest and operation plan, approves it, then executes it. The parser’s distinct extraction and analysis stages feed manifest generation; server task routes coordinate planning and execution through the file engine. Backups, rollback, project/file access, authentication, and event broadcasting support the main workflow. The README also describes controlled terminal execution, but the supplied tree and excerpts do not identify its implementation. Dashed links mark documented or unverified connections.

Main entry points: [`packages/local-server/src/server.ts`](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/server.ts) (HTTP server), [`packages/file-engine/src/engine.ts`](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/engine.ts) (File engine), [`packages/instruction-parser/src/pipeline.ts`](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/pipeline.ts) (Parser pipeline), [`packages/file-engine/src/restore/restore-manager.ts`](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/restore/restore-manager.ts) (Restore manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop client"]
  node_desktop["Desktop workflow<br/>[App.tsx]"]
  node_api["API client<br/>[api.ts]"]
  node_preview["Manifest preview"]
end

subgraph group_server["Local server"]
  node_server["HTTP server<br/>[server.ts]"]
  node_auth["Authentication<br/>[auth-manager.ts]"]
  node_projects["Project routes<br/>[projects.ts]"]
  node_tasks["Task workflow<br/>[tasks.ts]"]
  node_files["File routes<br/>[files.ts]"]
  node_backuproutes["Backup routes<br/>[backups.ts]"]
  node_events["Event broadcaster<br/>[broadcaster.ts]"]
end

subgraph group_parse["Instruction parsing"]
  node_pipeline["Parser pipeline<br/>[pipeline.ts]"]
  node_structure["Folder detection"]
  node_language["Language detection"]
  node_duplicates["Duplicate detection"]
  node_missing["Content checks"]
  node_manifest["Manifest generation"]
end

subgraph group_engine["File operations"]
  node_engine["File engine<br/>[engine.ts]"]
  node_paths["Path validation<br/>[path-validator.ts]"]
  node_symlinks["Symlink guard<br/>[symlink-guard.ts]"]
  node_createfolder["Folder creation<br/>[folder-creator.ts]"]
  node_backup["Backup manager<br/>[backup-manager.ts]"]
  node_restore["Restore manager<br/>[restore-manager.ts]"]
  node_scanner["Project scanner<br/>[project-scanner.ts]"]
end

subgraph group_data["Local persistence"]
  node_database[("SQLite database<br/>[connection.ts]")]
  node_repositories["Repositories<br/>[index.ts]"]
  node_schema["Data schema<br/>[index.ts]"]
end

node_user(("User"))

node_user -->|"provides instructions"| node_desktop
node_desktop -->|"calls requests"| node_api
node_desktop -->|"renders preview"| node_preview
node_api -.->|"requests backend"| node_server
node_server -->|"creates manager"| node_auth
node_server -->|"registers routes"| node_projects
node_server -->|"registers routes"| node_tasks
node_server -->|"registers routes"| node_files
node_server -->|"registers routes"| node_backuproutes
node_server -->|"registers socket"| node_events
node_server -->|"initializes"| node_database
node_server -->|"constructs"| node_repositories
node_database -->|"loads schema"| node_schema
node_tasks -.->|"uses parser"| node_pipeline
node_pipeline -->|"detects folders"| node_structure
node_pipeline -->|"detects language"| node_language
node_pipeline -->|"finds duplicates"| node_duplicates
node_pipeline -->|"checks content"| node_missing
node_pipeline -->|"generates manifest"| node_manifest
node_tasks -.->|"plans and executes"| node_engine
node_files -.->|"uses engine"| node_engine
node_projects -.->|"scans projects"| node_engine
node_engine -->|"validates paths"| node_paths
node_engine -->|"checks links"| node_symlinks
node_engine -->|"creates folders"| node_createfolder
node_engine -.->|"creates backups"| node_backup
node_engine -.->|"restores files"| node_restore
node_engine -.->|"scans projects"| node_scanner
node_backup -->|"validates paths"| node_paths
node_restore -->|"validates paths"| node_paths
node_restore -->|"creates parents"| node_createfolder
node_backup -.->|"records backup"| node_repositories
node_restore -->|"marks restored"| node_repositories

click node_desktop "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/apps/desktop-ui/src/App.tsx"
click node_api "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/apps/desktop-ui/src/api.ts"
click node_preview "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/apps/desktop-ui/src/components/ManifestPreview.tsx"
click node_server "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/server.ts"
click node_auth "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/authentication/auth-manager.ts"
click node_projects "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/routes/projects.ts"
click node_tasks "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/routes/tasks.ts"
click node_files "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/routes/files.ts"
click node_backuproutes "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/routes/backups.ts"
click node_events "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/websocket/broadcaster.ts"
click node_pipeline "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/pipeline.ts"
click node_structure "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/folder-structure-detector.ts"
click node_language "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/language-detector.ts"
click node_duplicates "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/duplicate-detector.ts"
click node_missing "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/missing-content-detector.ts"
click node_manifest "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/manifest-generator.ts"
click node_engine "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/engine.ts"
click node_paths "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/security/path-validator.ts"
click node_symlinks "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/security/symlink-guard.ts"
click node_createfolder "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/creator/folder-creator.ts"
click node_backup "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/backup/backup-manager.ts"
click node_restore "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/restore/restore-manager.ts"
click node_scanner "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/scanner/project-scanner.ts"
click node_database "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/database/src/connection.ts"
click node_repositories "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/database/src/repositories/index.ts"
click node_schema "https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/database/src/schema/index.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_desktop,node_api,node_preview,node_user toneBlue
class node_server,node_auth,node_projects,node_tasks,node_files,node_backuproutes,node_events toneAmber
class node_pipeline,node_structure,node_language,node_duplicates,node_missing,node_manifest toneMint
class node_engine,node_paths,node_symlinks,node_createfolder,node_backup,node_restore,node_scanner toneRose
class node_database,node_repositories,node_schema toneIndigo
```

## Components

### Desktop client

- [Desktop workflow](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/apps/desktop-ui/src/App.tsx): `apps/desktop-ui/src/App.tsx`
- [API client](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/apps/desktop-ui/src/api.ts): `apps/desktop-ui/src/api.ts`
- [Manifest preview](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/apps/desktop-ui/src/components/ManifestPreview.tsx): `apps/desktop-ui/src/components/ManifestPreview.tsx`

### Local server

- [HTTP server](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/server.ts): `packages/local-server/src/server.ts`
- [Authentication](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/authentication/auth-manager.ts): `packages/local-server/src/authentication/auth-manager.ts`
- [Project routes](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/routes/projects.ts): `packages/local-server/src/routes/projects.ts`
- [Task workflow](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/routes/tasks.ts): `packages/local-server/src/routes/tasks.ts`
- [File routes](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/routes/files.ts): `packages/local-server/src/routes/files.ts`
- [Backup routes](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/routes/backups.ts): `packages/local-server/src/routes/backups.ts`
- [Event broadcaster](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/local-server/src/websocket/broadcaster.ts): `packages/local-server/src/websocket/broadcaster.ts`

### Instruction parsing

- [Parser pipeline](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/pipeline.ts): `packages/instruction-parser/src/pipeline.ts`
- [Folder detection](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/folder-structure-detector.ts): `packages/instruction-parser/src/folder-structure-detector.ts`
- [Language detection](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/language-detector.ts): `packages/instruction-parser/src/language-detector.ts`
- [Duplicate detection](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/duplicate-detector.ts): `packages/instruction-parser/src/duplicate-detector.ts`
- [Content checks](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/missing-content-detector.ts): `packages/instruction-parser/src/missing-content-detector.ts`
- [Manifest generation](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/instruction-parser/src/manifest-generator.ts): `packages/instruction-parser/src/manifest-generator.ts`

### File operations

- [File engine](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/engine.ts): `packages/file-engine/src/engine.ts`
- [Path validation](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/security/path-validator.ts): `packages/file-engine/src/security/path-validator.ts`
- [Symlink guard](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/security/symlink-guard.ts): `packages/file-engine/src/security/symlink-guard.ts`
- [Folder creation](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/creator/folder-creator.ts): `packages/file-engine/src/creator/folder-creator.ts`
- [Backup manager](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/backup/backup-manager.ts): `packages/file-engine/src/backup/backup-manager.ts`
- [Restore manager](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/restore/restore-manager.ts): `packages/file-engine/src/restore/restore-manager.ts`
- [Project scanner](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/file-engine/src/scanner/project-scanner.ts): `packages/file-engine/src/scanner/project-scanner.ts`

### Local persistence

- [SQLite database](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/database/src/connection.ts): `packages/database/src/connection.ts`
- [Repositories](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/database/src/repositories/index.ts): `packages/database/src/repositories/index.ts`
- [Data schema](https://github.com/mdfyslsany-devobs/codepilot-local/blob/codepilot-local/packages/database/src/schema/index.ts): `packages/database/src/schema/index.ts`

### Other components

- **User**

## Connections

- User → Desktop workflow: provides instructions (evidence: `apps/desktop-ui/src/App.tsx`)
- Desktop workflow → API client: calls requests (evidence: `apps/desktop-ui/src/App.tsx`)
- Desktop workflow → Manifest preview: renders preview (evidence: `apps/desktop-ui/src/App.tsx`)
- API client → HTTP server: requests backend (evidence: `README.md`)
- HTTP server → Authentication: creates manager (evidence: `packages/local-server/src/server.ts`)
- HTTP server → Project routes: registers routes (evidence: `packages/local-server/src/server.ts`)
- HTTP server → Task workflow: registers routes (evidence: `packages/local-server/src/server.ts`)
- HTTP server → File routes: registers routes (evidence: `packages/local-server/src/server.ts`)
- HTTP server → Backup routes: registers routes (evidence: `packages/local-server/src/server.ts`)
- HTTP server → Event broadcaster: registers socket (evidence: `packages/local-server/src/server.ts`)
- HTTP server → SQLite database: initializes (evidence: `packages/local-server/src/server.ts`)
- HTTP server → Repositories: constructs (evidence: `packages/local-server/src/server.ts`)
- SQLite database → Data schema: loads schema (evidence: `packages/database/src/connection.ts`)
- Task workflow → Parser pipeline: uses parser
- Parser pipeline → Folder detection: detects folders (evidence: `packages/instruction-parser/src/pipeline.ts`)
- Parser pipeline → Language detection: detects language (evidence: `packages/instruction-parser/src/pipeline.ts`)
- Parser pipeline → Duplicate detection: finds duplicates (evidence: `packages/instruction-parser/src/pipeline.ts`)
- Parser pipeline → Content checks: checks content (evidence: `packages/instruction-parser/src/pipeline.ts`)
- Parser pipeline → Manifest generation: generates manifest (evidence: `packages/instruction-parser/src/pipeline.ts`)
- Task workflow → File engine: plans and executes
- File routes → File engine: uses engine
- Project routes → File engine: scans projects
- File engine → Path validation: validates paths (evidence: `packages/file-engine/src/engine.ts`)
- File engine → Symlink guard: checks links (evidence: `packages/file-engine/src/engine.ts`)
- File engine → Folder creation: creates folders (evidence: `packages/file-engine/src/engine.ts`)
- File engine → Backup manager: creates backups (evidence: `packages/file-engine/src/engine.ts`)
- File engine → Restore manager: restores files (evidence: `packages/file-engine/src/engine.ts`)
- File engine → Project scanner: scans projects (evidence: `packages/file-engine/src/engine.ts`)
- Backup manager → Path validation: validates paths (evidence: `packages/file-engine/src/backup/backup-manager.ts`)
- Restore manager → Path validation: validates paths (evidence: `packages/file-engine/src/restore/restore-manager.ts`)
- Restore manager → Folder creation: creates parents (evidence: `packages/file-engine/src/restore/restore-manager.ts`)
- Backup manager → Repositories: records backup
- Restore manager → Repositories: marks restored (evidence: `packages/file-engine/src/restore/restore-manager.ts`)
