# doris-duo/carlife-md-lib architecture

> Architecture diagram of the GitHub repository doris-duo/carlife-md-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/doris-duo/carlife-md-lib
- Repository: https://github.com/doris-duo/carlife-md-lib

## Overview

#### Purpose and Entry Points
This repository builds a cross-platform C++ dynamic library implementing the CarLife protocol for MD devices connecting to a head unit (HU). Its public embedding surface is `LibSource/include/CCarLifeLib.h` and `LibSource/include/CCarLifeLibWrapper.h`; the library implementation is `LibSource/libwrapper/CCarLifeLib.cpp`. `LibSource/CarLifeLibTest.cpp` is the standalone consumer/test entry point.

#### Library Facade and Lifecycle
`CCarLifeLib` exposes the MD-facing API and coordinates connection, channel setup, protocol traffic, and callbacks to the embedding device. The wrapper isolates callers from internal modules and transport details.
- `LibSource/include/CCarLifeLib.h`
- `LibSource/include/CCarLifeLibWrapper.h`
- `LibSource/libwrapper/CCarLifeLib.cpp`

#### Connection and Transport Boundary
Connection management establishes and owns the socket-level link to the HU. Socket abstractions allow platform-specific networking implementations while presenting a common interface to the protocol stack.
- `LibSource/include/CConnectManager.h`
- `LibSource/utility/CConnectManager.cpp`
- `LibSource/include/ISocket.h`

Transport implementations include IPv4 and IPv6 socket paths plus a connector layer:
- `LibSource/utility/CSocketConnector.cpp`
- `LibSource/utility/socket.cpp`
- `LibSource/utility/socketv6.cpp`

#### Setup, Framing, and Dispatch
The connection-setup module handles initial channel establishment. Received transport payloads pass through the package processor, which forms the boundary between raw socket bytes and protocol/module dispatch.
- `LibSource/modules/CConnectionSetupModule.cpp`
- `LibSource/core/CTranRecvPackageProcess.cpp`
- `LibSource/include/CTranRecvPackageProcess.h`

#### Logical CarLife Channels
Protocol traffic is split into dedicated channels rather than one monolithic handler. Command and control modules carry HU/MD interaction and input/control events; video, media, TTS, and VR modules carry rendering and voice-related streams.
- `LibSource/modules/CCmdChannelModule.cpp`
- `LibSource/modules/CCtrlChannelModule.cpp`
- `LibSource/modules/CVideoChannelModule.cpp`

Additional content-channel implementations:
- `LibSource/modules/CMediaChannelModule.cpp`
- `LibSource/modules/CTTSChannelModule.cpp`
- `LibSource/modules/CVRChannelModule.cpp`

#### Protocol Contract and Serialization
Protocol messages are defined as Protocol Buffers schemas, with checked-in generated C++ bindings. These schemas define the interoperability contract with the HU for authentication, connection errors, device/vehicle state, input, media metadata, video encoding, Bluetooth, and telemetry.
- `LibSource/protobuf/proto/CarlifeAuthenRequestProto.proto`
- `LibSource/protobuf/proto/CarlifeTouchEventProto.proto`
- `LibSource/protobuf/proto/CarlifeVideoEncoderInfoProto.proto`

Generated bindings are compiled from:
- `LibSource/protobuf/cc/include/`
- `LibSource/protobuf/cc/src/`

#### Runtime and Build Targets
The runtime is native C++ with sockets and protobuf 2.5.0 (`protobuf-2.5.0.tar.gz`). Makefile variants indicate Linux and QNX support, consistent with embedded MD deployment. Build orchestration is rooted at:
- `LibSource/Makefile`
- `LibSource/Makefile.linux`
- `LibSource/Makefile.qnx`

No cloud, database, or web service infrastructure is represented; the principal external system is the connected HU over the CarLife socket protocol.

Main entry points: [`LibSource/core/CTranRecvPackageProcess.cpp`](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/core/CTranRecvPackageProcess.cpp) (Receive Package Processor), [`LibSource/utility/CConnectManager.cpp`](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/utility/CConnectManager.cpp) (Connection Manager), [`LibSource/libwrapper/CCarLifeLib.cpp`](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/libwrapper/CCarLifeLib.cpp) (Library Facade), [`LibSource/include/CCarLifeLib.h`](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/include/CCarLifeLib.h) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Embedding Surface"]
  node_api["Public API<br/>C++ headers<br/>[CCarLifeLib.h]"]
  node_library["Library Facade<br/>C++ library<br/>[CCarLifeLib.cpp]"]
end

subgraph group_transport["Connection &amp; Transport"]
  node_connection["Connection Manager<br/>connection lifecycle"]
  node_socket_api["Socket Abstraction<br/>transport interface<br/>[ISocket.h]"]
  node_socket_impl["IPv4 / IPv6 Sockets<br/>socket implementations<br/>[socket.cpp]"]
end

subgraph group_protocol["Protocol Processing"]
  node_setup["Channel Setup<br/>setup module"]
  node_framing["Receive Package Processor<br/>framing and dispatch"]
end

subgraph group_channels["Logical Channels"]
  node_command["Command Channel<br/>protocol module"]
  node_control["Control Channel<br/>protocol module"]
  node_video["Video Channel<br/>protocol module"]
  node_content["Media, TTS &amp; VR Channels<br/>protocol modules"]
end

subgraph group_contract["Protocol Contract"]
  node_schemas["Protobuf Schemas<br/>protocol contract"]
  node_bindings["Generated Protobuf C++<br/>serialization bindings"]
end

node_consumer["Standalone Consumer<br/>C++ entry point<br/>[CarLifeLibTest.cpp]"]
node_hu{{"Head Unit<br/>external CarLife peer"}}
node_build["Linux / QNX Build<br/>Make targets"]

node_consumer -->|"embeds"| node_api
node_api -->|"implemented by"| node_library
node_library -->|"manages connection"| node_connection
node_connection -->|"uses"| node_socket_api
node_socket_api -->|"implemented by"| node_socket_impl
node_socket_impl -->|"socket link"| node_hu
node_connection -->|"initializes"| node_setup
node_connection -->|"delivers received bytes"| node_framing
node_framing -->|"dispatches commands"| node_command
node_framing -->|"dispatches control"| node_control
node_framing -->|"dispatches video"| node_video
node_framing -->|"dispatches media and voice"| node_content
node_setup -->|"serializes setup messages"| node_bindings
node_command -->|"serializes protocol messages"| node_bindings
node_control -->|"serializes protocol messages"| node_bindings
node_video -->|"serializes protocol messages"| node_bindings
node_content -->|"serializes protocol messages"| node_bindings
node_schemas -->|"generates"| node_bindings
node_build -->|"builds"| node_library

click node_consumer "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/CarLifeLibTest.cpp"
click node_api "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/include/CCarLifeLib.h"
click node_library "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/libwrapper/CCarLifeLib.cpp"
click node_connection "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/utility/CConnectManager.cpp"
click node_socket_api "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/include/ISocket.h"
click node_socket_impl "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/utility/socket.cpp"
click node_setup "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CConnectionSetupModule.cpp"
click node_framing "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/core/CTranRecvPackageProcess.cpp"
click node_command "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CCmdChannelModule.cpp"
click node_control "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CCtrlChannelModule.cpp"
click node_video "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CVideoChannelModule.cpp"
click node_content "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CMediaChannelModule.cpp"
click node_schemas "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/protobuf/proto/CarlifeAuthenRequestProto.proto"
click node_build "https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/Makefile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_library toneBlue
class node_connection,node_socket_api,node_socket_impl toneAmber
class node_setup,node_framing toneMint
class node_command,node_control,node_video,node_content toneRose
class node_schemas,node_bindings toneIndigo
class node_consumer,node_hu,node_build toneNeutral
```

## Components

### Embedding Surface

- [Public API](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/include/CCarLifeLib.h): C++ headers · MD-facing embedding API and wrapper. · `LibSource/include/CCarLifeLib.h`
- [Library Facade](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/libwrapper/CCarLifeLib.cpp): C++ library · Coordinates lifecycle, protocol traffic, and device callbacks. · `LibSource/libwrapper/CCarLifeLib.cpp`

### Connection & Transport

- [Connection Manager](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/utility/CConnectManager.cpp): connection lifecycle · Owns the socket-level HU link. · `LibSource/utility/CConnectManager.cpp`
- [Socket Abstraction](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/include/ISocket.h): transport interface · Common interface for platform networking. · `LibSource/include/ISocket.h`
- [IPv4 / IPv6 Sockets](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/utility/socket.cpp): socket implementations · Platform socket and connector paths. · `LibSource/utility/socket.cpp`

### Protocol Processing

- [Channel Setup](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CConnectionSetupModule.cpp): setup module · Establishes initial logical channels. · `LibSource/modules/CConnectionSetupModule.cpp`
- [Receive Package Processor](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/core/CTranRecvPackageProcess.cpp): framing and dispatch · Converts raw transport payloads into module dispatch. · `LibSource/core/CTranRecvPackageProcess.cpp`

### Logical Channels

- [Command Channel](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CCmdChannelModule.cpp): protocol module · Carries HU/MD commands. · `LibSource/modules/CCmdChannelModule.cpp`
- [Control Channel](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CCtrlChannelModule.cpp): protocol module · Handles input and control events. · `LibSource/modules/CCtrlChannelModule.cpp`
- [Video Channel](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CVideoChannelModule.cpp): protocol module · Carries rendering/video stream traffic. · `LibSource/modules/CVideoChannelModule.cpp`
- [Media, TTS & VR Channels](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/modules/CMediaChannelModule.cpp): protocol modules · Carries media and voice-related streams. · `LibSource/modules/CMediaChannelModule.cpp`

### Protocol Contract

- [Protobuf Schemas](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/protobuf/proto/CarlifeAuthenRequestProto.proto): protocol contract · HU interoperability messages for auth, input, video, state, and telemetry. · `LibSource/protobuf/proto/CarlifeAuthenRequestProto.proto`
- **Generated Protobuf C++**: serialization bindings · Checked-in C++ bindings compiled into the library.

### Other components

- [Standalone Consumer](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/CarLifeLibTest.cpp): C++ entry point · Example consumer of the library API. · `LibSource/CarLifeLibTest.cpp`
- **Head Unit**: external CarLife peer · Connected HU over the CarLife socket protocol.
- [Linux / QNX Build](https://github.com/doris-duo/carlife-md-lib/blob/main/LibSource/Makefile): Make targets · Build orchestration for embedded native targets. · `LibSource/Makefile`

## Connections

- Standalone Consumer → Public API: embeds
- Public API → Library Facade: implemented by
- Library Facade → Connection Manager: manages connection
- Connection Manager → Socket Abstraction: uses
- Socket Abstraction → IPv4 / IPv6 Sockets: implemented by
- IPv4 / IPv6 Sockets → Head Unit: socket link
- Connection Manager → Channel Setup: initializes
- Connection Manager → Receive Package Processor: delivers received bytes
- Receive Package Processor → Command Channel: dispatches commands
- Receive Package Processor → Control Channel: dispatches control
- Receive Package Processor → Video Channel: dispatches video
- Receive Package Processor → Media, TTS & VR Channels: dispatches media and voice
- Channel Setup → Generated Protobuf C++: serializes setup messages
- Command Channel → Generated Protobuf C++: serializes protocol messages
- Control Channel → Generated Protobuf C++: serializes protocol messages
- Video Channel → Generated Protobuf C++: serializes protocol messages
- Media, TTS & VR Channels → Generated Protobuf C++: serializes protocol messages
- Protobuf Schemas → Generated Protobuf C++: generates
- Linux / QNX Build → Library Facade: builds