# seeed-studio/sensecraft-web-toolkit architecture

> Architecture diagram of the GitHub repository seeed-studio/sensecraft-web-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seeed-studio/sensecraft-web-toolkit
- Repository: https://github.com/seeed-studio/sensecraft-web-toolkit

## Overview

##### Project Type & Purpose
- This is a front-end Single-Page Application (SPA) built with Vue.js (via Vite) and Vuetify.
- Purpose: Provide a visual programming toolkit for AIoT devices (SenseCraft platform), including device flashing, configuration, and interaction.

##### File Structure
- Top-level build & config:
- config/ (Vite configs, plugins for compression, image minification, visualizer)
- docker/ (Dockerfile + Nginx config)
- GitHub workflows & Husky (CI/CD, linting, commit hooks)
- Makefile, package.json, env files
- src/ directory (runtime code):
- src/main.ts + index.html → app bootstrap
- src/App.vue + pages/ + components/ → UI layer
- src/router/ → navigation & route guards
- src/store/ → Vuex store modules (app state, device state, tab-bar)
- src/sscma/ → device-communication library (serial, XModem, device abstractions for Grove AI WE2, Xiao ESP32S3)
- src/utils/ → helper services (env, event bus, firebase, flash, timer, route listener)
- src/hooks/ → composable logic (device manager, permission, themes, loading, detection)
- src/assets/ → static images, styles, world.json
- Config files: eslint, prettier, stylelint, tsconfig

##### README Insights
- Built with Vue.js & Vuetify
- Deployable via Vite build → dist → served by any static server (e.g., Nginx or http-server)
- Customizable for different SenseCraft environments

##### Main Components & Their Relationships
a. Browser (User’s machine)
- Hosts the Vue SPA served by Nginx (in production) or Vite dev server
b. Vue Application
- UI Layer: pages & reusable components
- Router: client-side routing & guards
- Store: centralized state management
- Service Layer:
- sscma library → direct device communication (Web Serial / USB)
- utils/firebase → optional cloud services
- utils/flash → firmware flashing logic
- hooks/composables → isolate business logic
c. External Systems
- SenseCraft backend API (config, telemetry) – endpoint defined via env variables
- IoT Devices (Grove AI WE2, Xiao ESP32S3) via serial protocols (XModem, custom drivers)
- Firebase (for authentication, data storage)
d. Build & Deployment Pipeline
- GitHub Actions → run lint/tests → build Docker image
- Docker + Nginx → serve built files
- CI/CD pushes to hosting or edge servers

##### Architectural Patterns & Principles
- Modular SPA: clear separation between UI, state, and services
- Composable MVVM (Vue + Composition API)
- Plugin-based build (Vite + custom plugins for optimization)
- Layered design:
- Presentation (components/pages)
- Application (router + store)
- Infrastructure (sscma, utils, external APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workflow & CI/CD
    subgraph "Developer Workflow & CI/CD"
        Repo["GitHub Repository"]:::devops
        Actions["GitHub Actions"]:::devops
        LintHooks["Linting & Git Hooks"]:::devops
        Repo -->|"push/pull request"| Actions
        Actions -->|"run lint/tests"| LintHooks
        Actions -->|"build Docker image"| DockerImage
    end

    %% Deployment
    subgraph "Deployment"
        DockerImage["Docker Image"]:::build
        Nginx["Nginx Server"]:::build
        DockerImage -->|"deploy image"| Nginx
    end

    %% Runtime (Browser)
    subgraph "Runtime (Browser)" 
        direction TB
        Bootstrap["App Bootstrap"]:::frontend
        subgraph "Frontend Layer"
            direction TB
            UI["UI Layer (Components & Pages)"]:::frontend
            Router["Vue Router"]:::frontend
            Store["Vuex Store"]:::frontend
            Services["Service Layer"]:::service
            Hooks["Composable Hooks"]:::frontend
            Assets["Static Assets"]:::frontend
            Config["Global Settings"]:::frontend
            Permission["Permission Directive"]:::frontend
        end
        Bootstrap --> UI
        Bootstrap --> Router
        Bootstrap --> Store
        UI -->|dispatch action| Store
        UI -->|navigate| Router
        Router -->|guard/check| Store
        Store -->|"invoke service"| Services
        Services -->|"emit events"| Hooks
        UI -->|"use hooks"| Hooks
        UI -->|"load assets"| Assets
        Services -->|read| Config
        UI -->|use| Permission
    end

    %% Service Layer Details
    subgraph "Service Layer Components"
        direction TB
        SSCMA["sscma Device Library"]:::service
        Flash["Flashing Service"]:::service
        FirebaseSrv["Firebase Service"]:::service
        EnvUtil["Environment Utility"]:::service
        EventBus["Event Bus Utility"]:::service
        RouteList["Route Listener Utility"]:::service
        Timer["Timer Utility"]:::service
        Services --> SSCMA
        Services --> Flash
        Services --> FirebaseSrv
        Services --> EnvUtil
        Services --> EventBus
        Services --> RouteList
        Services --> Timer
        Flash --> SSCMA
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        SenseAPI["SenseCraft Backend API"]:::external
        FirebaseCloud["Firebase Cloud"]:::external
        Devices["IoT Devices (Serial)"]:::external
        SSCMA -->|XModem/Serial| Devices
        FirebaseSrv -->|HTTP| FirebaseCloud
        Store -->|REST API| SenseAPI
    end

    %% CI/CD to Deployment
    Actions --> DockerImage

    %% Deployment to Browser
    Nginx -->|"serve SPA"| Bootstrap

    %% Build Tools & Config
    subgraph "Build Tools & Config"
        ViteBase["vite.config.base.ts"]:::build
        ViteDev["vite.config.dev.ts"]:::build
        ViteProd["vite.config.prod.ts"]:::build
        Plugins["Vite Plugins"]:::build
        ViteBase --> Plugins
        ViteDev --> Plugins
        ViteProd --> Plugins
    end

    %% Docker Config
    subgraph "Docker Configuration"
        Dockerfile["Dockerfile"]:::build
        NginxConf["nginx-default.conf"]:::build
        Dockerfile --> NginxConf
    end

    %% CI/CD Workflows & Hooks
    click Repo "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/.github/workflows/deployment.yml"
    click LintHooks "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/.eslintrc.js"
    click LintHooks "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/.stylelintrc.js"
    click LintHooks "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/.prettierrc.js"
    click LintHooks "https://github.com/seeed-studio/sensecraft-web-toolkit/tree/main/.husky/"
    click UI "https://github.com/seeed-studio/sensecraft-web-toolkit/tree/main/src/components/"
    click UI "https://github.com/seeed-studio/sensecraft-web-toolkit/tree/main/src/pages/"
    click Router "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/router/index.ts"
    click Store "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/store/index.ts"
    click SSCMA "https://github.com/seeed-studio/sensecraft-web-toolkit/tree/main/src/sscma/"
    click Flash "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/utils/flash.ts"
    click FirebaseSrv "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/utils/firebase.ts"
    click EnvUtil "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/utils/env.ts"
    click EventBus "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/utils/event.ts"
    click RouteList "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/utils/route-listener.ts"
    click Timer "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/utils/timer.ts"
    click Hooks "https://github.com/seeed-studio/sensecraft-web-toolkit/tree/main/src/hooks/"
    click Assets "https://github.com/seeed-studio/sensecraft-web-toolkit/tree/main/src/assets/"
    click Bootstrap "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/main.ts"
    click Bootstrap "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/index.html"
    click ViteBase "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/config/vite.config.base.ts"
    click ViteDev "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/config/vite.config.dev.ts"
    click ViteProd "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/config/vite.config.prod.ts"
    click Plugins "https://github.com/seeed-studio/sensecraft-web-toolkit/tree/main/config/plugin/"
    click Dockerfile "https://github.com/seeed-studio/sensecraft-web-toolkit/tree/main/docker/Dockerfile"
    click NginxConf "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/docker/default/nginx-default.conf"
    click Config "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/config/settings.json"
    click Permission "https://github.com/seeed-studio/sensecraft-web-toolkit/blob/main/src/directive/permission/index.ts"

    %% Styles
    classDef devops fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef build fill:#dddddd,stroke:#444,stroke-width:1px;
    classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:1px;
    classDef service fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef external fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px;
```
