# dirkjanm/roadtools architecture

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

- Interactive diagram: https://gitdiagram.com/dirkjanm/roadtools
- Repository: https://github.com/dirkjanm/roadtools

## Overview

##### Main Components
- ROADlib – This is the foundational library that provides common functionality:
- It includes modules for authentication (asyncauth, asyncdeviceauth, deviceauth), metadata generation (metagen, metagen_msgraph), and database creation (dbgen, dbgen_msgraph).
- The database model is auto-generated using metadata definitions from the Azure AD internal API.
- ROADrecon – A tool for exploring and analyzing Azure AD data:
- It uses ROADlib to asynchronously retrieve data from the Azure AD Graph API.
- It populates an SQLAlchemy-backed database with the fetched data.
- It comes with a plugin system (plugins for bloodhound, policies, etc.) to process and transform the data.
- The front-end component is built in Angular (located in roadrecon/frontend) for interactive offline data analysis.
- roadtx – The token exchange tool:
- Provides support for various Azure AD authentication flows.
- Handles operations to exchange and utilize different tokens.
- Its functionality revolves around token management and often reuses parts of ROADlib.
- Additional Components:
- roadoidc: Contains a Flask-based web application (an OpenID Connect related demo or service).
- browsercore: Likely a browser-integrated tool (with a manifest and test script) that supports the overall framework.
- Testing and CI/CD: The tests directory, Azure Pipelines configuration, and setup scripts indicate an emphasis on continuous integration/delivery and testing.

##### Relationships and Interactions
- ROADlib is at the heart of the framework: both ROADrecon and roadtx rely on it for handling Azure AD interactions, authentication, and database model generation.
- ROADrecon divides into two primary layers:
- The backend that performs asynchronous HTTP calls to fetch data and populate the database.
- The Angular front-end that queries this offline database to provide a user-friendly interface.
- The plugin system within roadrecon extends its functionality to produce various outputs (e.g., for red/blue team perspectives).
- roadtx operates as a standalone tool, but it shares similar dependencies with ROADlib for token operations.
- roadoidc (the Flask app) and browsercore likely serve specialized roles or proof-of-concept features; they interface with other parts of the framework or demonstrate integration with web-based/OIDC protocols.
- External integrations such as Azure AD (and possibly MS Graph through the msgraph-specific modules) are key to the system’s operation.

##### Architectural Patterns and Design Principles
- Modularity: The separation into ROADlib, ROADrecon, and roadtx demonstrates a clear modular design where each tool focuses on a distinct set of functionalities.
- Separation of Concerns: The Angular front-end is cleanly separated from the ROADrecon backend, emphasizing a clear API/data-flow pipeline.
- Asynchronous Processing: The use of async methods in ROADlib and ROADrecon indicates non-blocking calls for better performance when interacting with external services.
- Plugin Architecture: ROADrecon’s plugins allow for extensibility and customization in processing the Azure AD data.
- Reusability: ROADlib’s architecture supports reuse across multiple tools (both recon and token exchange).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    AAD["Azure Active Directory"]:::external

    %% Core Framework
    subgraph "Core Framework"
        ROADlib["ROADlib (Core Library)\n(auth, metadata, db generation)"]:::core
    end

    %% Tools and Applications
    subgraph "Tools"
        ROADreconBackend["ROADrecon Backend\n(Data Gathering, Plugins)"]:::backend
        Plugins["Plugins System\n(bloodhound, policies, etc.)"]:::backend
        ROADreconFrontend["ROADrecon Frontend (Angular UI)"]:::frontend
        roadtx["roadtx (Token Exchange)"]:::token
        roadoidc["roadoidc (Flask OIDC Service)"]:::flask
        browsercore["browsercore (Browser-integrated Tool)"]:::browser
    end

    %% Services
    subgraph "Services"
        Database["SQLAlchemy Database"]:::database
    end

    %% Testing and CI/CD
    subgraph "Testing & CI/CD"
        Testing["Tests & CI/CD"]:::testing
        AzurePipelines["CI/CD (Azure Pipelines)"]:::testing
    end

    %% Relationships
    AAD -->|"auth/metadata"| ROADlib
    ROADlib -->|"provides"| ROADreconBackend
    ROADlib -->|"provides"| roadtx
    ROADreconBackend -->|"uses"| Plugins
    ROADreconBackend -->|"populates"| Database
    ROADreconBackend -->|"supplies"| ROADreconFrontend
    roadtx -->|"reuses"| ROADlib
    roadoidc -->|"integrates"| ROADlib
    browsercore -->|"demonstrates"| ROADlib

    %% Testing connections
    Testing --- ROADlib
    Testing --- ROADreconBackend
    Testing --- roadtx
    Testing --- roadoidc
    Testing --- browsercore
    AzurePipelines --> Testing

    %% Click Events
    click ROADlib "https://github.com/dirkjanm/roadtools/tree/master/roadlib/roadtools/roadlib/"
    click ROADreconBackend "https://github.com/dirkjanm/roadtools/tree/master/roadrecon/roadtools/roadrecon/"
    click ROADreconFrontend "https://github.com/dirkjanm/roadtools/tree/master/roadrecon/frontend/"
    click roadtx "https://github.com/dirkjanm/roadtools/tree/master/roadtx/roadtools/roadtx/"
    click roadoidc "https://github.com/dirkjanm/roadtools/tree/master/roadoidc/flaskapp/"
    click browsercore "https://github.com/dirkjanm/roadtools/tree/master/browsercore/"
    click Testing "https://github.com/dirkjanm/roadtools/tree/master/tests/"
    click AzurePipelines "https://github.com/dirkjanm/roadtools/blob/master/azure-pipelines.yml"

    %% Styles
    classDef external fill:#f9d,stroke:#333,stroke-width:2px;
    classDef core fill:#cce,stroke:#333,stroke-width:2px;
    classDef backend fill:#cfc,stroke:#333,stroke-width:2px;
    classDef frontend fill:#fcf,stroke:#333,stroke-width:2px;
    classDef token fill:#cff,stroke:#333,stroke-width:2px;
    classDef flask fill:#ffd,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef browser fill:#dfd,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef database fill:#ffe,stroke:#333,stroke-width:2px;
    classDef testing fill:#eef,stroke:#333,stroke-width:2px;
```
