# tencentblueking/bkpaas-python-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/tencentblueking/bkpaas-python-sdk
- Repository: https://github.com/tencentblueking/bkpaas-python-sdk

## Overview

##### Project Type and Purpose
- This is a monorepo of multiple related Python SDKs (`blue-krill`, `bkstorages`, `bkapi-client-core`, `bkapi-component-open`, `apigw-manager`, `bkpaas-auth`, `paas-service`), packaged and released together to support BlueKing PaaS/SaaS development.
- Each SDK provides reusable building blocks: utility functions, storage backends, API clients, authentication modules, gateway management, and an enhanced service framework.

##### File-Structure Analysis
- Top-level: CI configurations (`.ci/`, `.github/workflows/`), documentation (`docs/`), monorepo `pyproject.toml`, `readme.md`, license.
- `sdks/`: seven independent Python packages, each with its own tests, demos, build files.
- blue-krill: core utilities (async, auth, monitoring, storage, web helpers)
- bkstorages: Django storage backends for BlueKing repo & S3
- bkapi-client-core: generic BlueKing Cloud API & ESB client
- bkapi-component-open: client for “component open” APIs
- apigw-manager: CLI/Django management commands to sync API Gateway
- bkpaas-auth: PaaS-internal auth (token, middleware, plugins)
- paas-service: PaaS enhancement framework (models, views, tasks)
- Build/Ops: Poetry/pyproject, Makefiles, Dockerfiles (for `apigw-manager`), GitHub Actions workflows for each SDK.

##### Key Insights from README
- Purpose: eliminate repeated designs, provide best practices for common PaaS development scenarios.
- Audience: PaaS/SaaS developers integrating with BlueKing ecosystem.
- Tech stack: Python ≥3.6, Django integrations, Kubernetes (Helm charts in examples), S3/Ceph storage, Prometheus for monitoring, JWT for auth.

- Developer Environment – local code, pip installs SDKs
- Monorepo & CI/CD – GitHub repo, CI pipelines, PyPI/Artifacts registry
- SDK Packages – each of the seven `sdks/*` as separate modules
- BlueKing PaaS Control Plane – API Gateway, ESB, CMDB, Token Service
- External Services – S3/Ceph storage, Kubernetes API Server, Prometheus
- Client Apps – Django apps or CLI tools that consume the SDKs

- Developer → Monorepo: commits, PRs trigger CI/CD
- CI/CD → Package Registry: build & publish each SDK
- Client Apps → SDKs: import & call functions
- SDKs → BlueKing PaaS APIs: REST calls via `bkapi-client-core`, `bkapi-component-open`, `apigw-manager`
- `bkpaas-auth` → Token Service/DB: user authentication & token validation
- `bkstorages` → S3/Ceph: upload/download files
- `blue-krill/monitoring` → Prometheus: metrics/probes
- `apigw-manager` → Kubernetes API: deploy Helm charts, sync Gateway resources

c. Architectural Patterns & Principles
- Modular monorepo: independent, loosely coupled packages
- Reusable library pattern: common “blue-krill” core, layered dependencies
- CI/CD as code: per-SDK GitHub Actions pipelines, shared templates
- Test-driven & demo apps: each SDK has tests and example/demo integrations

d. Technologies & Frameworks
- Python 3.6+, Poetry/pyproject for packaging
- Django for web integrations (`apigw-manager`, `paas-service`, `bkstorages`)
- Helm/Kubernetes for Gateway sync
- REST & HTTP clients for BlueKing APIs, ESB
- Prometheus client libraries for monitoring

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Swimlane: Developer Environment
    subgraph "Developer Environment"
        DEV["Developer"]:::developer
    end

    %% Swimlane: Monorepo & CI/CD
    subgraph "Monorepo & CI/CD"
        REPO["GitHub Repo"]:::external
        subgraph "CI Configurations"
            CI1[".ci/"]:::pipeline
            CI2[".github/workflows/"]:::pipeline
        end
        PIPELINE["CI Pipelines"]:::pipeline
        REGISTRY["Package Registry"]:::registry
    end

    %% Swimlane: SDK Packages
    subgraph "SDK Packages"
        subgraph "blue-krill" 
            BK["blue-krill"]:::sdk
            PROM["Prometheus Client"]:::external
        end
        subgraph "bkstorages"
            RGW["rgw.py"]:::sdk
            BKREPO["bkrepo.py"]:::sdk
        end
        subgraph "bkapi-client-core"
            APIGW_CORE["apigateway/"]:::sdk
            ESB_CORE["esb/"]:::sdk
        end
        BKC_OPEN["bkapi-component-open"]:::sdk
        subgraph "apigw-manager"
            CLI["apigw-manager.sh"]:::sdk
            DJANGO_AGW["apigw/"]:::sdk
            K8S_HELPER["k8s_helper.py"]:::sdk
            DEMO_AGW["demo/"]:::sdk
        end
        subgraph "bkpaas-auth"
            TOKEN["token.py"]:::sdk
            MIDDLE["middlewares.py"]:::sdk
        end
        PAAS["paas-service"]:::sdk
        DEMO_CORE["bkapi-client-core demo"]:::external
        DEMO_PAAS["paas-service tests"]:::external
    end

    %% Swimlane: Client Applications
    subgraph "Client Applications"
        APP1["Django Apps/CLI Tools"]:::external
    end

    %% Swimlane: BlueKing PaaS Control Plane
    subgraph "BlueKing PaaS Control Plane"
        APIGW["API Gateway"]:::external
        ESB["ESB"]:::external
        CMDB["CMDB"]:::external
        TOKEN_SVC["Token Service"]:::external
    end

    %% Swimlane: External Services
    subgraph "External Services"
        S3["S3/Ceph Storage"]:::database
        K8S["Kubernetes API"]:::database
        PROMETHEUS["Prometheus"]:::database
    end

    %% Connections
    DEV -->|commits/PRs| REPO
    REPO -->|triggers| PIPELINE
    PIPELINE -->|build & publish| REGISTRY

    APP1 -->|imports| BK
    APP1 -->|imports| BKREPO
    APP1 -->|imports| RGW
    APP1 -->|imports| APIGW_CORE
    APP1 -->|imports| ESB_CORE
    APP1 -->|imports| BKC_OPEN
    APP1 -->|imports| CLI
    APP1 -->|imports| DJANGO_AGW
    APP1 -->|imports| K8S_HELPER
    APP1 -->|imports| TOKEN
    APP1 -->|imports| MIDDLE
    APP1 -->|imports| PAAS

    BK -->|metrics| PROMETHEUS
    RGW -->|upload/download| S3
    BKREPO -->|upload/download| S3
    APIGW_CORE -->|REST calls| APIGW
    ESB_CORE -->|REST calls| ESB
    BKC_OPEN -->|calls| APIGW
    CLI -->|sync| APIGW
    DJANGO_AGW -->|sync| APIGW
    K8S_HELPER -->|Helm/CRD sync| K8S
    TOKEN -->|validate| TOKEN_SVC
    MIDDLE -->|auth middleware| TOKEN_SVC
    PAAS -->|uses| CMDB

    %% Click Events
    click CI1 "https://github.com/tencentblueking/bkpaas-python-sdk/tree/master/.ci/"
    click CI2 "https://github.com/tencentblueking/bkpaas-python-sdk/tree/master/.github/workflows/"
    click BK "https://github.com/tencentblueking/bkpaas-python-sdk/tree/master/sdks/blue-krill/blue_krill/"
    click PROM "https://github.com/tencentblueking/bkpaas-python-sdk/tree/master/sdks/blue-krill/blue_krill/monitoring/prometheus/"
    click RGW "https://github.com/tencentblueking/bkpaas-python-sdk/blob/master/sdks/bk-storages/bkstorages/backends/rgw.py"
    click BKREPO "https://github.com/tencentblueking/bkpaas-python-sdk/blob/master/sdks/bk-storages/bkstorages/backends/bkrepo.py"
    click APIGW_CORE "https://github.com/tencentblueking/bkpaas-python-sdk/tree/master/sdks/bkapi-client-core/bkapi_client_core/apigateway/"
    click ESB_CORE "https://github.com/tencentblueking/bkpaas-python-sdk/tree/master/sdks/bkapi-client-core/bkapi_client_core/esb/"
    click BKC_OPEN "https://github.com/tencentblueking/bkpaas-python-sdk/blob/master/sdks/bkapi-component-open/bkapi_component/open/client.py"
    click CLI "https://github.com/tencentblueking/bkpaas-python-sdk/blob/master/sdks/apigw-manager/bin/apigw-manager.sh"
    click DJANGO_AGW "https://github.com/tencentblueking/bkpaas-python-sdk/tree/master/sdks/apigw-manager/src/apigw_manager/apigw/"
    click K8S_HELPER "https://github.com/tencentblueking/bkpaas-python-sdk/blob/master/sdks/apigw-manager/src/apigw_manager/apigw/k8s_helper.py"
    click TOKEN "https://github.com/tencentblueking/bkpaas-python-sdk/blob/master/sdks/bkpaas-auth/bkpaas_auth/core/token.py"
    click MIDDLE "https://github.com/tencentblueking/bkpaas-python-sdk/blob/master/sdks/bkpaas-auth/bkpaas_auth/middlewares.py"
    click PAAS "https://github.com/tencentblueking/bkpaas-python-sdk/tree/master/sdks/paas-service/paas_service/"

    %% Styles
    classDef sdk fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#bbf,stroke:#333,stroke-width:1px
    classDef pipeline fill:#ffb,stroke:#333,stroke-width:1px
    classDef registry fill:#bfb,stroke:#333,stroke-width:1px
    classDef developer fill:#fbf,stroke:#333,stroke-width:1px
    classDef database fill:#def,stroke:#333,stroke-width:1px
```
