# maazi-ahmed/vorqen architecture

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

- Interactive diagram: https://gitdiagram.com/maazi-ahmed/vorqen
- Repository: https://github.com/maazi-ahmed/vorqen

## Overview

VORQEN is an Electron desktop workspace whose documented workflow selects and inspects a folder, runs a script against it, streams execution results, and refreshes the folder index. It also includes system discovery and AI file analysis. The tree and source index expose a second, substantial frontend workspace with file, project, migration, backup, storage, activity, and assistant routes; its behavior is not described in the README, so those capabilities are shown without speculative connections. Some subsystem links rely on source-index references rather than inspected implementation excerpts.

Main entry points: [`src/renderer/src/App.tsx`](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/App.tsx) (Desktop app), [`src/main/services/scanner/scanCoordinator.ts`](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/scanCoordinator.ts) (Scan coordinator), [`src/main/ipc/handlers.ts`](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/ipc/handlers.ts) (IPC handlers), [`src/main/services/ai/analysisCoordinator.ts`](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/analysisCoordinator.ts) (Analysis coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop_ui["Desktop renderer"]
  node_desktop_app["Desktop app<br/>[App.tsx]"]
  node_folder_picker["Folder picker<br/>[FolderPicker.tsx]"]
  node_folder_items["Folder inspection"]
  node_script_catalog["Script library<br/>[ScriptCatalog.tsx]"]
  node_console["Live console<br/>[ConsoleOutput.tsx]"]
  node_scanner_view["System discovery UI"]
  node_app_report["Application reports"]
  node_ai_view["AI analysis UI<br/>[AIAnalysisView.tsx]"]
  node_ai_details["Analysis details<br/>[AIDetailsModal.tsx]"]
end

subgraph group_main_services["Main process services"]
  node_preload["IPC bridge<br/>[index.ts]"]
  node_ipc_handlers["IPC handlers<br/>[handlers.ts]"]
  node_folder_service["Folder inspection service<br/>[fileSystem.ts]"]
  node_script_runner["Script execution<br/>[scriptRunner.ts]"]
  node_scan_coord["Scan coordinator<br/>[scanCoordinator.ts]"]
  node_system_discovery["Root discovery<br/>[systemDiscovery.ts]"]
  node_app_discovery["Application discovery"]
  node_app_association["File association"]
  node_file_inventory["File inventory<br/>[fileInventory.ts]"]
  node_report_builder["Report builder<br/>[reportBuilder.ts]"]
  node_analysis_coord["Analysis coordinator"]
  node_content_extract["Content extraction"]
  node_ai_provider["AI provider<br/>[aiProvider.ts]"]
  node_analysis_store[("Analysis cache<br/>[analysisStorage.ts]")]
end

subgraph group_web_workspace["Frontend workspace"]
  node_web_routes["Workspace routes"]
  node_web_assistant["Assistant interface<br/>[assistant.tsx]"]
  node_web_assistant_lib["Assistant client<br/>[assistant.ts]"]
  node_web_primitives["Workspace primitives<br/>[primitives.tsx]"]
end

node_user(("Desktop user"))
node_ai_service(("AI service"))

node_user -->|"uses"| node_desktop_app
node_desktop_app -->|"renders"| node_folder_picker
node_desktop_app -->|"renders"| node_folder_items
node_desktop_app -->|"renders"| node_script_catalog
node_desktop_app -->|"renders"| node_console
node_desktop_app -->|"renders"| node_scanner_view
node_desktop_app -->|"renders"| node_ai_view
node_scanner_view -->|"opens report"| node_app_report
node_ai_view -->|"opens details"| node_ai_details
node_desktop_app -->|"calls bridge"| node_preload
node_preload -->|"dispatches IPC"| node_ipc_handlers
node_ipc_handlers -->|"inspects folder"| node_folder_service
node_ipc_handlers -->|"runs scripts"| node_script_runner
node_ipc_handlers -->|"discovers roots"| node_system_discovery
node_ipc_handlers -->|"starts scans"| node_scan_coord
node_ipc_handlers -->|"starts analysis"| node_analysis_coord
node_scan_coord -->|"discovers roots"| node_system_discovery
node_scan_coord -->|"discovers apps"| node_app_discovery
node_scan_coord -->|"scans files"| node_file_inventory
node_scan_coord -->|"associates files"| node_app_association
node_scan_coord -.->|"builds reports"| node_report_builder
node_analysis_coord -->|"uses scan data"| node_scan_coord
node_analysis_coord -->|"extracts content"| node_content_extract
node_analysis_coord -->|"requests analysis"| node_ai_provider
node_analysis_coord -->|"reads and writes"| node_analysis_store
node_ai_provider -.->|"connects optionally"| node_ai_service
node_web_assistant -.->|"uses client"| node_web_assistant_lib
node_web_routes -.->|"uses UI"| node_web_primitives

click node_desktop_app "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/App.tsx"
click node_folder_picker "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/FolderPicker.tsx"
click node_folder_items "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/FolderItemsView.tsx"
click node_script_catalog "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/ScriptCatalog.tsx"
click node_console "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/ConsoleOutput.tsx"
click node_scanner_view "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/SystemScannerView.tsx"
click node_app_report "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/ApplicationReportModal.tsx"
click node_ai_view "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/AIAnalysisView.tsx"
click node_ai_details "https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/AIDetailsModal.tsx"
click node_preload "https://github.com/maazi-ahmed/vorqen/blob/main/src/preload/index.ts"
click node_ipc_handlers "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/ipc/handlers.ts"
click node_folder_service "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/fileSystem.ts"
click node_script_runner "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scriptRunner.ts"
click node_scan_coord "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/scanCoordinator.ts"
click node_system_discovery "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/systemDiscovery.ts"
click node_app_discovery "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/applicationDiscovery.ts"
click node_app_association "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/applicationAssociation.ts"
click node_file_inventory "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/fileInventory.ts"
click node_report_builder "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/reportBuilder.ts"
click node_analysis_coord "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/analysisCoordinator.ts"
click node_content_extract "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/contentExtractor.ts"
click node_ai_provider "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/aiProvider.ts"
click node_analysis_store "https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/analysisStorage.ts"
click node_web_routes "https://github.com/maazi-ahmed/vorqen/tree/main/frontend/src/routes"
click node_web_assistant "https://github.com/maazi-ahmed/vorqen/blob/main/frontend/src/routes/assistant.tsx"
click node_web_assistant_lib "https://github.com/maazi-ahmed/vorqen/blob/main/frontend/src/lib/assistant.ts"
click node_web_primitives "https://github.com/maazi-ahmed/vorqen/blob/main/frontend/src/components/vq/primitives.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_desktop_app,node_folder_picker,node_folder_items,node_script_catalog,node_console,node_scanner_view,node_app_report,node_ai_view,node_ai_details,node_user toneBlue
class node_preload,node_ipc_handlers,node_folder_service,node_script_runner,node_scan_coord,node_system_discovery,node_app_discovery,node_app_association,node_file_inventory,node_report_builder,node_analysis_coord,node_content_extract,node_ai_provider,node_analysis_store toneAmber
class node_web_routes,node_web_assistant,node_web_assistant_lib,node_web_primitives toneMint
class node_ai_service toneIndigo
```

## Components

### Desktop renderer

- [Desktop app](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Folder picker](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/FolderPicker.tsx): `src/renderer/src/components/FolderPicker.tsx`
- [Folder inspection](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/FolderItemsView.tsx): `src/renderer/src/components/FolderItemsView.tsx`
- [Script library](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/ScriptCatalog.tsx): `src/renderer/src/components/ScriptCatalog.tsx`
- [Live console](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/ConsoleOutput.tsx): `src/renderer/src/components/ConsoleOutput.tsx`
- [System discovery UI](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/SystemScannerView.tsx): `src/renderer/src/components/SystemScannerView.tsx`
- [Application reports](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/ApplicationReportModal.tsx): `src/renderer/src/components/ApplicationReportModal.tsx`
- [AI analysis UI](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/AIAnalysisView.tsx): `src/renderer/src/components/AIAnalysisView.tsx`
- [Analysis details](https://github.com/maazi-ahmed/vorqen/blob/main/src/renderer/src/components/AIDetailsModal.tsx): `src/renderer/src/components/AIDetailsModal.tsx`

### Main process services

- [IPC bridge](https://github.com/maazi-ahmed/vorqen/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [IPC handlers](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/ipc/handlers.ts): `src/main/ipc/handlers.ts`
- [Folder inspection service](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/fileSystem.ts): `src/main/services/fileSystem.ts`
- [Script execution](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scriptRunner.ts): `src/main/services/scriptRunner.ts`
- [Scan coordinator](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/scanCoordinator.ts): `src/main/services/scanner/scanCoordinator.ts`
- [Root discovery](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/systemDiscovery.ts): `src/main/services/scanner/systemDiscovery.ts`
- [Application discovery](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/applicationDiscovery.ts): `src/main/services/scanner/applicationDiscovery.ts`
- [File association](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/applicationAssociation.ts): `src/main/services/scanner/applicationAssociation.ts`
- [File inventory](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/fileInventory.ts): `src/main/services/scanner/fileInventory.ts`
- [Report builder](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/scanner/reportBuilder.ts): `src/main/services/scanner/reportBuilder.ts`
- [Analysis coordinator](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/analysisCoordinator.ts): `src/main/services/ai/analysisCoordinator.ts`
- [Content extraction](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/contentExtractor.ts): `src/main/services/ai/contentExtractor.ts`
- [AI provider](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/aiProvider.ts): `src/main/services/ai/aiProvider.ts`
- [Analysis cache](https://github.com/maazi-ahmed/vorqen/blob/main/src/main/services/ai/analysisStorage.ts): `src/main/services/ai/analysisStorage.ts`

### Frontend workspace

- [Workspace routes](https://github.com/maazi-ahmed/vorqen/tree/main/frontend/src/routes): `frontend/src/routes`
- [Assistant interface](https://github.com/maazi-ahmed/vorqen/blob/main/frontend/src/routes/assistant.tsx): `frontend/src/routes/assistant.tsx`
- [Assistant client](https://github.com/maazi-ahmed/vorqen/blob/main/frontend/src/lib/assistant.ts): `frontend/src/lib/assistant.ts`
- [Workspace primitives](https://github.com/maazi-ahmed/vorqen/blob/main/frontend/src/components/vq/primitives.tsx): `frontend/src/components/vq/primitives.tsx`

### Other components

- **Desktop user**
- **AI service**

## Connections

- Desktop user → Desktop app: uses (evidence: `README.md`)
- Desktop app → Folder picker: renders (evidence: `src/renderer/src/App.tsx`)
- Desktop app → Folder inspection: renders (evidence: `src/renderer/src/App.tsx`)
- Desktop app → Script library: renders (evidence: `src/renderer/src/App.tsx`)
- Desktop app → Live console: renders (evidence: `src/renderer/src/App.tsx`)
- Desktop app → System discovery UI: renders (evidence: `src/renderer/src/App.tsx`)
- Desktop app → AI analysis UI: renders (evidence: `src/renderer/src/App.tsx`)
- System discovery UI → Application reports: opens report (evidence: `src/renderer/src/components/SystemScannerView.tsx`)
- AI analysis UI → Analysis details: opens details (evidence: `src/renderer/src/components/AIAnalysisView.tsx`)
- Desktop app → IPC bridge: calls bridge (evidence: `README.md`)
- IPC bridge → IPC handlers: dispatches IPC (evidence: `README.md`)
- IPC handlers → Folder inspection service: inspects folder (evidence: `src/main/ipc/handlers.ts`)
- IPC handlers → Script execution: runs scripts (evidence: `src/main/ipc/handlers.ts`)
- IPC handlers → Root discovery: discovers roots (evidence: `src/main/ipc/handlers.ts`)
- IPC handlers → Scan coordinator: starts scans (evidence: `src/main/ipc/handlers.ts`)
- IPC handlers → Analysis coordinator: starts analysis (evidence: `src/main/ipc/handlers.ts`)
- Scan coordinator → Root discovery: discovers roots (evidence: `src/main/services/scanner/scanCoordinator.ts`)
- Scan coordinator → Application discovery: discovers apps (evidence: `src/main/services/scanner/scanCoordinator.ts`)
- Scan coordinator → File inventory: scans files (evidence: `src/main/services/scanner/scanCoordinator.ts`)
- Scan coordinator → File association: associates files (evidence: `src/main/services/scanner/scanCoordinator.ts`)
- Scan coordinator → Report builder: builds reports (evidence: `src/main/services/scanner/scanCoordinator.ts`)
- Analysis coordinator → Scan coordinator: uses scan data (evidence: `src/main/services/ai/analysisCoordinator.ts`)
- Analysis coordinator → Content extraction: extracts content (evidence: `src/main/services/ai/analysisCoordinator.ts`)
- Analysis coordinator → AI provider: requests analysis (evidence: `src/main/services/ai/analysisCoordinator.ts`)
- Analysis coordinator → Analysis cache: reads and writes (evidence: `src/main/services/ai/analysisCoordinator.ts`)
- AI provider → AI service: connects optionally
- Assistant interface → Assistant client: uses client
- Workspace routes → Workspace primitives: uses UI