00-bkci-global-architecture_skill

Overview

This skill describes the global architecture of BK-CI, a pipeline-centered continuous integration platform. It presents a panoramic view of modules, execution flow, data flows, and core concepts to help readers quickly grasp how components collaborate. Use it as the primary reference when you need a system-wide mental model before diving into module-level details.

How this skill works

The document outlines a five-layer system: User, Gateway, Microservice, Build Machine, and Resource layers, and maps core modules (Process, Dispatch, Worker, Agent, Store, Auth, etc.) to responsibilities. It traces the full pipeline execution lifecycle from trigger to build end, explains responsibility-chain scheduling (Stage/Container/Task), and details Worker/Agent interactions and event-driven non-blocking coordination. Key code entry points and database task patterns are highlighted to aid cross-module development and debugging.

When to use it

• When you need an overall system view before starting cross-module development.
• When tracing complex runtime behavior across services and build machines.
• When planning architecture changes, refactors, or new pipeline features.
• When deciding which module should own a new capability (auth, dispatch, store, etc.).
• When onboarding engineers to BK-CI or preparing operational runbooks.

Best practices

• Start with the global flow: trigger → engine → dispatch → agent → worker → status return.
• Follow the responsibility-chain pattern for stage/container control to keep scheduling predictable.
• Design new features to fit the existing layer responsibilities (microservice vs build-machine).
• Prefer event-driven, non-blocking interactions for cross-service coordination and scalability.
• Use the documented key entry points and APIs (claimTask, completeTask, jobStarted) for Worker integration.

Example use cases

• Implementing a new pipeline plugin that requires Worker runtime and Store registration.
• Changing dispatch strategy to optimize build machine allocation and quota management.
• Adding an OpenAPI-driven remote trigger integration for third-party CI/CD automation.
• Investigating a failed pipeline by tracing task status from Worker back to PipelineBuildFacadeService.
• Designing RBAC changes that impact pipeline triggers and execution permissions.