# chaitu-ycr/py_canoe architecture

> Architecture diagram of the GitHub repository chaitu-ycr/py_canoe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chaitu-ycr/py_canoe
- Repository: https://github.com/chaitu-ycr/py_canoe

## Overview

##### Project Type and Purpose
- This is an open-source Python library (py_canoe) that provides a high-level API for controlling the Vector CANoe tool via its COM/automation interface. Users write Python scripts that import py_canoe to drive CANoe configurations, start/stop measurements, manipulate signals/logging, compile CAPL nodes, and more.

##### High-Level File Structure (ignoring `.github` and `tests`)
- mkdocs.yml
- docs/…            ← Documentation source (MkDocs)
- pyproject.toml     ← Packaging metadata for PyPI
- scripts/*.bat      ← Windows batch scripts (build wheel, deploy docs, run tests)
- py_canoe/          ← Core library
- __init__.py
- py_canoe.py     ← Facade/API layer exposing `CANoe` class and `wait()`
- py_canoe_utils/ ← Utility modules
– logging_collection.py
– py_canoe_logger.py
- README.md, LICENSE, SECURITY.md, CODE_OF_CONDUCT.md

##### Key Components
a. Python Client Code
– Your own test scripts or application that `import py_canoe` and invokes methods (e.g., open(), start_measurement()).
b. py_canoe Library
– API Layer (py_canoe.py): exposes `CANoe` class, wraps COM calls.
– Utils (py_canoe_utils): logging collection, internal logger.
c. Vector CANoe Application
– Runs as an external process; exposes COM automation interface.
d. CAN Hardware / Offline Data
– Physical CAN bus or offline log files (.blf).
e. File System
– Configuration files (.cfg, .cdd, .dbc, .arxml, .ldf), log files, CAPL source, database files.
f. CI/CD & Packaging
– GitHub Actions workflows (lint, publish to PyPI), MkDocs site deployment, batch scripts for manual automation.

##### Interactions & Data Flows
1. Python Client → py_canoe API
- Calls `CANoe.open()`, `start_measurement()`, etc.
2. py_canoe API → COM Automation
- Internally uses `win32com.client` (or equivalent) to drive CANoe.
3. COM Automation ↔ Vector CANoe App
- Opens config, controls measurement, retrieves data.
4. Vector CANoe ↔ CAN Bus / Offline Logs
- Sends/receives frames to/from hardware or reads/writes .blf files.
5. py_canoe_utils → Logging Collection
- Manages logging blocks, collects statistics.
6. File System ↔ CANoe / py_canoe
- Reads config, writes logs, saves configurations.
7. CI/CD Pipelines → Repository
- On push: Lint, build & publish package, deploy docs.

##### Architectural Patterns & Design Principles
- Facade Pattern: `py_canoe.py` hides low-level COM complexity behind simple method calls.
- Separation of Concerns: clear split between API surface (py_canoe.py), utilities (logging, internal logger), docs, packaging, and CI/CD scripts.
- Extensibility: additional utility modules can be plugged under `py_canoe_utils`.

##### Technologies & Frameworks
- Python ≥3.9
- Windows COM Automation (win32com)
- MkDocs for documentation
- GitHub Actions for CI/CD
- PyPI for distribution
- Batch scripts for local automation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        UserScript["User Python Script"]:::client
    end

    %% Library Layer
    subgraph "py_canoe Library"
        Init["__init__.py"]:::library
        API["py_canoe.py"]:::library
        subgraph "Utils"
            LogColl["logging_collection.py"]:::utils
            Logger["py_canoe_logger.py"]:::utils
        end
    end

    %% COM Automation Bridge
    subgraph "COM Automation Bridge"
        Win32Com["win32com.client"]:::external
    end

    %% External Application
    CanoeApp["Vector CANoe App"]:::external

    %% CAN Infrastructure
    subgraph "CAN Infrastructure"
        CANBus["Physical CAN Bus"]:::external
        Offline["Offline Logs (.blf)"]:::external
    end

    %% File System
    subgraph "File System"
        Configs["Config & Database Files"]:::infra
        LogsFS["Log Files"]:::infra
        CAPL["CAPL Source & Panels"]:::infra
    end

    %% Documentation & Packaging
    subgraph "Documentation & Packaging"
        DocsSrc["docs/"]:::infra
        MkdocsCfg["mkdocs.yml"]:::infra
        PyProject["pyproject.toml"]:::infra
        Scripts["scripts/"]:::infra
        subgraph "Governance Files"
            Readme["README.md"]:::infra
            License["LICENSE"]:::infra
            Security["SECURITY.md"]:::infra
            CodeConduct["CODE_OF_CONDUCT.md"]:::infra
        end
    end

    %% CI/CD & Distribution
    subgraph "CI/CD & Distribution"
        GitHubActions["GitHub Actions"]:::infra
        PyPI["PyPI Registry"]:::infra
        DocsSite["MkDocs Site"]:::infra
    end

    %% Connections
    UserScript -->|"import & call open(), start_measurement()"| API
    API -->|"uses COM interface"| Win32Com
    Win32Com -->|"automation calls"| CanoeApp
    CanoeApp -->|"sends/receives frames"| CANBus
    CanoeApp -->|"reads/writes logs"| Offline
    API -->|"load cfg/write logs"| Configs
    API -->|"load cfg/write logs"| LogsFS
    API -->|"manage logging blocks"| LogColl
    LogColl -->|"internal logging"| Logger
    CanoeApp -->|"reads configs"| Configs
    CanoeApp -->|"writes logs"| LogsFS
    GitHubActions -->|"on push: lint, publish, deploy"| PyPI
    GitHubActions -->|"on push: deploy docs"| DocsSite
    GitHubActions -->|"run build scripts"| Scripts

    %% Click Events
    click API "https://github.com/chaitu-ycr/py_canoe/blob/dev/py_canoe/py_canoe.py"
    click Init "https://github.com/chaitu-ycr/py_canoe/blob/dev/py_canoe/__init__.py"
    click LogColl "https://github.com/chaitu-ycr/py_canoe/blob/dev/py_canoe/py_canoe_utils/logging_collection.py"
    click Logger "https://github.com/chaitu-ycr/py_canoe/blob/dev/py_canoe/py_canoe_utils/py_canoe_logger.py"
    click DocsSrc "https://github.com/chaitu-ycr/py_canoe/tree/dev/docs/"
    click MkdocsCfg "https://github.com/chaitu-ycr/py_canoe/blob/dev/mkdocs.yml"
    click PyProject "https://github.com/chaitu-ycr/py_canoe/blob/dev/pyproject.toml"
    click Scripts "https://github.com/chaitu-ycr/py_canoe/tree/dev/scripts/"
    click Readme "https://github.com/chaitu-ycr/py_canoe/blob/dev/README.md"
    click License "https://github.com/chaitu-ycr/py_canoe/tree/dev/LICENSE"
    click Security "https://github.com/chaitu-ycr/py_canoe/blob/dev/SECURITY.md"
    click CodeConduct "https://github.com/chaitu-ycr/py_canoe/blob/dev/CODE_OF_CONDUCT.md"

    %% Styles
    classDef client fill:#ddeeff,stroke:#888888
    classDef library fill:#bbccdd,stroke:#888888
    classDef utils fill:#ccddee,stroke:#888888
    classDef external fill:#ffdddd,stroke:#888888
    classDef infra fill:#ddffdd,stroke:#888888
```
