# hkpc-labs/snapcode-suite architecture

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

- Interactive diagram: https://gitdiagram.com/hkpc-labs/snapcode-suite
- Repository: https://github.com/hkpc-labs/snapcode-suite

## Overview

Snapcode is a visual Flutter-app authoring product, represented here by both its Windows IDE and a web editor/worker implementation. The main workflow is designing UI or Blockly logic, generating Dart, preserving developer edits, and running the Flutter project on a discovered device. The README documents the desktop compile-and-run path; source-index references and excerpts support the specific implementation links shown. Some web/worker wiring and unsampled desktop view interactions are not verified, so those connections are omitted.

Main entry points: [`snapcode-frontend/src/pages/EditorPage.jsx`](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/pages/EditorPage.jsx) (Web Editor), [`src/Services/ProjectService.cs`](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/ProjectService.cs) (Project Files), [`src/Services/FlutterCompilerService.cs`](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/FlutterCompilerService.cs) (Flutter Compiler), [`src/Services/UserCodePreservationService.cs`](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/UserCodePreservationService.cs) (Code Preservation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Windows IDE"]
  node_native_designer["UI Designer"]
  node_desktop_editor["Editor Page<br/>[EditorPage.xaml.cs]"]
  node_project_service["Project Files<br/>[ProjectService.cs]"]
  node_page_metadata["Page Metadata<br/>[PageMetadata.cs]"]
  node_template_service["Project Templates<br/>[TemplateService.cs]"]
  node_flutter_compiler["Flutter Compiler"]
  node_preservation["Code Preservation"]
  node_dart_formatter["Dart Formatter"]
  node_asset_dialog["Asset Manager"]
  node_asset_service["Asset Service<br/>[AssetService.cs]"]
  node_project_explorer["Project Explorer"]
  node_device_dialog["Device Manager"]
  node_device_service["Device Discovery<br/>[DeviceService.cs]"]
end

subgraph group_web["Web Editor"]
  node_web_editor["Web Editor<br/>[EditorPage.jsx]"]
  node_block_editor["Blockly Canvas<br/>[BlockEditor.jsx]"]
  node_dart_generator["Dart Generator<br/>[dartGenerator.js]"]
  node_code_preview["Code Preview<br/>[CodePreview.jsx]"]
  node_export_panel["Export Panel<br/>[ExportPanel.jsx]"]
  node_auth_context["Authentication<br/>[AuthContext.jsx]"]
  node_api_service["API Client<br/>[api.js]"]
end

subgraph group_backend["Cloud Workers"]
  node_worker_auth["Token Verification<br/>[auth.js]"]
  node_state_worker["Project State Worker<br/>[state-worker.js]"]
  node_consumer_worker["Build Consumer<br/>[consumer-worker.js]"]
  node_project_builder["Project Builder<br/>[projectBuilder.js]"]
  node_dart_emitter["Dart Emitter<br/>[dartEmitter.js]"]
end

subgraph group_flutter["Flutter Toolchain"]
  node_flutter_runner["Flutter Runner"]
end

node_developer(("Developer"))
node_target_device(("Target Device"))
node_firebase_auth["Firebase Auth"]

node_developer -->|"designs UI"| node_native_designer
node_developer -->|"authors project"| node_web_editor
node_native_designer -->|"compiles layout"| node_flutter_compiler
node_desktop_editor -.->|"manages project"| node_project_service
node_project_service -->|"loads metadata"| node_page_metadata
node_template_service -->|"creates project"| node_project_service
node_project_service -->|"generates Dart"| node_flutter_compiler
node_project_service -->|"saves preserving code"| node_preservation
node_flutter_compiler -->|"preserves edits"| node_preservation
node_preservation -->|"formats Dart"| node_dart_formatter
node_flutter_compiler -->|"formats output"| node_dart_formatter
node_asset_dialog -->|"imports assets"| node_asset_service
node_developer -->|"selects device"| node_device_dialog
node_device_dialog -->|"scans devices"| node_device_service
node_flutter_compiler -->|"produces app code"| node_flutter_runner
node_flutter_runner -->|"runs app"| node_target_device
node_web_editor -->|"renders canvas"| node_block_editor
node_web_editor -->|"generates Dart"| node_dart_generator
node_web_editor -->|"shows generated code"| node_code_preview
node_web_editor -->|"offers export"| node_export_panel
node_auth_context -->|"authenticates users"| node_firebase_auth
node_auth_context -.->|"syncs user"| node_api_service
node_api_service -.->|"sends bearer token"| node_worker_auth
node_state_worker -->|"verifies requests"| node_worker_auth
node_consumer_worker -->|"builds project"| node_project_builder
node_project_builder -->|"emits Dart"| node_dart_emitter

click node_native_designer "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Views/NativeUIDesigner.xaml.cs"
click node_desktop_editor "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Views/EditorPage.xaml.cs"
click node_project_service "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/ProjectService.cs"
click node_page_metadata "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Models/PageMetadata.cs"
click node_template_service "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/TemplateService.cs"
click node_flutter_compiler "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/FlutterCompilerService.cs"
click node_preservation "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/UserCodePreservationService.cs"
click node_dart_formatter "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/DartFormatterService.cs"
click node_asset_dialog "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Views/AssetManagerDialog.xaml.cs"
click node_asset_service "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/AssetService.cs"
click node_project_explorer "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/ViewModels/ProjectExplorerViewModel.cs"
click node_device_dialog "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Views/EmulatorManagerDialog.xaml.cs"
click node_device_service "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/DeviceService.cs"
click node_flutter_runner "https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/FlutterExecutionService.cs"
click node_web_editor "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/pages/EditorPage.jsx"
click node_block_editor "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/components/BlockEditor.jsx"
click node_dart_generator "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/blockly/generators/dartGenerator.js"
click node_code_preview "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/components/CodePreview.jsx"
click node_export_panel "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/components/ExportPanel.jsx"
click node_auth_context "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/contexts/AuthContext.jsx"
click node_api_service "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/services/api.js"
click node_worker_auth "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/middleware/auth.js"
click node_state_worker "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/state-worker.js"
click node_consumer_worker "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/consumer-worker.js"
click node_project_builder "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/codegen/projectBuilder.js"
click node_dart_emitter "https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/codegen/dartEmitter.js"

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_native_designer,node_desktop_editor,node_project_service,node_page_metadata,node_template_service,node_flutter_compiler,node_preservation,node_dart_formatter,node_asset_dialog,node_asset_service,node_project_explorer,node_device_dialog,node_device_service toneBlue
class node_web_editor,node_block_editor,node_dart_generator,node_code_preview,node_export_panel,node_auth_context,node_api_service toneAmber
class node_worker_auth,node_state_worker,node_consumer_worker,node_project_builder,node_dart_emitter toneMint
class node_flutter_runner toneRose
class node_developer,node_target_device,node_firebase_auth toneIndigo
```

## Components

### Windows IDE

- [UI Designer](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Views/NativeUIDesigner.xaml.cs): `src/Views/NativeUIDesigner.xaml.cs`
- [Editor Page](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Views/EditorPage.xaml.cs): `src/Views/EditorPage.xaml.cs`
- [Project Files](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/ProjectService.cs): `src/Services/ProjectService.cs`
- [Page Metadata](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Models/PageMetadata.cs): `src/Models/PageMetadata.cs`
- [Project Templates](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/TemplateService.cs): `src/Services/TemplateService.cs`
- [Flutter Compiler](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/FlutterCompilerService.cs): `src/Services/FlutterCompilerService.cs`
- [Code Preservation](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/UserCodePreservationService.cs): `src/Services/UserCodePreservationService.cs`
- [Dart Formatter](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/DartFormatterService.cs): `src/Services/DartFormatterService.cs`
- [Asset Manager](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Views/AssetManagerDialog.xaml.cs): `src/Views/AssetManagerDialog.xaml.cs`
- [Asset Service](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/AssetService.cs): `src/Services/AssetService.cs`
- [Project Explorer](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/ViewModels/ProjectExplorerViewModel.cs): `src/ViewModels/ProjectExplorerViewModel.cs`
- [Device Manager](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Views/EmulatorManagerDialog.xaml.cs): `src/Views/EmulatorManagerDialog.xaml.cs`
- [Device Discovery](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/DeviceService.cs): `src/Services/DeviceService.cs`

### Web Editor

- [Web Editor](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/pages/EditorPage.jsx): `snapcode-frontend/src/pages/EditorPage.jsx`
- [Blockly Canvas](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/components/BlockEditor.jsx): `snapcode-frontend/src/components/BlockEditor.jsx`
- [Dart Generator](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/blockly/generators/dartGenerator.js): `snapcode-frontend/src/blockly/generators/dartGenerator.js`
- [Code Preview](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/components/CodePreview.jsx): `snapcode-frontend/src/components/CodePreview.jsx`
- [Export Panel](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/components/ExportPanel.jsx): `snapcode-frontend/src/components/ExportPanel.jsx`
- [Authentication](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/contexts/AuthContext.jsx): `snapcode-frontend/src/contexts/AuthContext.jsx`
- [API Client](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-frontend/src/services/api.js): `snapcode-frontend/src/services/api.js`

### Cloud Workers

- [Token Verification](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/middleware/auth.js): `snapcode-workers/src/middleware/auth.js`
- [Project State Worker](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/state-worker.js): `snapcode-workers/src/state-worker.js`
- [Build Consumer](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/consumer-worker.js): `snapcode-workers/src/consumer-worker.js`
- [Project Builder](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/codegen/projectBuilder.js): `snapcode-workers/src/codegen/projectBuilder.js`
- [Dart Emitter](https://github.com/hkpc-labs/snapcode-suite/blob/master/snapcode-workers/src/codegen/dartEmitter.js): `snapcode-workers/src/codegen/dartEmitter.js`

### Flutter Toolchain

- [Flutter Runner](https://github.com/hkpc-labs/snapcode-suite/blob/master/src/Services/FlutterExecutionService.cs): `src/Services/FlutterExecutionService.cs`

### Other components

- **Developer**
- **Target Device**
- **Firebase Auth**

## Connections

- Developer → UI Designer: designs UI
- Developer → Web Editor: authors project
- UI Designer → Flutter Compiler: compiles layout
- Editor Page → Project Files: manages project
- Project Files → Page Metadata: loads metadata (evidence: `src/Services/ProjectService.cs`)
- Project Templates → Project Files: creates project (evidence: `src/Services/TemplateService.cs`)
- Project Files → Flutter Compiler: generates Dart (evidence: `src/Services/ProjectService.cs`)
- Project Files → Code Preservation: saves preserving code (evidence: `src/Services/ProjectService.cs`)
- Flutter Compiler → Code Preservation: preserves edits
- Code Preservation → Dart Formatter: formats Dart (evidence: `src/Services/UserCodePreservationService.cs`)
- Flutter Compiler → Dart Formatter: formats output (evidence: `src/Services/FlutterCompilerService.cs`)
- Asset Manager → Asset Service: imports assets (evidence: `src/Views/AssetManagerDialog.xaml.cs`)
- Developer → Device Manager: selects device
- Device Manager → Device Discovery: scans devices (evidence: `src/Views/EmulatorManagerDialog.xaml.cs`)
- Flutter Compiler → Flutter Runner: produces app code
- Flutter Runner → Target Device: runs app
- Web Editor → Blockly Canvas: renders canvas (evidence: `snapcode-frontend/src/pages/EditorPage.jsx`)
- Web Editor → Dart Generator: generates Dart (evidence: `snapcode-frontend/src/pages/EditorPage.jsx`)
- Web Editor → Code Preview: shows generated code (evidence: `snapcode-frontend/src/pages/EditorPage.jsx`)
- Web Editor → Export Panel: offers export (evidence: `snapcode-frontend/src/pages/EditorPage.jsx`)
- Authentication → Firebase Auth: authenticates users (evidence: `snapcode-frontend/src/contexts/AuthContext.jsx`)
- Authentication → API Client: syncs user
- API Client → Token Verification: sends bearer token
- Project State Worker → Token Verification: verifies requests (evidence: `snapcode-workers/src/state-worker.js`)
- Build Consumer → Project Builder: builds project (evidence: `snapcode-workers/src/consumer-worker.js`)
- Project Builder → Dart Emitter: emits Dart (evidence: `snapcode-workers/src/codegen/projectBuilder.js`)
