# dhananjay-ryu-jin-sama/wavical architecture

> Architecture diagram of the GitHub repository dhananjay-ryu-jin-sama/wavical, 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/dhananjay-ryu-jin-sama/wavical
- Repository: https://github.com/dhananjay-ryu-jin-sama/wavical

## Overview

Wavical is a Windows desktop-app framework: developers scaffold and build HTML/CSS/JavaScript projects, then run them in a native WebView2 shell. The shell brokers default-deny, capability-gated IPC to native OS features and optional AI, Node.js backend, and signed updater services. The graph preserves those distinct product stages and branches. Source excerpts are partial, so links for documented but unsampled features rely on the README; uncertain implementation-level connections are omitted.

Main entry points: [`crates/wavical-cli/src/lib.rs`](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/lib.rs) (Wavical CLI), [`crates/wavical-ipc/src/lib.rs`](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/lib.rs) (IPC dispatcher), [`crates/wavical-shell/src/lib.rs`](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/lib.rs) (Shell services), [`crates/wavical-shell/src/updater.rs`](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/updater.rs) (Signed auto-updater)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_project["Project lifecycle"]
  node_cli["Wavical CLI<br/>[lib.rs]"]
  node_scaffold["Project scaffolding<br/>[scaffold.rs]"]
  node_config["App configuration<br/>[lib.rs]"]
  node_assetbuild["Asset build<br/>[lib.rs]"]
  node_backendbuild["Backend bundling<br/>[backend_build.rs]"]
  node_runtimecache["Runtime management<br/>[runtime.rs]"]
  node_signing["Release signing<br/>[signer.rs]"]
end

subgraph group_desktop["Desktop runtime"]
  node_shell["WebView2 shell<br/>[main.rs]"]
  node_shellruntime["Shell services<br/>[lib.rs]"]
  node_protocol["Asset and backend protocol<br/>[lib.rs]"]
  node_native["Native OS services<br/>[lib.rs]"]
end

subgraph group_ipc["Capability IPC"]
  node_ipc["IPC dispatcher<br/>[lib.rs]"]
  node_grants["Scoped file grants<br/>[grants.rs]"]
  node_aiipc["AI IPC validation<br/>[ai.rs]"]
end

subgraph group_ai["AI services"]
  node_aiworkflow["Chat and RAG<br/>[chat.rs]"]
  node_aimodels[("Model catalog and storage<br/>[catalog.rs]")]
  node_aimanager["Local engine lifecycle<br/>[manager.rs]"]
  node_cloudai["Cloud AI client<br/>[cloud_client.rs]"]
end

subgraph group_extensions["Optional services"]
  node_backend["Sandboxed Node backend<br/>[backend.rs]"]
  node_updater["Signed auto-updater<br/>[updater.rs]"]
  node_updatepolicy["Update manifest validation<br/>[update_manifest.rs]"]
end

node_developer(("App developer"))
node_node["Node.js runtime"]
node_webapp(("App WebView"))
node_modelhost(("Model download host"))
node_cloudprovider(("Cloud AI provider"))
node_updatehost(("Update server"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"scaffolds project"| node_scaffold
node_cli -->|"evaluates config"| node_config
node_cli -->|"builds assets"| node_assetbuild
node_assetbuild -->|"bundles backend"| node_backendbuild
node_cli -->|"manages runtime"| node_runtimecache
node_cli -->|"signs releases"| node_signing
node_cli -->|"launches shell"| node_shell
node_shell -->|"starts services"| node_shellruntime
node_shellruntime -->|"uses protocol"| node_protocol
node_shellruntime -->|"dispatches IPC"| node_ipc
node_shellruntime -->|"manages backend"| node_backend
node_shellruntime -->|"runs updater"| node_updater
node_webapp -->|"invokes methods"| node_ipc
node_ipc -->|"dispatches native calls"| node_native
node_ipc -->|"checks file grants"| node_grants
node_ipc -->|"validates AI requests"| node_aiipc
node_aiipc -->|"routes AI requests"| node_aiworkflow
node_aiworkflow -.->|"uses local engine"| node_aimanager
node_aimanager -.->|"loads model"| node_aimodels
node_aiworkflow -.->|"uses cloud mode"| node_cloudai
node_aimodels -->|"downloads models"| node_modelhost
node_cloudai -->|"sends requests"| node_cloudprovider
node_backend -->|"runs backend"| node_node
node_ipc -->|"routes backend calls"| node_backend
node_ipc -->|"routes update calls"| node_updater
node_updater -.->|"validates manifest"| node_updatepolicy
node_updater -->|"checks releases"| node_updatehost

click node_cli "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/lib.rs"
click node_scaffold "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/scaffold.rs"
click node_config "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-config/src/lib.rs"
click node_assetbuild "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/lib.rs"
click node_backendbuild "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/backend_build.rs"
click node_runtimecache "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/runtime.rs"
click node_signing "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/signer.rs"
click node_shell "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/main.rs"
click node_shellruntime "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/lib.rs"
click node_protocol "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-protocol/src/lib.rs"
click node_native "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-native/src/lib.rs"
click node_ipc "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/lib.rs"
click node_grants "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/grants.rs"
click node_aiipc "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/ai.rs"
click node_aiworkflow "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/chat.rs"
click node_aimodels "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/catalog.rs"
click node_aimanager "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/manager.rs"
click node_cloudai "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/cloud_client.rs"
click node_backend "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/backend.rs"
click node_updater "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/updater.rs"
click node_updatepolicy "https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/update_manifest.rs"

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_cli,node_scaffold,node_config,node_assetbuild,node_backendbuild,node_runtimecache,node_signing,node_webapp toneBlue
class node_shell,node_shellruntime,node_protocol,node_native toneAmber
class node_ipc,node_grants,node_aiipc,node_updatehost toneMint
class node_aiworkflow,node_aimodels,node_aimanager,node_cloudai toneRose
class node_backend,node_updater,node_updatepolicy,node_developer,node_node,node_modelhost,node_cloudprovider toneIndigo
```

## Components

### Project lifecycle

- [Wavical CLI](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/lib.rs): `crates/wavical-cli/src/lib.rs`
- [Project scaffolding](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/scaffold.rs): `crates/wavical-ai/src/scaffold.rs`
- [App configuration](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-config/src/lib.rs): `crates/wavical-config/src/lib.rs`
- [Asset build](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/lib.rs): `crates/wavical-cli/src/lib.rs`
- [Backend bundling](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/backend_build.rs): `crates/wavical-cli/src/backend_build.rs`
- [Runtime management](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/runtime.rs): `crates/wavical-cli/src/runtime.rs`
- [Release signing](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-cli/src/signer.rs): `crates/wavical-cli/src/signer.rs`

### Desktop runtime

- [WebView2 shell](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/main.rs): `crates/wavical-shell/src/main.rs`
- [Shell services](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/lib.rs): `crates/wavical-shell/src/lib.rs`
- [Asset and backend protocol](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-protocol/src/lib.rs): `crates/wavical-protocol/src/lib.rs`
- [Native OS services](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-native/src/lib.rs): `crates/wavical-native/src/lib.rs`

### Capability IPC

- [IPC dispatcher](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/lib.rs): `crates/wavical-ipc/src/lib.rs`
- [Scoped file grants](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/grants.rs): `crates/wavical-ipc/src/grants.rs`
- [AI IPC validation](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/ai.rs): `crates/wavical-ipc/src/ai.rs`

### AI services

- [Chat and RAG](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/chat.rs): `crates/wavical-ai/src/chat.rs`
- [Model catalog and storage](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/catalog.rs): `crates/wavical-ai/src/catalog.rs`
- [Local engine lifecycle](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/manager.rs): `crates/wavical-ai/src/manager.rs`
- [Cloud AI client](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ai/src/cloud_client.rs): `crates/wavical-ai/src/cloud_client.rs`

### Optional services

- [Sandboxed Node backend](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/backend.rs): `crates/wavical-shell/src/backend.rs`
- [Signed auto-updater](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-shell/src/updater.rs): `crates/wavical-shell/src/updater.rs`
- [Update manifest validation](https://github.com/dhananjay-ryu-jin-sama/wavical/blob/main/crates/wavical-ipc/src/update_manifest.rs): `crates/wavical-ipc/src/update_manifest.rs`

### Other components

- **App developer**
- **Node.js runtime**
- **App WebView**
- **Model download host**
- **Cloud AI provider**
- **Update server**

## Connections

- App developer → Wavical CLI: runs commands (evidence: `README.md`)
- Wavical CLI → Project scaffolding: scaffolds project (evidence: `README.md`)
- Wavical CLI → App configuration: evaluates config (evidence: `README.md`)
- Wavical CLI → Asset build: builds assets (evidence: `crates/wavical-cli/src/lib.rs`)
- Asset build → Backend bundling: bundles backend (evidence: `crates/wavical-cli/src/lib.rs`)
- Wavical CLI → Runtime management: manages runtime (evidence: `crates/wavical-cli/src/lib.rs`)
- Wavical CLI → Release signing: signs releases (evidence: `README.md`)
- Wavical CLI → WebView2 shell: launches shell (evidence: `README.md`)
- WebView2 shell → Shell services: starts services (evidence: `crates/wavical-shell/src/main.rs`)
- Shell services → Asset and backend protocol: uses protocol (evidence: `crates/wavical-shell/src/lib.rs`)
- Shell services → IPC dispatcher: dispatches IPC (evidence: `crates/wavical-shell/src/lib.rs`)
- Shell services → Sandboxed Node backend: manages backend (evidence: `crates/wavical-shell/src/lib.rs`)
- Shell services → Signed auto-updater: runs updater (evidence: `crates/wavical-shell/src/lib.rs`)
- App WebView → IPC dispatcher: invokes methods (evidence: `README.md`)
- IPC dispatcher → Native OS services: dispatches native calls (evidence: `crates/wavical-ipc/src/lib.rs`)
- IPC dispatcher → Scoped file grants: checks file grants (evidence: `crates/wavical-ipc/src/lib.rs`)
- IPC dispatcher → AI IPC validation: validates AI requests (evidence: `crates/wavical-ipc/src/lib.rs`)
- AI IPC validation → Chat and RAG: routes AI requests (evidence: `README.md`)
- Chat and RAG → Local engine lifecycle: uses local engine
- Local engine lifecycle → Model catalog and storage: loads model
- Chat and RAG → Cloud AI client: uses cloud mode (evidence: `README.md`)
- Model catalog and storage → Model download host: downloads models (evidence: `README.md`)
- Cloud AI client → Cloud AI provider: sends requests (evidence: `README.md`)
- Sandboxed Node backend → Node.js runtime: runs backend (evidence: `README.md`)
- IPC dispatcher → Sandboxed Node backend: routes backend calls (evidence: `README.md`)
- IPC dispatcher → Signed auto-updater: routes update calls (evidence: `README.md`)
- Signed auto-updater → Update manifest validation: validates manifest
- Signed auto-updater → Update server: checks releases (evidence: `README.md`)
