# lschulz/scion-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/lschulz/scion-cpp
- Repository: https://github.com/lschulz/scion-cpp

## Overview

SCION-CPP is a C++ SDK for SCION applications, with C bindings and two compatibility products: a libc interposer and the Scitra IP translator. The principal SDK workflow is an application using SCION addressing and name resolution, obtaining paths, then communicating through SCION sockets; path handling, packet formats, SCMP, and ID-INT support that workflow. The README establishes the major capabilities and product boundaries, while several implementation links below are dashed because the relevant source was not sampled.

Main entry points: [`src/scion_c/scion.cpp`](https://github.com/lschulz/scion-cpp/blob/main/src/scion_c/scion.cpp) (C Bindings), [`interposer/src/interposer.cpp`](https://github.com/lschulz/scion-cpp/blob/main/interposer/src/interposer.cpp) (Libc Interposer), [`scitra/src/scitra-tun/scitra_tun.cpp`](https://github.com/lschulz/scion-cpp/blob/main/scitra/src/scitra-tun/scitra_tun.cpp) (Scitra TUN), [`src/resolver.cpp`](https://github.com/lschulz/scion-cpp/blob/main/src/resolver.cpp) (Name Resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["SCION SDK"]
  node_resolver["Name Resolution<br/>[resolver.cpp]"]
  node_daemon["Daemon Client<br/>[client.cpp]"]
  node_sockets["SCION Sockets<br/>[udp_socket.hpp]"]
  node_scmp["SCMP Handling<br/>[handler.hpp]"]
  node_pmtu["Path MTU<br/>[path_mtu.hpp]"]
  node_idint["ID-INT Telemetry<br/>[idint.cpp]"]
  node_drkey["DRKey Support<br/>[drkey.hpp]"]
  node_capi["C Bindings<br/>[scion.cpp]"]
end

subgraph group_compat["Application Compatibility"]
  node_interposer["Libc Interposer<br/>[interposer.cpp]"]
  node_selector["Path Selection"]
  node_interposer_api["Interposer API<br/>[path_selector.h]"]
end

subgraph group_translator["IP Translation"]
  node_scitra["Scitra Translator<br/>[translator.cpp]"]
  node_tun["Scitra TUN<br/>[scitra_tun.cpp]"]
  node_scion2ip["scion2ip Tool<br/>[scion2ip.cpp]"]
  node_systemd["Service Notifications"]
end

subgraph group_internals["Shared Internals"]
  node_addresses["SCION Addresses<br/>[address.hpp]"]
  node_paths["Path Handling<br/>[raw.hpp]"]
  node_packet["Packet Formats<br/>[scion.hpp]"]
end

node_app(("SCION Application"))
node_os(("Operating System"))

node_app -.->|"resolves names"| node_resolver
node_app -->|"uses sockets"| node_sockets
node_app -->|"uses bindings"| node_capi
node_resolver -.->|"returns addresses"| node_addresses
node_daemon -->|"builds paths"| node_paths
node_sockets -->|"dispatches SCMP"| node_scmp
node_paths -.->|"encodes path"| node_packet
node_scmp -.->|"chains handlers"| node_pmtu
node_app -->|"uses telemetry"| node_idint
node_app -.->|"requests keys"| node_drkey
node_app -->|"uses transparently"| node_interposer
node_interposer -->|"filters paths"| node_selector
node_interposer -.->|"invokes selector"| node_interposer_api
node_app -->|"uses legacy IP"| node_tun
node_tun -.->|"translates traffic"| node_scitra
node_app -.->|"runs conversion"| node_scion2ip
node_tun -.->|"reports status"| node_systemd
node_systemd -->|"notifies service"| node_os
node_capi -->|"wraps sockets"| node_sockets
node_capi -->|"initializes resolver"| node_resolver

click node_addresses "https://github.com/lschulz/scion-cpp/blob/main/include/scion/addr/address.hpp"
click node_resolver "https://github.com/lschulz/scion-cpp/blob/main/src/resolver.cpp"
click node_daemon "https://github.com/lschulz/scion-cpp/blob/main/src/daemon/client.cpp"
click node_paths "https://github.com/lschulz/scion-cpp/blob/main/include/scion/path/raw.hpp"
click node_sockets "https://github.com/lschulz/scion-cpp/blob/main/include/scion/asio/udp_socket.hpp"
click node_packet "https://github.com/lschulz/scion-cpp/blob/main/include/scion/hdr/scion.hpp"
click node_scmp "https://github.com/lschulz/scion-cpp/blob/main/include/scion/scmp/handler.hpp"
click node_pmtu "https://github.com/lschulz/scion-cpp/blob/main/include/scion/scmp/path_mtu.hpp"
click node_idint "https://github.com/lschulz/scion-cpp/blob/main/src/extensions/idint.cpp"
click node_drkey "https://github.com/lschulz/scion-cpp/blob/main/include/scion/drkey/drkey.hpp"
click node_capi "https://github.com/lschulz/scion-cpp/blob/main/src/scion_c/scion.cpp"
click node_interposer "https://github.com/lschulz/scion-cpp/blob/main/interposer/src/interposer.cpp"
click node_selector "https://github.com/lschulz/scion-cpp/blob/main/interposer/src/builtin_selector.cpp"
click node_interposer_api "https://github.com/lschulz/scion-cpp/blob/main/interposer/include/scion/path_selector.h"
click node_scitra "https://github.com/lschulz/scion-cpp/blob/main/scitra/src/translator.cpp"
click node_tun "https://github.com/lschulz/scion-cpp/blob/main/scitra/src/scitra-tun/scitra_tun.cpp"
click node_scion2ip "https://github.com/lschulz/scion-cpp/blob/main/scitra/tools/scion2ip/src/scion2ip.cpp"
click node_systemd "https://github.com/lschulz/scion-cpp/blob/main/scitra/src/scitra-tun/service_systemd.cpp"

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_resolver,node_daemon,node_sockets,node_scmp,node_pmtu,node_idint,node_drkey,node_capi toneBlue
class node_interposer,node_selector,node_interposer_api toneAmber
class node_scitra,node_tun,node_scion2ip,node_systemd toneMint
class node_addresses,node_paths,node_packet toneRose
class node_app,node_os toneIndigo
```

## Components

### SCION SDK

- [Name Resolution](https://github.com/lschulz/scion-cpp/blob/main/src/resolver.cpp): `src/resolver.cpp`
- [Daemon Client](https://github.com/lschulz/scion-cpp/blob/main/src/daemon/client.cpp): `src/daemon/client.cpp`
- [SCION Sockets](https://github.com/lschulz/scion-cpp/blob/main/include/scion/asio/udp_socket.hpp): `include/scion/asio/udp_socket.hpp`
- [SCMP Handling](https://github.com/lschulz/scion-cpp/blob/main/include/scion/scmp/handler.hpp): `include/scion/scmp/handler.hpp`
- [Path MTU](https://github.com/lschulz/scion-cpp/blob/main/include/scion/scmp/path_mtu.hpp): `include/scion/scmp/path_mtu.hpp`
- [ID-INT Telemetry](https://github.com/lschulz/scion-cpp/blob/main/src/extensions/idint.cpp): `src/extensions/idint.cpp`
- [DRKey Support](https://github.com/lschulz/scion-cpp/blob/main/include/scion/drkey/drkey.hpp): `include/scion/drkey/drkey.hpp`
- [C Bindings](https://github.com/lschulz/scion-cpp/blob/main/src/scion_c/scion.cpp): `src/scion_c/scion.cpp`

### Application Compatibility

- [Libc Interposer](https://github.com/lschulz/scion-cpp/blob/main/interposer/src/interposer.cpp): `interposer/src/interposer.cpp`
- [Path Selection](https://github.com/lschulz/scion-cpp/blob/main/interposer/src/builtin_selector.cpp): `interposer/src/builtin_selector.cpp`
- [Interposer API](https://github.com/lschulz/scion-cpp/blob/main/interposer/include/scion/path_selector.h): `interposer/include/scion/path_selector.h`

### IP Translation

- [Scitra Translator](https://github.com/lschulz/scion-cpp/blob/main/scitra/src/translator.cpp): `scitra/src/translator.cpp`
- [Scitra TUN](https://github.com/lschulz/scion-cpp/blob/main/scitra/src/scitra-tun/scitra_tun.cpp): `scitra/src/scitra-tun/scitra_tun.cpp`
- [scion2ip Tool](https://github.com/lschulz/scion-cpp/blob/main/scitra/tools/scion2ip/src/scion2ip.cpp): `scitra/tools/scion2ip/src/scion2ip.cpp`
- [Service Notifications](https://github.com/lschulz/scion-cpp/blob/main/scitra/src/scitra-tun/service_systemd.cpp): `scitra/src/scitra-tun/service_systemd.cpp`

### Shared Internals

- [SCION Addresses](https://github.com/lschulz/scion-cpp/blob/main/include/scion/addr/address.hpp): `include/scion/addr/address.hpp`
- [Path Handling](https://github.com/lschulz/scion-cpp/blob/main/include/scion/path/raw.hpp): `include/scion/path/raw.hpp`
- [Packet Formats](https://github.com/lschulz/scion-cpp/blob/main/include/scion/hdr/scion.hpp): `include/scion/hdr/scion.hpp`

### Other components

- **SCION Application**
- **Operating System**

## Connections

- SCION Application → Name Resolution: resolves names
- SCION Application → SCION Sockets: uses sockets
- SCION Application → C Bindings: uses bindings
- Name Resolution → SCION Addresses: returns addresses
- Daemon Client → Path Handling: builds paths (evidence: `src/daemon/client.cpp`)
- SCION Sockets → SCMP Handling: dispatches SCMP (evidence: `include/scion/asio/udp_socket.hpp`)
- Path Handling → Packet Formats: encodes path (evidence: `include/scion/path/raw.hpp`)
- SCMP Handling → Path MTU: chains handlers
- SCION Application → ID-INT Telemetry: uses telemetry
- SCION Application → DRKey Support: requests keys
- SCION Application → Libc Interposer: uses transparently
- Libc Interposer → Path Selection: filters paths (evidence: `interposer/src/interposer.cpp`)
- Libc Interposer → Interposer API: invokes selector
- SCION Application → Scitra TUN: uses legacy IP
- Scitra TUN → Scitra Translator: translates traffic
- SCION Application → scion2ip Tool: runs conversion
- Scitra TUN → Service Notifications: reports status
- Service Notifications → Operating System: notifies service (evidence: `scitra/src/scitra-tun/service_systemd.cpp`)
- C Bindings → SCION Sockets: wraps sockets (evidence: `src/scion_c/scion.cpp`)
- C Bindings → Name Resolution: initializes resolver (evidence: `src/scion_c/scion.cpp`)
