# pollere/dct architecture

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

- Interactive diagram: https://gitdiagram.com/pollere/dct
- Repository: https://github.com/pollere/dct

## Overview

##### Project Overview and Purpose
- The project is a specialized communications toolkit for secure, defined-trust networks. Its purpose is to provide a reference implementation of the DeftT protocol – a collection-based, broadcast-friendly transport that enforces strict trust rules on the network.
- It includes header-only C++ libraries (all in the “include” directory) for implementing secure transport, schema verification, signature management, certificate distribution, and related functions. It also includes tool chains for building schema and certificates (in “tools” – notably under the “compiler” and “dctwatch” subdirectories) as well as example applications (in “examples”).

##### Analyzing the File Structure
- Top-level directories of note:
- “include”: Contains all header-only libraries. These are organized into submodules such as:
▪ dct (core runtime components)
▪ subdirectories like syncps (for pub-sub messaging), face (interface bridging transport), schema management, sigmgrs (for signing and verification), distributors (certs/keys management), and shims (APIs for different network protocols).
▪ Additionally, there are included libraries like “date”, “fmt”, “pcg_random”, and others.
- “tools”: This contains utility programs for creating and inspecting the trust schemas and certificates:
▪ “compiler” subdirectory holds the source for the VerSec language compiler, which converts trust rules into a binary schema.
▪ “dctwatch” is a tool for passively monitoring DCT network traffic.
- “examples”: Provides several example implementations (like “hmIot”, “office”, “pubpriv”, “relay”, and “robust”) that demonstrate how to use the toolkit. Each example comes with Makefiles, scripts, and source code (in C++) that utilize the DCT libraries.
- The README further explains how these components fit together (for example, showing that the runtime libraries are designed to be used via a header-only approach and that the examples illustrate real-world communication domains using both broadcast and unicast setups).

a. Main Components:
- Runtime Libraries (the “include/dct” modules):
- Core Transport Modules: syncps, face, schema, sigmgrs, distributors, shims.
- Tools:
- Schema Compiler (found in tools/compiler) – translates high-level trust rules into binary schemas.
- Dctwatch (found in tools/dctwatch) – monitors and prints network traffic for debugging.
- Other utilities in “tools” for managing certificates, bundles, etc.
- Examples/Applications:
- Multiple example applications (hmIot, office, pubpriv, relay, robust) demonstrating how to set up a defined-trust domain and run secure communications.
- External Dependencies:
- Libraries such as libsodium (for cryptography), boost, and fmt (for formatted output).

b. Relationships and Interactions:
- The design should show how applications (in “examples”) incorporate the header-only DCT libraries for secure communication.
- Within the DCT libraries, indicate how data flows from the transport interface (face) into the synchronization protocol (syncps) and then interacts with schema validation (schema) and signature management (sigmgrs).
- Tools such as the schema compiler generate the binary schemas that the runtime libraries use at startup/configuration.
- The Dctwatch utility listens on the network interface to verify that the transport protocol (broadcast UDP/IPv6 multicast) and packet formats (derived from NDN experiments) are working as expected.

c. Architectural Patterns & Design Principles:
- Modular Design: The project is broken into distinct modules – each providing a part of the secure communications stack.
- Header-only Libraries: Emphasizes compile-time integration and minimal external linking.
- Defined Trust Domains: Clearly illustrated by showing key components for certificate management, chain-of-trust creation, and enforcement of communication rules.
- Layering: It is useful to visually separate layers like the trust schema and transport layer (application-level, runtime modules) versus the toolchain (development/utilities).

d. Relevant Technologies:
- C++20 (with reliance on new formatted output models)
- libsodium (cryptography library)
- Boost and fmt (for utilities and formatted output)
- UDP/IPv6 multicast (for transport semantics)

##### Final Touches
- Adding legends or notes to explain complex flows (e.g., how certificates are chained to a trust anchor, or how a binary schema is generated and then read at run-time).
- Tailor the level of detail according to the audience – in this case, a principal software engineer will appreciate the detail provided in the architectural breakdown, so include all major modules and their interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Libraries"
        DCT["DCT Core Library"]:::runtime
        Face["Transport Interface (face)"]:::runtime
        Sync["Synchronization Protocol (syncps)"]:::runtime
        Schema["Schema Management"]:::runtime
        Sigmgrs["Signature Management (sigmgrs)"]:::runtime
        Distr["Certificate/Key Distribution (distributors)"]:::runtime
        Shims["Network Protocol Shims (shims)"]:::runtime
    end

    subgraph "Tools"
        Compiler["Schema Compiler (VerSec Language)"]:::tools
        Dctwatch["Dctwatch (Network Traffic Monitor)"]:::tools
    end

    subgraph "Example Applications"
        Examples["Example Applications"]:::examples
    end

    subgraph "External Libraries"
        Date["date"]:::external
        Fmt["fmt"]:::external
        PCGR["pcg_random"]:::external
    end

    %% Relationships
    Examples -->|"uses"| DCT
    DCT -->|"includes"| Face
    DCT -->|"includes"| Sync
    DCT -->|"includes"| Schema
    DCT -->|"includes"| Sigmgrs
    DCT -->|"includes"| Distr
    DCT -->|"includes"| Shims

    Compiler -->|"generatesSchema"| Schema
    Dctwatch -->|"monitors"| Face

    DCT -.->|"dependsOn"| Date
    DCT -.->|"dependsOn"| Fmt
    DCT -.->|"dependsOn"| PCGR

    %% Styles
    classDef runtime fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef tools fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef examples fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef external fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;

    %% Click Events
    click DCT "https://github.com/pollere/dct/tree/main/include/dct"
    click Face "https://github.com/pollere/dct/tree/main/include/dct/face"
    click Sync "https://github.com/pollere/dct/tree/main/include/dct/syncps"
    click Schema "https://github.com/pollere/dct/tree/main/include/dct/schema"
    click Sigmgrs "https://github.com/pollere/dct/tree/main/include/dct/sigmgrs"
    click Distr "https://github.com/pollere/dct/tree/main/include/dct/distributors"
    click Shims "https://github.com/pollere/dct/tree/main/include/dct/shims"
    click Compiler "https://github.com/pollere/dct/tree/main/tools/compiler"
    click Dctwatch "https://github.com/pollere/dct/tree/main/tools/dctwatch"
    click Examples "https://github.com/pollere/dct/tree/main/examples"
    click Date "https://github.com/pollere/dct/tree/main/include/date"
    click Fmt "https://github.com/pollere/dct/tree/main/include/fmt"
    click PCGR "https://github.com/pollere/dct/tree/main/include/pcg_random"
```
