# commaai/opendbc architecture

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

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

## Overview

##### Main Components
- CAN Library (opendbc/can)
- This part is responsible for parsing and building CAN messages from DBC files.
- Contains components like the parser (in Python and C/C++ via pyx files) and the packer.
- DBC Repository (opendbc/dbc)
- Holds DBC files and the generator scripts used to produce CAN message definitions.
- Serves as the data dictionary for the CAN layer.
- Car Interface Library (opendbc/car)
- A high-level abstraction for interfacing with different car brands.
- Contains per-brand folders (chrysler, ford, gm, honda, hyundai, etc.).
- Core modules include carcontroller.py, carstate.py, fingerprints.py, interface.py, and brand-specific implementations.
- Safety Module (opendbc/safety)
- Written in C/C++ for real-time safety-critical operations.
- Implements different safety modes (e.g., SAFETY_SILENT, SAFETY_ALLOUTPUT).
- Contains test suites for rigorous validation (using unit tests, MISRA testing, etc.).
- Examples, Docs, & Build/CI:
- The examples directory shows how to use the API (for instance, a joystick program to control a car).
- Documentation (docs/) and pre-commit/CI configuration (.github/workflows, SConstruct/SConscript) support development, testing, and continuous integration.

- The DBC Repository feeds the CAN parser and packer in the CAN Library.
- The CAN Library is central to converting DBC definitions into low-level CAN messages.
- The Car Interface Library leverages the CAN Library to communicate commands and state information between the code and the physical car.
- The Safety Module acts as an overlay on the CAN bus: it both monitors and intervenes to ensure safe message transmission. It may also interact directly with low-level hardware via the panda.
- Example applications illustrate how higher-level control (API calls) translates into CAN communication.
- The CI/build scripts (SConstruct/SConscript, pre-commit configs, and GitHub workflows) ensure that both the Python and safety (C/C++) components compile, pass linting, and meet standard tests.

##### Architectural Patterns and Technologies
- Layered Architecture:
- Bottom: DBC files providing message definitions.
- Middle: CAN Library for low-level message parsing/packing.
- Upper: Car Interface Library that implements domain-specific logic for each supported car.
- Crossing layers: Safety Module ensuring that communications are within approved operational modes.
- Language & Build Crossovers:
- Mix of Python (for high-level APIs, tests, and examples) and C/C++ (for performance/safety-critical code, e.g., in the safety directory).
- Integration via Cython (see .pyx files) to bridge the two domains.
- Continuous Integration & Testing:
- The GitHub workflows (.github/workflows) cover automated test runs, linting, static analysis (cppcheck, misra), and building.
- Extensibility Pattern:
- The car support “port” structure (organized by brand) facilitates contributions by isolating the vehicle-specific logic within separate modules.

- Off to the side (or integrated), show the “Safety Module” (opendbc/safety) interacting with both the CAN Library and Car Interface.
b. Ancillary blocks:
- “Examples” to show sample usage.
- “Docs & CI/Build” to represent supporting infrastructure (SConscripts, GitHub workflows).
- For instance, from “Car Interface” send control commands through the “CAN Library” and observe a safety check before reaching the hardware.
- Similarly, telemetry or vehicle state flows back up.
d. Connection points:
- Mention that some parts are bridged with Cython (in CAN Library) and that CI tests cross the entire codebase.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Dictionary Layer
    subgraph "Data Dictionary Layer"
        DBC["DBC Repository"]
    end

    %% CAN Communication Layer
    subgraph "CAN Communication Layer"
        CAN_L["CAN Library"]
    end

    %% Car Control Layer
    subgraph "Car Control Layer"
        Car_Interface["Car Interface Library"]
    end

    %% Safety and Validation Layer
    subgraph "Safety and Validation Layer"
        Safety["Safety Module"]
    end

    %% Peripheral Components
    subgraph "Peripheral Components"
        Examples["Examples"]
        Docs["Docs"]
        subgraph "Build Scripts"
            SConstruct["SConstruct"]
            SConscript["SConscript"]
            GH_Workflows[".github/workflows"]
        end
    end

    %% Core Data Flow
    DBC -->|"feeds"| CAN_L
    CAN_L -->|"communicates"| Car_Interface
    CAN_L -->|"monitors"| Safety
    Safety -->|"intervenes"| CAN_L
    Car_Interface -->|"safetyCheck"| Safety
    Examples -->|"usage"| Car_Interface
    Docs -->|"documentation"| Car_Interface

    %% CI / Build Scripts Integration (dashed arrows)
    SConstruct -.->|"CI_support"| DBC
    SConscript -.->|"CI_support"| CAN_L
    GH_Workflows -.->|"CI_pipeline"| Car_Interface
    GH_Workflows -.->|"CI_pipeline"| Safety

    %% Click Events for Component Mapping
    click DBC "https://github.com/commaai/opendbc/tree/master/opendbc/dbc"
    click CAN_L "https://github.com/commaai/opendbc/tree/master/opendbc/can"
    click Car_Interface "https://github.com/commaai/opendbc/tree/master/opendbc/car"
    click Safety "https://github.com/commaai/opendbc/tree/master/opendbc/safety"
    click Examples "https://github.com/commaai/opendbc/tree/master/examples"
    click Docs "https://github.com/commaai/opendbc/tree/master/docs"
    click SConstruct "https://github.com/commaai/opendbc/tree/master/SConstruct"
    click SConscript "https://github.com/commaai/opendbc/tree/master/SConscript"
    click GH_Workflows "https://github.com/commaai/opendbc/tree/master/.github/workflows"

    %% Styles
    classDef python fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef safety fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef peripheral fill:#d4edda,stroke:#155724,stroke-width:2px;
    
    class DBC,CAN_L,Car_Interface python;
    class Safety safety;
    class Examples,Docs,SConstruct,SConscript,GH_Workflows peripheral;
```
