# huaqiu-electronics/ecad-viewer architecture

> Architecture diagram of the GitHub repository huaqiu-electronics/ecad-viewer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huaqiu-electronics/ecad-viewer
- Repository: https://github.com/huaqiu-electronics/ecad-viewer

## Overview

##### Project Type and Purpose
- This is a full-stack web-based application designed to display electronic design files (PCB, schematic, and 3D models) interactively in the browser.
- The README makes clear that ECAD-Viewer builds upon the kicanvas framework and incorporates additional features (such as integration with kicad-cli for file conversion, 3D visualization with Three.js, etc.).
- It supports both standalone and embedded usage, includes Docker deployments (full and lite), and provides build scripts and utilities for font/sprite generation.

##### File Structure
- The root includes configuration files (eslint, prettier, tsconfig, .gitignore) and Docker configurations, which indicate that there are distinct environments for development and deployment.
- The “src” directory is the heart of the project. It’s further broken into multiple subdirectories:
a. “3d-viewer”: Manages the 3D models and the Three.js integration.
b. “base”: Provides utilities, helper functions, math operations, DOM utilities, and common web-components, which are used across the project.
c. “ecad-viewer”: Contains the core viewer logic and file conversion for handling electronic design files.
d. “graphics”: Holds rendering logic both for canvas2d and WebGL (including shader files).
e. “kc-ui”: Implements the custom UI components (buttons, menus, panels, charts, etc.) using web components.
f. “kicad”: Implements parsing and processing of KiCad files, including visitors and tokenizers for boards, schematics, BOM extraction, etc.
g. “kicanvas”: Contains the integration layers for the interactive canvas elements to display different types of designs (board, schematic, and common application features for viewer operations) and includes service modules (such as GitHub integration and virtual file system (VFS) support).
h. “viewers”: Provides distinct viewers for documents, board, drawing sheet, and schematic with specific painter and layer management classes.
i. “utils”: Contains various helper scripts such as design utilities and functions for working with ZIP files.
- There is also a “third_party” folder which bundles external libraries (such as “earcut” for polygon triangulation and “newstroke” for fonts).

##### Key System Components & Their Roles
- Web Frontend:
- Built using plain JavaScript/TypeScript modules and web components.
- UI components are defined under “kc-ui” and “kicanvas”, used to render the interactive viewer.
- Multiple viewer modules exist for handling PCB (board), schematic, drawing sheet, and 3D presentations.
- Graphics Engine:
- “graphics” handles various rendering pipelines: a 2D canvas-based renderer and a WebGL-based renderer for complex visualizations.
- KiCad File and Design Processing:
- Under “kicad”, files are parsed and processed, with multiple utilities (such as visitors, tokenizers, parsers, and font/text renderers) that prepare design data for viewing.
- Conversion/Integration Services:
- Integration with kicad-cli (running as Docker containers) is critical. The frontend calls REST API endpoints (e.g. /convert_pcb_to_glb) to convert design files into formats suitable for viewing (3D models in GLB format).
- This processing may be implemented externally (via the provided Docker images for kicad-cli) and potentially, a lightweight Python wrapper using kicad-cli-python.
- Build/Deployment & DevOps:
- Dockerfiles for the “full” and “lite” versions enable containerized deployment.
- Scripts in the “scripts” directory bundle assets, build fonts/sprites, and handle testing/serving, which are critical during CI/CD (also evidenced by the GitHub workflows).

##### Final Points
- Every component is labeled clearly.
- Notes on which parts are executed in the browser (frontend) and which (like the kicad-cli service) are on separated backend containers.
- Don’t overcomplicate: focus on key modules and how they interact. The above divisions into front-end components, processing/parsing layers, rendering engines, and conversion APIs should be sufficient.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% High-level Nodes
    subgraph "Client Side (Browser)"
        UIC["\"UI Components\""]:::frontend
        IC["\"Interactive Canvas\""]:::frontend
        SV["\"Specific Viewers\""]:::frontend
        GE["\"Graphics Engine\""]:::frontend
        V3D["\"3D Viewer\""]:::frontend
    end

    subgraph "Business Logic"
        KP["\"KiCad Processing\""]:::processing
        subgraph "Utility Libraries"
            BU["\"Base Utilities\""]:::utility
            DU["\"Design Utilities\""]:::utility
        end
    end

    subgraph "External"
        TP["\"Third-Party Libraries\""]:::external
    end

    subgraph "Backend Services"
        subgraph "Conversion Service"
            DFC["\"Docker Full Conversion\""]:::backend
            DLC["\"Docker Lite Conversion\""]:::backend
        end
        subgraph "Deployment/DevOps"
            DC["\"Docker Config\""]:::deployment
            BS["\"Build Scripts\""]:::deployment
            GH["\"CI/CD Workflows\""]:::deployment
        end
    end

    %% User Node
    U["\"User/Browser\""]:::frontend

    %% Connections - Client Side Flow
    U -->|"interacts"| UIC
    UIC -->|"triggers"| IC
    IC -->|"passes actions to"| SV
    SV -->|"requests parsing"| KP
    KP -->|"utilizes"| BU
    KP -->|"utilizes"| DU
    SV -->|"updates"| V3D
    UIC -->|"supports rendering with"| GE
    GE -->|"feeds into"| SV

    %% External dependencies
    TP ---|"provides libs to"| KP
    TP ---|"supports"| GE

    %% Conversion Service Flow
    U -->|"calls conversion API"| DFC
    U -->|"calls conversion API"| DLC
    DFC -->|"returns converted data"| V3D
    DLC -->|"returns converted data"| V3D

    %% Deployment influences Conversion Service
    DC -->|"deploys"| DFC
    DC -->|"deploys"| DLC
    BS -->|"builds"| DFC
    BS -->|"builds"| DLC
    GH -->|"automates"| DFC
    GH -->|"automates"| DLC

    %% Classes Definition
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef processing fill:#fffacd,stroke:#000,stroke-width:1px;
    classDef backend fill:#f08080,stroke:#000,stroke-width:1px;
    classDef utility fill:#ffa500,stroke:#000,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef deployment fill:#90ee90,stroke:#000,stroke-width:1px;

    %% Click Events
    click UIC "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/src/kc-ui"
    click IC "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/src/kicanvas"
    click SV "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/src/viewers"
    click GE "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/src/graphics"
    click KP "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/src/kicad"
    click V3D "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/src/3d-viewer"
    click DFC "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/docker/full"
    click DLC "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/docker/lite"
    click BU "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/src/base"
    click DU "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/src/utils"
    click TP "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/third_party"
    click DC "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/docker"
    click BS "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/scripts"
    click GH "https://github.com/huaqiu-electronics/ecad-viewer/tree/master/.github/workflows"
```
