# nsu-ai/kappa architecture

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

- Interactive diagram: https://gitdiagram.com/nsu-ai/kappa
- Repository: https://github.com/nsu-ai/kappa

## Overview

##### Project type and purpose
- This is a Python client-side SDK (“kf_sdk”) that wraps HTTP calls to two microservices:
- SessionManagementApi (user‐micro‐service)
- DatasetManagementApi (data-micro-service)
- Its purpose is to simplify authentication (session management) and dataset retrieval for Kappa Framework v1.0.0.

##### File structure
- Top‐level: CI/CD configs (.github/, .travis.yml, .gitlab‐ci.yml, tox.ini), packaging (setup.py, pyproject.toml, requirements.txt), docs/ (OpenAPI‐generated Markdown for each endpoint and model), tests/
- kf_sdk package:
- configuration.py – global settings (host URLs, tokens)
- api_client.py / rest.py – HTTP client layer built on urllib3
- api/ – one class per endpoint group (dataset_management_api.py, session_management_api.py)
- models/ – Pydantic (v2) data classes for request and response bodies
- exceptions.py – custom exception types

a. Main components:
1) Client application (user code)
2) kf_sdk layers:
- Configuration (host, auth token)
- ApiClient & HTTP transport (rest.py)
- API modules (SessionManagementApi, DatasetManagementApi)
- Model layer (Pydantic classes)
- Exception/Error handling
3) External microservices:
- User-micro-service (Session endpoint)
- Data-micro-service (Dataset endpoint)
4) Optional: CI/CD pipelines (GitHub Actions, Travis, GitLab CI) and docs generator
b. Relationships and interactions:
- Client code imports kf_sdk → configures host & token → instantiates ApiClient
- ApiClient invokes API class methods → translate method call into HTTP request → send to microservice
- Microservice returns JSON → ApiClient deserializes into model objects → returns to client
- Errors in HTTP or validation propagate via custom exceptions
c. Architectural patterns & design principles:
- Layered architecture (transport layer, API interface layer, model layer, exception layer)
- Separation of concerns: configuration, client transport, API definitions, data models
- OpenAPI‐driven code generation (docs/ content mirrors generated SDK)
- Dependency injection of Configuration into ApiClient
d. Key technologies & libraries:
- Python 3.8+
- urllib3 for HTTP transport
- Pydantic v2 for models and validation
- setuptools / pip packaging

##### Detail without over-splitting
- Logical layers of the SDK but avoid showing every single file
- Groupings: configuration, transport, API, models, exceptions
- Both Session and Dataset flows side by side, highlighting shared ApiClient and config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    ClientApp["Client Application"]:::external

    %% SDK Layers
    subgraph "kf_sdk SDK" 
        direction TB
        Config["kf_sdk.Configuration"]:::sdk
        ApiClient["kf_sdk.ApiClient"]:::sdk
        subgraph "HTTP Transport Helpers"
            direction TB
            Rest["rest.py"]:::sdk
            ApiResponse["api_response.py"]:::sdk
        end
        subgraph "API Modules"
            direction TB
            SessionAPI["SessionManagementApi"]:::sdk
            DatasetAPI["DatasetManagementApi"]:::sdk
        end
        Models["Pydantic Models"]:::model
        Exceptions["Exceptions"]:::error
    end

    %% External Services
    UserService["User-Microservice\n(POST /session/login,\nDELETE /session/logout)"]:::service
    DataService["Data-Microservice\n(GET /datasets/…)"]:::service

    %% Docs
    subgraph "OpenAPI Documentation"
        direction TB
        DocSession["SessionManagementApi.md"]:::docs
        DocDataset["DatasetManagementApi.md"]:::docs
        DocNewSession["NewSession.md"]:::docs
        DocDatasetDetails["DatasetDetails.md"]:::docs
        DocValidationError["ValidationError.md"]:::docs
        DocHTTPValidation["HTTPValidationError.md"]:::docs
    end

    %% CI/CD
    subgraph "CI/CD Workflows"
        direction TB
        GitHub[".github/workflows/python.yml"]:::ci
        Travis[".travis.yml"]:::ci
        GitLabCI[".gitlab-ci.yml"]:::ci
    end

    %% Packaging
    subgraph "Packaging & Metadata"
        direction TB
        SetupPy["setup.py"]:::ci
        PyProject["pyproject.toml"]:::ci
        Requirements["requirements.txt"]:::ci
        SetupCfg["setup.cfg"]:::ci
    end

    %% Flows
    ClientApp -->|"import & configure"| Config
    Config -->|"inject config"| ApiClient
    ApiClient -->|"uses"| Rest
    ApiClient -->|"uses"| ApiResponse
    ApiClient -->|"instantiates"| SessionAPI
    ApiClient -->|"instantiates"| DatasetAPI

    SessionAPI -->|"POST /session/login"| UserService
    DatasetAPI -->|"GET /datasets"| DataService

    UserService -->|"JSON Response"| ApiClient
    DataService -->|"JSON Response"| ApiClient

    ApiClient -->|"deserialize"| Models
    Models -->|"return objects"| ClientApp

    %% Exception Flow
    ApiClient -.->|"HTTP or Validation Error"| Exceptions
    SessionAPI -.->|"API Error"| Exceptions
    DatasetAPI -.->|"API Error"| Exceptions
    Exceptions -->|"raise to"| ClientApp

    %% Side components
    ClientApp --- OpenAPI_Docs([" "]):::none
    OpenAPI_Docs --> DocSession
    OpenAPI_Docs --> DocDataset
    OpenAPI_Docs --> DocNewSession
    OpenAPI_Docs --> DocDatasetDetails
    OpenAPI_Docs --> DocValidationError
    OpenAPI_Docs --> DocHTTPValidation

    ClientApp --- CI_CD([" "]):::none
    CI_CD --> GitHub
    CI_CD --> Travis
    CI_CD --> GitLabCI

    ClientApp --- Packaging([" "]):::none
    Packaging --> SetupPy
    Packaging --> PyProject
    Packaging --> Requirements
    Packaging --> SetupCfg

    %% Click events
    click Config "https://github.com/nsu-ai/kappa/blob/main/kf_sdk/configuration.py"
    click ApiClient "https://github.com/nsu-ai/kappa/blob/main/kf_sdk/api_client.py"
    click Rest "https://github.com/nsu-ai/kappa/blob/main/kf_sdk/rest.py"
    click ApiResponse "https://github.com/nsu-ai/kappa/blob/main/kf_sdk/api_response.py"
    click SessionAPI "https://github.com/nsu-ai/kappa/blob/main/kf_sdk/api/session_management_api.py"
    click DatasetAPI "https://github.com/nsu-ai/kappa/blob/main/kf_sdk/api/dataset_management_api.py"
    click Models "https://github.com/nsu-ai/kappa/tree/main/kf_sdk/models/"
    click Exceptions "https://github.com/nsu-ai/kappa/blob/main/kf_sdk/exceptions.py"
    click DocSession "https://github.com/nsu-ai/kappa/blob/main/docs/SessionManagementApi.md"
    click DocDataset "https://github.com/nsu-ai/kappa/blob/main/docs/DatasetManagementApi.md"
    click DocNewSession "https://github.com/nsu-ai/kappa/blob/main/docs/NewSession.md"
    click DocDatasetDetails "https://github.com/nsu-ai/kappa/blob/main/docs/DatasetDetails.md"
    click DocValidationError "https://github.com/nsu-ai/kappa/blob/main/docs/ValidationError.md"
    click DocHTTPValidation "https://github.com/nsu-ai/kappa/blob/main/docs/HTTPValidationError.md"
    click GitHub "https://github.com/nsu-ai/kappa/blob/main/.github/workflows/python.yml"
    click Travis "https://github.com/nsu-ai/kappa/blob/main/.travis.yml"
    click GitLabCI "https://github.com/nsu-ai/kappa/blob/main/.gitlab-ci.yml"
    click SetupPy "https://github.com/nsu-ai/kappa/blob/main/setup.py"
    click PyProject "https://github.com/nsu-ai/kappa/blob/main/pyproject.toml"
    click Requirements "https://github.com/nsu-ai/kappa/blob/main/requirements.txt"
    click SetupCfg "https://github.com/nsu-ai/kappa/blob/main/setup.cfg"

    %% Styles
    classDef sdk fill:#D0E6FF,stroke:#4A90E2,color:#003366
    classDef external fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef service fill:#E0F7FA,stroke:#00796B,color:#004D40
    classDef model fill:#FFF9C4,stroke:#FBC02D,color:#F57F17
    classDef error stroke-dasharray: 5 5,fill:#FFEBEE,stroke:#C62828,color:#B71C1C
    classDef docs fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
    classDef ci fill:#ECEFF1,stroke:#607D8B,color:#263238
    classDef none stroke:none,fill:none, color:none
```
