# tencent/cloudbase-framework architecture

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

- Interactive diagram: https://gitdiagram.com/tencent/cloudbase-framework
- Repository: https://github.com/tencent/cloudbase-framework

## Overview

##### Project type and purpose
- This is a monorepo (Lerna-managed) Node.js/TypeScript toolset and CLI—CloudBase Framework—designed to provide “one-click” front-end and back-end deployment on Tencent Cloud’s Serverless platform.
- Key use case: automatically detect your application’s technologies (Vue, Nuxt, Next, Node, Dart, etc.), load the corresponding plugin(s), build the code, then deploy it as cloud functions, static hosting, managed containers, databases, etc., without writing cloud-specific infrastructure code yourself.

##### Main components
a. CLI layer
- `@cloudbase/cli` (root package.json & bin entry)
- Initialization commands (`cloudbase init`, `cloudbase framework deploy`)
b. Core framework (`packages/framework-core`)
- API entrypoints (`src/index.ts`)
- Configuration resolution and validation (`src/config`)
- Lifecycle orchestrator and hook manager (`src/lifecycle`, `src/hooks`)
- Plugin manager (`src/plugin-manager`)—loads & invokes plugins
- Builder, generator, deployer, SAM convertor modules (`src/builder`, `src/generator`, `src/deployer`, `src/sam`)
- Context and utilities (`src/context`, `src/utils`, `src/logger`, `src/error`)
c. Plugin packages (`packages/framework-plugin-*` + builder packages)
- Website plugin (static hosting)
- Node plugin (cloud functions / cloud hosting)
- Nuxt, Next, Deno, Dart, MP (mini-program), Function, Container, Database, Auth, etc.
- Each plugin implements build/deploy steps against cloud APIs
d. Builders (`packages/cloudbase-*-builder`)
- Low-level “asset launcher” and bundling logic for various targets (Next, Nuxt, static, Node, etc.)
e. Configuration schema & CLI helpers
- JSON schema for `.cloudbaserc.json` (`packages/cloudbaserc-json-schema`)
- Scripts folder: build-runner, doc-builder, CI helpers, license checks
f. Documentation & community resources
- `README.md`, `CLI_GUIDE.md`, `community` posts, `doc` folder

##### Relationships and data flow
1. User runs `cloudbase` CLI → CLI entry loads `framework-core` API
2. Core reads project root config (`cloudbaserc.json` or auto-detect), resolves `framework.plugins`
3. Plugin manager loads detected plugins (via NPM packages under `packages/framework-plugin-*`)
4. For each plugin:
- Execute “detect” phase (to validate the project structure)
- Execute “build” phase (invoke matching builder from `cloudbase-*-builder`)
- Package artifacts (functions/containers/static files)
- Execute “deploy” phase (call Tencent Cloud TCB REST APIs or SAM conversion + Cloud API)
5. Core orchestrates phases in sequence, aggregates results, logs progress

##### Architectural patterns & design principles
- Plugin architecture: core orchestrator + pluggable modules, each implements a uniform interface (detect, build, deploy)
- Command pattern: CLI commands map to core APIs
- Lifecycle hooks: stages (pre-build, post-build, pre-deploy, post-deploy) allow cross-cutting concerns
- Monorepo modularization: shared utilities & types in `framework-core`, isolated plugin packages
- Separation of concerns:
- Config resolution/validation → `config`
- Business logic (build/deploy) → `builder` & `deployer`
- Plugin management → `plugin-manager`
- Context/environment abstraction → `context`

##### Final recommendations
- In the Plugin Layer, represent at least one or two sample plugins (e.g., website, node, function) to illustrate extensibility

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLIpkg["package.json"]:::core
        CLIBin["bin entry"]:::core
    end

    %% Core Framework
    subgraph "Core Framework"
        CoreAPI["src/index.ts"]:::core
        ConfigResolve["src/config/resolve-config.ts"]:::core
        ConfigValidate["src/config/validate.ts"]:::core
        Lifecycle["src/lifecycle/index.ts"]:::core
        Hooks["src/hooks/index.ts"]:::core
        PluginMgr["src/plugin-manager/index.ts"]:::core
        BuilderCore["src/builder/index.ts"]:::core
        DeployerCore["src/deployer/index.ts"]:::core
        SAM["src/sam/index.ts"]:::core
        Context["src/context/index.ts"]:::core
        Utils["src/utils"]:::core
        Logger["src/logger/index.ts"]:::core
        ErrorCore["src/error.ts"]:::core
    end

    %% Plugin Layer
    subgraph "Plugin Layer"
        AuthP["Auth Plugin"]:::plugin
        ContainerP["Container Plugin"]:::plugin
        DartP["Dart Plugin"]:::plugin
        DatabaseP["Database Plugin"]:::plugin
        FunctionP["Function Plugin"]:::plugin
        MPP["Mini-program Plugin"]:::plugin
        NextP["Next.js Plugin"]:::plugin
        NodeP["Node Plugin"]:::plugin
        NuxtP["Nuxt Plugin"]:::plugin
        WebsiteP["Website Plugin"]:::plugin
    end

    %% Builder Packages
    subgraph "Builder Packages"
        NextBuilder["Next Builder"]:::plugin
        NodeBuilder["Node Builder"]:::plugin
        NuxtBuilder["Nuxt Builder"]:::plugin
        StaticBuilder["Static Builder"]:::plugin
    end

    %% Config Schema & CLI Helpers
    subgraph "Config Schema & CLI Helpers"
        Schema["cloudbaserc-base-schema.json"]:::gray
        SchemaTest["cloudbaserc.json (tests)"]:::gray
    end

    %% Documentation & Community
    subgraph "Docs & Community"
        Readme["README.md"]:::gray
        Guide["CLI_GUIDE.md"]:::gray
        DocFolder["doc/"]:::gray
        Community["community/posts/"]:::gray
    end

    %% Scripts & Tools
    subgraph "Scripts & Tools"
        BuildRunner["scripts/build-runner/"]:::gray
        CIHelper["scripts/ci-log-viewer/"]:::gray
        License["scripts/license-checker.js"]:::gray
        LinkPkg["scripts/link-packages.js"]:::gray
        Link["scripts/link.js"]:::gray
        Spawn["scripts/spawn.js"]:::gray
    end

    %% Tencent Cloud Services
    subgraph "Tencent Cloud Services"
        FuncSvc(["Function Service"]):::service
        StaticHost(["Static Hosting"]):::service
        ContainerSvc(["Container Service"]):::service
        DB(["NoSQL DB"]):::service
        AuthSvc(["Auth Service"]):::service
    end

    %% Flow
    CLIpkg -->|invokes| CoreAPI
    CLIBin -->|entrypoint| CoreAPI
    CoreAPI -->|load config| ConfigResolve -->|validate| ConfigValidate
    ConfigValidate -->|init lifecycle| Lifecycle -->|register hooks| Hooks
    Lifecycle -->|use manager| PluginMgr
    PluginMgr -->|"load/invoke"| AuthP
    PluginMgr -->|"load/invoke"| ContainerP
    PluginMgr -->|"load/invoke"| FunctionP
    PluginMgr -->|"load/invoke"| WebsiteP
    AuthP -->|"build assets"| BuilderCore
    ContainerP -->|"build assets"| BuilderCore
    FunctionP -->|"build assets"| BuilderCore
    WebsiteP -->|"build assets"| BuilderCore
    BuilderCore -->|bundle| NextBuilder
    BuilderCore -->|bundle| NodeBuilder
    BuilderCore -->|bundle| NuxtBuilder
    BuilderCore -->|bundle| StaticBuilder
    BuilderCore -->|invoke deploy| DeployerCore -->|optionally via SAM| SAM
    DeployerCore -->|REST API calls| FuncSvc
    StaticBuilder -->|deploy files| StaticHost
    ContainerBuilder(("Container Builder")):::plugin -->|deploy container| ContainerSvc
    DatabaseP -->|deploy schema| DB
    AuthP -->|setup| AuthSvc
    CoreAPI -->|use utils| Utils
    CoreAPI -->|log| Logger
    CoreAPI -->|error handling| ErrorCore

    %% Click Events
    click CLIpkg "https://github.com/tencent/cloudbase-framework/blob/master/package.json"
    click CLIBin "https://github.com/tencent/cloudbase-framework/blob/master/package.json"
    click CoreAPI "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/index.ts"
    click ConfigResolve "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/config/resolve-config.ts"
    click ConfigValidate "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/config/validate.ts"
    click Lifecycle "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/lifecycle/index.ts"
    click Hooks "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/hooks/index.ts"
    click PluginMgr "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/plugin-manager/index.ts"
    click BuilderCore "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/builder/index.ts"
    click DeployerCore "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/deployer/index.ts"
    click SAM "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/sam/index.ts"
    click Context "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/context/index.ts"
    click Utils "https://github.com/tencent/cloudbase-framework/tree/master/packages/framework-core/src/utils"
    click Logger "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/logger/index.ts"
    click ErrorCore "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-core/src/error.ts"
    click AuthP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-auth/src/index.ts"
    click ContainerP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-container/src/index.ts"
    click DartP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-dart/src/index.ts"
    click DatabaseP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-database/src/index.ts"
    click FunctionP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-function/src/index.ts"
    click MPP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-mp/src/index.ts"
    click NextP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-next/src/index.ts"
    click NodeP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-node/src/index.ts"
    click NuxtP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-nuxt/src/index.ts"
    click WebsiteP "https://github.com/tencent/cloudbase-framework/blob/master/packages/framework-plugin-website/src/index.ts"
    click NextBuilder "https://github.com/tencent/cloudbase-framework/blob/master/packages/cloudbase-next-builder/src/index.ts"
    click NodeBuilder "https://github.com/tencent/cloudbase-framework/blob/master/packages/cloudbase-node-builder/src/index.ts"
    click NuxtBuilder "https://github.com/tencent/cloudbase-framework/blob/master/packages/cloudbase-nuxt-builder/src/index.ts"
    click StaticBuilder "https://github.com/tencent/cloudbase-framework/blob/master/packages/cloudbase-static-builder/src/index.ts"
    click Schema "https://github.com/tencent/cloudbase-framework/blob/master/packages/cloudbaserc-json-schema/src/schema/cloudbaserc-base-schema.json"
    click SchemaTest "https://github.com/tencent/cloudbase-framework/blob/master/packages/cloudbaserc-json-schema/__tests__/cloudbaserc.json"
    click Readme "https://github.com/tencent/cloudbase-framework/blob/master/README.md"
    click Guide "https://github.com/tencent/cloudbase-framework/blob/master/CLI_GUIDE.md"
    click DocFolder "https://github.com/tencent/cloudbase-framework/tree/master/doc/"
    click Community "https://github.com/tencent/cloudbase-framework/tree/master/community/posts/"
    click BuildRunner "https://github.com/tencent/cloudbase-framework/tree/master/scripts/build-runner/"
    click CIHelper "https://github.com/tencent/cloudbase-framework/tree/master/scripts/ci-log-viewer/"
    click License "https://github.com/tencent/cloudbase-framework/blob/master/scripts/license-checker.js"
    click LinkPkg "https://github.com/tencent/cloudbase-framework/blob/master/scripts/link-packages.js"
    click Link "https://github.com/tencent/cloudbase-framework/blob/master/scripts/link.js"
    click Spawn "https://github.com/tencent/cloudbase-framework/blob/master/scripts/spawn.js"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef plugin fill:#ABEBC6,stroke:#229954,color:#196F3D
    classDef service fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef gray fill:#E5E7E9,stroke:#566573,color:#424949
```
