# runai-professional-services/runapy architecture

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

- Interactive diagram: https://gitdiagram.com/runai-professional-services/runapy
- Repository: https://github.com/runai-professional-services/runapy

## Overview

##### Main Components

a. Client Layer:
- Central `RunaiClient` class as the main entry point
- Authentication handling (both API tokens and CLIv2 token support)
- Configuration management
- Retry mechanism

b. Controllers Layer:
- Resource-specific controllers (Projects, Workloads, Assets, etc.)
- Controller factories and implementations
- Error handling

c. Models Layer:
- Data models and schema validation (using Pydantic)
- Type definitions

d. External Integration:
- Run:ai REST API connection
- CLIv2 configuration integration

**┌─────────────────────────────────────────────────────────┐**
- Client Applications                    │
- ┬─────────────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- RunaiClient                         │
- ┬────────────────┬────────────────┬────┤
- Authentication  │ Configuration  │ Retry Logic    │    │
- Management      │ Management     │                │    │
- ┴────────────────┴────────────────┘    │
- ↓                                 │
**┌─────────────────────────────────────────────────────┐  │**
- Controllers Layer                   │  │
- ┬───────────┬────────────┬──────────────┐ │  │
- Projects  │ Workloads │ Assets     │ Users/Roles   │ │  │
- Controller│ Controller│ Controller  │ Controller    │ │  │
- ┴───────────┴────────────┴──────────────┘ │  │
- ↓                             │  │
**┌─────────────────────────────────────────────────────┤  │**
- Models Layer                      │  │
- ┤  │
- Pydantic Models & Validation              │  │
- ┘  │
- ↓                                 │
**┌─────────────────────────────────────────────────────┐  │**
- Error Handling Layer                    │←─┘
- ┬─────────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────┐**
- Run:ai REST API                     │
- ┘

##### Important Details to Highlight

- Hierarchical relationship between controllers (e.g., Assets controller having sub-controllers for PVC, S3, Git, etc.)
- Authentication flow, including both standard API token and CLIv2 token paths
- Retry mechanism's integration with the error handling layer
- Validation flow from controllers through models

##### Implementation Notes

- The single entry point nature of the RunaiClient class
- The controller-based architecture for resource management
- The separation of concerns between authentication, business logic, and data validation
- The error handling and retry mechanism's pervasive nature
- The integration points with the Run:ai platform

This system design should provide a clear understanding of the SDK's architecture while maintaining enough detail to be useful for development and maintenance purposes.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CA[Client Applications]
        RC[RunaiClient]:::client
        Auth[Authentication Management]:::client
        Config[Configuration Management]:::client
        Retry[Retry Logic]:::client
        CLI[CLIv2 Integration]:::client
    end

    subgraph Controllers
        BC[Base Controller]:::controller
        PC[Projects Controller]:::controller
        WC[Workloads Controller]:::controller
        AC[Assets Controller]:::controller
        UC[Users/Roles Controller]:::controller
        DC[Department Controller]:::controller
        NP[Node Pools Controller]:::controller
        TC[Templates Controller]:::controller
        AR[Access Rules Controller]:::controller
        WS[Workspace Controller]:::controller
    end

    subgraph Models
        PM[Pydantic Models]:::model
        Val[Validation Layer]:::model
    end

    subgraph ErrorHandling
        EH[Error Handler]:::error
    end

    subgraph External
        API[Run:ai REST API]:::external
    end

    %% Relationships
    CA --> RC
    RC --> Auth
    RC --> Config
    RC --> Retry
    RC --> CLI
    RC --> BC

    BC --> PC
    BC --> WC
    BC --> AC
    BC --> UC
    BC --> DC
    BC --> NP
    BC --> TC
    BC --> AR
    BC --> WS

    PC & WC & AC & UC & DC & NP & TC & AR & WS --> PM
    PM --> Val

    RC --> EH
    BC --> EH
    EH --> API

    %% Click Events
    click RC "https://github.com/runai-professional-services/runapy/blob/main/runai/client.py"
    click CLI "https://github.com/runai-professional-services/runapy/blob/main/runai/cliv2_config_loader.py"
    click EH "https://github.com/runai-professional-services/runapy/blob/main/runai/errors.py"
    click PM "https://github.com/runai-professional-services/runapy/blob/main/runai/models.py"
    click BC "https://github.com/runai-professional-services/runapy/blob/main/runai/controllers.py"
    click AC "https://github.com/runai-professional-services/runapy/blob/main/runai/assets.py"
    click PC "https://github.com/runai-professional-services/runapy/blob/main/tests/controllers/test_project_controller.py"
    click WC "https://github.com/runai-professional-services/runapy/blob/main/tests/controllers/test_workloads_controller.py"
    click UC "https://github.com/runai-professional-services/runapy/blob/main/tests/controllers/test_user_controller.py"
    click DC "https://github.com/runai-professional-services/runapy/blob/main/tests/controllers/test_department_controller.py"
    click NP "https://github.com/runai-professional-services/runapy/blob/main/tests/controllers/test_node_pools_controller.py"
    click TC "https://github.com/runai-professional-services/runapy/blob/main/tests/controllers/test_template_controller.py"
    click AR "https://github.com/runai-professional-services/runapy/blob/main/tests/controllers/test_access_rule_controller.py"
    click WS "https://github.com/runai-professional-services/runapy/blob/main/tests/controllers/test_workspace_controller.py"

    %% Styles
    classDef client fill:#3498db,stroke:#2980b9,color:white
    classDef controller fill:#2ecc71,stroke:#27ae60,color:white
    classDef model fill:#f1c40f,stroke:#f39c12,color:black
    classDef error fill:#e74c3c,stroke:#c0392b,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Legend
    subgraph Legend
        L1[Client Layer]:::client
        L2[Controllers Layer]:::controller
        L3[Models Layer]:::model
        L4[Error Handling]:::error
        L5[External Systems]:::external
    end
```
