# gkshub/doip_python architecture

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

- Interactive diagram: https://gitdiagram.com/gkshub/doip_python
- Repository: https://github.com/gkshub/doip_python

## Overview

This repository is a **Python DoIP (Diagnostics over IP) client** implementation with:
- A **core client/engine layer** (`src/doip_client/doip_engine.py`) orchestrating DoIP communication
- A **protocol + message modeling layer** (`src/doip_client/lib/doip_protocol.py`, `doip_messages.py`)
- **Network connectivity + discovery** utilities (`connection.py`, `discovery.py`)
- **Configuration loading** from JSON (`json_config.py`, `config/config_client.json`, `config/config_server.json`)
- A **CLI entrypoint** (`src/doip_client/run_cli.py`, `src/doip_client/main.py`)
- **Tests** (`tests/`)
- A currently minimal/placeholder `web/` package (exists but no internal modules in the tree)

So the “system” is not a multi-service backend; it’s primarily a **client-side tool/library** that communicates with an **external DoIP server/ECU** over the network (UDP discovery + TCP diagnostic session in typical DoIP setups).

From the tree:

##### Entrypoints / UI layer
- `src/doip_client/run_cli.py` and `src/doip_client/main.py`

##### Orchestration / Application layer
- `src/doip_client/doip_engine.py`

##### Configuration layer
- `src/doip_client/json_config.py`
- `config/config_client.json`
- `config/config_server.json`

##### Core library (Protocol + Networking) — “domain” for this project
- `src/doip_client/lib/connection.py`
- `src/doip_client/lib/discovery.py`
- `src/doip_client/lib/doip_protocol.py`
- `src/doip_client/lib/doip_messages.py`

##### Quality / Verification
- `tests/`

##### Web
- `web/__init__.py` only

##### (Optional) Network boundary (LAN / Automotive Ethernet)

- **UDP Discovery Channel** (Discovery ↔ ECU)
- **TCP Diagnostic Channel** (Connection ↔ ECU)

##### Architectural patterns present (what to highlight explicitly)
Even though it’s a single-process project, it has clear layering:

- **Interface layer**: CLI
- **Application orchestration**: `DoIPEngine`
- **Infrastructure**: sockets/connection + discovery
- **Protocol modeling**: message definitions + codec/protocol handler
- **External system boundary**: ECU/DoIP server

Call out that this is essentially a **library + tool** design:
- The `lib/` folder is the reusable core
- The `main.py`/`run_cli.py` are “adapters” for interactive usage

From the repo, it’s pure Python; the meaningful tech is:
- **Python runtime**
- **Sockets / networking** (even if not explicitly listed, `connection.py` implies it)
- **DoIP protocol** (domain protocol)
- **JSON config** (config files + loader)

##### Engine prints result / exits

- `encode(message)` in protocol handler
- `send(bytes)` in connection
- `recv(bytes)` and `decode(bytes)`

##### “Don’t overthink it” but be very detailed (how to maximize component separation)
For this repo, “separating into as many components as possible” means:
- Split **Discovery** and **Connection** explicitly (don’t combine them into “Networking”)
- Split **Protocol codec** from **Message definitions**
- Split **Engine orchestration** from **CLI**
- Split **Config files** from **Config loader**

##### One note on README vs tree mismatch (how to handle
The README’s example structure mentions `app.py` and `run_cli.py` at repo root, but the actual tree shows:
- `src/doip_client/main.py`
- `src/doip_client/run_cli.py`
- no `app.py` at root

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% External Actors / Systems
    %% =========================================================
    Operator["Operator / User"]:::actor
    Network["Network (LAN / Automotive Ethernet)"]:::network
    ECU["External DoIP Server / ECU"]:::external

    %% =========================================================
    %% Repo Boundary
    %% =========================================================
    subgraph "doip_python (this repo)"
        direction TB

        subgraph "Interface / Entrypoints"
            direction TB
            CLI_Run["CLI Entrypoint (run_cli.py)"]:::ui
            CLI_Main["CLI Entrypoint (main.py)"]:::ui
        end

        subgraph "Application / Orchestration"
            direction TB
            Engine["DoIP Engine / Orchestrator (doip_engine.py)"]:::engine
        end

        subgraph "Configuration"
            direction TB
            ConfigLoader["JSON Config Loader (json_config.py)"]:::config
            ConfigClient[("config_client.json")]:::configFile
            ConfigServer[("config_server.json")]:::configFile
        end

        subgraph "Core Library (src/doip_client/lib)"
            direction TB

            subgraph "Infrastructure: Connectivity"
                direction TB
                Discovery["Discovery Service (UDP) (discovery.py)"]:::infra
                Connection["Connection Manager (TCP) (connection.py)"]:::infra
            end

            subgraph "Protocol Modeling"
                direction TB
                Protocol["DoIP Protocol Handler / Codec (doip_protocol.py)"]:::protocol
                Messages["DoIP Message Model / Definitions (doip_messages.py)"]:::model
            end
        end

        subgraph "Quality / Verification (non-runtime)"
            direction TB
            Tests["Tests (tests/)"]:::test
        end

        subgraph "Web (placeholder)"
            direction TB
            WebPkg["Reserved Web Package (web/__init__.py)"]:::placeholder
        end
    end

    %% =========================================================
    %% Runtime Flow (solid)
    %% =========================================================
    Operator -->|"invokes CLI command"| CLI_Run
    Operator -->|"invokes CLI command"| CLI_Main

    CLI_Run -->|"starts / delegates"| Engine
    CLI_Main -->|"starts / delegates"| Engine

    CLI_Run -->|"loads JSON config"| ConfigLoader
    CLI_Main -->|"loads JSON config"| ConfigLoader

    ConfigClient -->|"config values"| ConfigLoader
    ConfigServer -->|"config values"| ConfigLoader
    ConfigLoader -->|"parsed settings"| Engine

    Engine -->|"UDP: discovery request/response"| Discovery
    Discovery -->|"UDP broadcast/multicast"| Network
    Network -->|"UDP discovery"| ECU
    ECU -->|"UDP discovery response"| Network
    Network -->|"UDP discovery response"| Discovery
    Discovery -->|"discovered endpoint info"| Engine

    Engine -->|"connect/disconnect + IO"| Connection
    Connection -->|"TCP session (DoIP diagnostic channel)"| Network
    Network -->|"TCP DoIP frames"| ECU
    ECU -->|"TCP DoIP frames"| Network
    Network -->|"TCP bytes"| Connection

    Engine -->|"encode/decode DoIP frames"| Protocol
    Protocol -->|"construct/parse message types"| Messages

    Protocol -->|"encoded bytes"| Engine
    Engine -->|"send(bytes)"| Connection
    Connection -->|"recv(bytes)"| Engine
    Engine -->|"decode(bytes)"| Protocol

    %% =========================================================
    %% Optional: static dependencies (dashed "imports/uses")
    %% =========================================================
    CLI_Run -.->|"imports/uses"| Engine
    CLI_Main -.->|"imports/uses"| Engine
    Engine -.->|"imports/uses"| ConfigLoader
    Engine -.->|"imports/uses"| Discovery
    Engine -.->|"imports/uses"| Connection
    Engine -.->|"imports/uses"| Protocol
    Protocol -.->|"imports/uses"| Messages

    %% =========================================================
    %% Click Events (component_mapping paths)
    %% =========================================================
    click CLI_Run "https://github.com/gkshub/doip_python/blob/main/src/doip_client/run_cli.py"
    click CLI_Main "https://github.com/gkshub/doip_python/blob/main/src/doip_client/main.py"
    click Engine "https://github.com/gkshub/doip_python/blob/main/src/doip_client/doip_engine.py"
    click ConfigLoader "https://github.com/gkshub/doip_python/blob/main/src/doip_client/json_config.py"
    click ConfigClient "https://github.com/gkshub/doip_python/blob/main/config/config_client.json"
    click ConfigServer "https://github.com/gkshub/doip_python/blob/main/config/config_server.json"
    click Connection "https://github.com/gkshub/doip_python/blob/main/src/doip_client/lib/connection.py"
    click Discovery "https://github.com/gkshub/doip_python/blob/main/src/doip_client/lib/discovery.py"
    click Protocol "https://github.com/gkshub/doip_python/blob/main/src/doip_client/lib/doip_protocol.py"
    click Messages "https://github.com/gkshub/doip_python/blob/main/src/doip_client/lib/doip_messages.py"
    click Tests "https://github.com/gkshub/doip_python/tree/main/tests/"
    click WebPkg "https://github.com/gkshub/doip_python/blob/main/web/__init__.py"

    %% =========================================================
    %% Styles
    %% =========================================================
    classDef actor fill:#ffffff,stroke:#111827,stroke-width:1px,color:#111827
    classDef ui fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#0f172a
    classDef engine fill:#dcfce7,stroke:#16a34a,stroke-width:1px,color:#052e16
    classDef config fill:#ffedd5,stroke:#ea580c,stroke-width:1px,color:#7c2d12
    classDef configFile fill:#fff7ed,stroke:#f97316,stroke-width:1px,color:#7c2d12
    classDef infra fill:#e0f2fe,stroke:#0284c7,stroke-width:1px,color:#0c4a6e
    classDef protocol fill:#f3e8ff,stroke:#7c3aed,stroke-width:1px,color:#2e1065
    classDef model fill:#fae8ff,stroke:#a21caf,stroke-width:1px,color:#500724
    classDef network fill:#f1f5f9,stroke:#334155,stroke-width:1px,color:#0f172a
    classDef external fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#111827
    classDef test fill:#fef9c3,stroke:#ca8a04,stroke-width:1px,color:#713f12
    classDef placeholder fill:#f3f4f6,stroke:#6b7280,stroke-dasharray: 4 3,color:#111827
```
