# xdevplatform/xdk architecture

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

- Interactive diagram: https://gitdiagram.com/xdevplatform/xdk
- Repository: https://github.com/xdevplatform/xdk

## Overview

##### Project Type and Purpose
- This is an open-source, multi-crate Rust workspace whose primary goal is to generate type-safe SDKs (“XDKs”) for the X APIs from OpenAPI 3.0 specs.
- It provides:
- xdk-openapi – a minimal OpenAPI parser
- xdk-gen – a generic code-generation library
- xdk-build – a command-line wrapper that drives parsing and generation
- utils/python – post-processing (e.g., code formatting)
- Python SDK output under xdk/python
- The user workflow: supply an OpenAPI spec → xdk-build CLI → xdk-openapi parser + xdk-gen templates → formatted Python SDK.

##### Key Components
- **Input**
- OpenAPI spec files (YAML/JSON)
- **xdk-openapi (Rust crate)**
- Reads and parses the spec into an AST/context
- Exports core models and reference resolution
- **xdk-gen (Rust crate)**
- Core library: transforms parser AST into language-agnostic model
- Language‐specific backend (python generator) that applies Jinja2 templates
- Contains templates for Python client, models, auth, README, setup.py, etc.
- **xdk-build (Rust CLI)**
- User-facing tool
- Invokes xdk-openapi → xdk-gen → utils/python.format
- Handles CLI args, file I/O, error reporting, logging
- **utils/python**
- Simple Python-based code formatter applied to generated files
- **Output**
- A ready-to-install Python package under xdk/python
- Packaged modules for each API area (tweets, users, likes, etc.)
- **Tests**
- OpenAPI spec sanity tests under tests/openapi
- Python integration/orchestration tests under tests/python

##### Relationships and Data Flow
1. User passes `openapi.yaml` to xdk-build CLI
2. xdk-build calls xdk-openapi parser → builds internal spec model
3. Parsed model flows into xdk-gen core → constructs generator context
4. xdk-gen python backend applies Jinja2 templates → emits raw .py files
5. utils/python.format script tidies up code style
6. Final files land in `--output` directory (xdk/python)
7. tests drive both parser unit tests and generated SDK integration

##### Architectural Patterns & Principles
- **Separation of Concerns**: parsing, model transformation, templating, formatting, CLI orchestration all in separate crates/modules
- **Plugin-style Backends**: xdk-gen core is language-agnostic; language-specific generators live under `src/python` and `templates/python`
- **Workspace-level Modularity**: each crate builds independently, can be tested/published separately
- **Template-Driven Generation**: uses Jinja2 (.j2) templates for maximum flexibility

- Parser (xdk-openapi)
- Generator Core (xdk-gen/core)
- Python Generator (xdk-gen/python + templates)
- CLI (xdk-build)
- Formatter (utils/python)
- Output SDK (xdk/python)
- Tests
- Spec → CLI → Parser → Generator Core → Templates → Formatter → SDK Output
- CLI directly orchestrates each step
- Tests target Parser and SDK Output
- Template files in another (e.g., orange)
- Python code/formatter in green
- Tests in gray

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input
    Spec["OpenAPI Spec (YAML/JSON)"]

    %% Crates
    CLI["xdk-build CLI"]:::rust
    Parser["xdk-openapi"]:::rust
    GenCore["xdk-gen Core"]:::rust
    PyBackend["xdk-gen Python Backend"]:::rust

    %% Templates & Formatter
    Templates["xdk-gen Templates"]:::template
    Formatter["utils/python Formatter"]:::python

    %% Output
    SDK["Output SDK (xdk/python)"]:::python

    %% Tests
    TestsParser["OpenAPI Spec Tests"]:::test
    TestsSDK["Python Integration Tests"]:::test

    %% Flow
    Spec -->|"passes spec"| CLI
    CLI -->|"invokes parser"| Parser
    Parser -->|"AST (OpenAPI AST)"| GenCore
    GenCore -->|"GeneratorContext"| PyBackend
    PyBackend -->|"applies Jinja2"| Templates
    Templates -->|"raw .py files"| Formatter
    Formatter -->|"formatted .py"| SDK
    CLI -->|"orchestrates formatting"| Formatter

    TestsParser -->|"validate parser"| Parser
    TestsSDK -->|"validate SDK"| SDK

    %% Click Events
    click Parser "https://github.com/xdevplatform/xdk/blob/main/xdk-openapi/Cargo.toml"
    click GenCore "https://github.com/xdevplatform/xdk/tree/main/xdk-gen/src/core"
    click PyBackend "https://github.com/xdevplatform/xdk/tree/main/xdk-gen/src/python"
    click Templates "https://github.com/xdevplatform/xdk/tree/main/xdk-gen/templates/python"
    click CLI "https://github.com/xdevplatform/xdk/blob/main/xdk-build/Cargo.toml"
    click Formatter "https://github.com/xdevplatform/xdk/blob/main/utils/python/format.py"
    click SDK "https://github.com/xdevplatform/xdk/tree/main/xdk/python"
    click TestsParser "https://github.com/xdevplatform/xdk/tree/main/tests/openapi"
    click TestsSDK "https://github.com/xdevplatform/xdk/tree/main/tests/python"

    %% Styles
    classDef rust fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef template fill:#F4A261,stroke:#333,stroke-width:1px
    classDef python fill:#2A9D8F,stroke:#333,stroke-width:1px
    classDef test fill:#CCCCCC,stroke:#333,stroke-width:1px
```
