# flowdriveai/opendbc architecture

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

- Interactive diagram: https://gitdiagram.com/flowdriveai/opendbc
- Repository: https://github.com/flowdriveai/opendbc

## Overview

##### Project Type and Purpose
- This is an open-source tool/library (opendbc) for working with automotive CAN bus DBC files: parsing, preprocessing (generating brand/model-specific DBCs), packing/unpacking CAN messages, and offering a Python/C++ API.
- Key functionality:
- Read and interpret DBC definitions (parser).
- Generate consolidated DBC files from “brand” + “model” source DBCs (generator).
- Pack/unpack CAN messages according to DBC definitions (packer).
- Provide a C++ core with Python/Cython bindings for high performance.
- Offer unit tests, SCons-based build, Docker for reproducible environments.

##### High-Level Components
A. DBC Parser Library
- Core in C++: common.cc/.h, dbc.cc, parser.cc
- Cython/Pyrex bindings: parser_pyx.pyx, common.pxd
- Python wrapper: parser.py
B. CAN Packer Module
- Core in C++: packer.cc
- Cython bindings: packer_pyx.pyx
- Python façade: packer.py
C. DBC Preprocessor/Generator
- Python script: generator/generator.py
- Brand/model folders under generator/ (honda, toyota, chrysler, etc.)
- Inputs: source DBCs (.dbc) in generator subdirs
- Outputs: *_generated.dbc files in project root
D. CLI / Build Infrastructure
- SConstruct build script invoking SCons, Cython compilation
- Dockerfile for containerized build/test
- GitHub Actions CI (tests.yml)
E. Tests
- Python pytest modules under can/tests/
- Validate parsing, checksums, exceptions, packer/parser interplay

##### Relationships and Data Flow
- Input DBC files (brand/model) → Generator module → Consolidated/generated DBC files
- Parser Library reads DBC files (either source or generated) → internal in-memory model of messages, signals
- Packer consumes in-memory model + signal values → binary CAN frames, and vice versa
- CLI or downstream tools (e.g., CANdevStudio, Cabana) can call parser/packer API
- GitHub Actions & Docker orchestrate build → run SCons → compile C++/Cython → run tests

##### Architectural Patterns & Design Principles
- Modular separation: parsing, packing, generation are distinct modules
- Polyglot core: C++ for performance, Cython for bindings, pure-Python for orchestration
- Convention-based file layout: source DBCs under generator/, outputs at root with _generated suffix
- External tooling integration points: Panda, Cabana, CANdevStudio

##### Essential Details to Capture
- Build pipeline: SCons → C++ compilation → Cython wrapping → pip install
- DBC preprocessing flow: how brand-level and model-level DBCs combine
- API boundary between native code and Python layer
- Testing harness and CI integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source and Generation
    SRC["Source DBC Files"]:::external
    subgraph "Generator Module" 
        direction TB
        GEN_SCRIPT["generator.py\n(Orchestration)"]:::orchestration
        GEN_BRANDS["Brand/Model DBC Folders"]:::orchestration
        GEN_SCRIPT --> GEN_BRANDS
        GEN_OUT["Generated DBC Outputs\n(*_can_generated.dbc)"]:::external
        GEN_BRANDS --> GEN_OUT
    end
    SRC --> GEN_SCRIPT

    %% Core Library
    subgraph "Core Library" 
        direction TB
        subgraph "Parser Module" 
            direction TB
            P_CPP["Parser C++ Core"]:::cpp
            P_BIND["Parser Python/Cython"]:::py
        end
        subgraph "Packer Module"
            direction TB
            K_CPP["Packer C++ Core"]:::cpp
            K_BIND["Packer Python/Cython"]:::py
        end
    end
    GEN_OUT --> P_CPP
    P_CPP --> P_BIND
    P_BIND -->|"In-memory Model"| K_BIND
    K_BIND --> K_CPP
    K_CPP --> CANFRAMES["CAN Frames"]:::external

    %% CLI/Build Infrastructure
    subgraph "Build & CI/CD"
        direction TB
        SCONS["SConstruct"]:::infra
        DOCKER["Dockerfile"]:::infra
        CI[".github/workflows/tests.yml"]:::infra
        SCONS -->|"build pipeline"| DOCKER
        DOCKER --> CI
    end
    SCONS --> P_CPP
    SCONS --> K_CPP

    %% Tests
    subgraph "Tests (pytest)"
        direction TB
        T1["test_checksums.py"]:::test
        T2["test_dbc_exceptions.py"]:::test
        T3["test_dbc_parser.py"]:::test
        T4["test_define.py"]:::test
        T5["test_packer_parser.py"]:::test
        T1 & T2 & T3 & T4 & T5 --> P_BIND
        T1 & T2 & T3 & T4 & T5 --> K_BIND
    end

    %% External Integrations
    subgraph "External Tools"
        direction TB
        CABANA["Cabana"]:::external
        CANDEV["CANdevStudio"]:::external
        PANDA["Panda"]:::external
    end
    CABANA & CANDEV & PANDA -->|"API Calls"| P_BIND

    %% Click Events - Parser Core Files
    click P_CPP_can_common_cc "https://github.com/flowdriveai/opendbc/blob/master/can/common.cc"
    click P_CPP_can_common_h "https://github.com/flowdriveai/opendbc/blob/master/can/common.h"
    click P_CPP_can_common_dbc_h "https://github.com/flowdriveai/opendbc/blob/master/can/common_dbc.h"
    click P_CPP_can_dbc_cc "https://github.com/flowdriveai/opendbc/blob/master/can/dbc.cc"
    click P_CPP_can_parser_cc "https://github.com/flowdriveai/opendbc/blob/master/can/parser.cc"

    %% Click Events - Parser Bindings
    click P_BIND_common_pxd "https://github.com/flowdriveai/opendbc/blob/master/can/common.pxd"
    click P_BIND_parser_pyx "https://github.com/flowdriveai/opendbc/blob/master/can/parser_pyx.pyx"
    click P_BIND_parser_py "https://github.com/flowdriveai/opendbc/blob/master/can/parser.py"

    %% Click Events - Packer Core
    click K_CPP_packer_cc "https://github.com/flowdriveai/opendbc/blob/master/can/packer.cc"

    %% Click Events - Packer Bindings
    click K_BIND_packer_pyx "https://github.com/flowdriveai/opendbc/blob/master/can/packer_pyx.pyx"
    click K_BIND_packer_py "https://github.com/flowdriveai/opendbc/blob/master/can/packer.py"

    %% Click Events - Generator
    click GEN_SCRIPT "https://github.com/flowdriveai/opendbc/blob/master/generator/generator.py"
    click GEN_BRANDS "https://github.com/flowdriveai/opendbc/tree/master/generator/"
    click GEN_OUT "https://github.com/flowdriveai/opendbc/blob/master/*/_can_generated.dbc"

    %% Click Events - Build & CI/CD
    click SCONS "https://github.com/flowdriveai/opendbc/tree/master/SConstruct"
    click DOCKER "https://github.com/flowdriveai/opendbc/tree/master/Dockerfile"
    click CI "https://github.com/flowdriveai/opendbc/blob/master/.github/workflows/tests.yml"
    click SCONS_site "https://github.com/flowdriveai/opendbc/blob/master/site_scons/site_tools/cython.py"

    %% Click Events - Tests
    click T1 "https://github.com/flowdriveai/opendbc/blob/master/can/tests/test_checksums.py"
    click T2 "https://github.com/flowdriveai/opendbc/blob/master/can/tests/test_dbc_exceptions.py"
    click T3 "https://github.com/flowdriveai/opendbc/blob/master/can/tests/test_dbc_parser.py"
    click T4 "https://github.com/flowdriveai/opendbc/blob/master/can/tests/test_define.py"
    click T5 "https://github.com/flowdriveai/opendbc/blob/master/can/tests/test_packer_parser.py"

    %% Styles
    classDef cpp fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef py fill:#90EE90,stroke:#000,stroke-width:1px
    classDef orchestration fill:#FFA500,stroke:#000,stroke-width:1px
    classDef infra fill:#FFE4B5,stroke:#000,stroke-width:1px
    classDef test fill:#FFDAB9,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
