BK-CI Global Architecture Guide
Applicable Scenarios
- A requirement spans multiple modules and it is not yet clear where to start
- You need to understand the main chain of a pipeline from trigger to execution completion
- You need to determine whether a piece of logic belongs to
Process、Dispatch、Agent、Worker or another module
- You need to choose a skill first, then go deeper into the specific implementation
Inapplicable Scenarios
- It is already clear that only the internal logic of a single module will be changed
- It is only a small change to a frontend page, database script, or some utility function
- The target module is already known and only its local conventions are needed
Quick Guidance
- First use the five-layer view to establish a sense of system position:
- User layer: Web, OpenAPI, Webhook, third-party systems
- Gateway layer: OpenResty, responsible for routing, authentication, rate limiting, and service discovery
- Microservice layer: Project, Process, Auth, Repository, Store, Dispatch, etc.
- Build machine layer: Agent is responsible for processes and scheduling, Worker is responsible for task execution
- Resource layer: MySQL, Redis, RabbitMQ, ES, file storage
- Understand the pipeline main chain in this order:
触发 -> Process 编排 -> Dispatch 分配 -> Agent 领取 -> Worker 执行 -> 状态回传
- First choose a skill according to module boundaries, then go deeper into the implementation:
- Pipeline model, execution chain, state machine:
process-module-architecture
- Permissions, RBAC, IAM:
auth-module-architecture
- Code repository, Webhook, PAC integration:
repository-module-architecture
- Store, templates, plugin publishing:
store-module-architecture
- Scheduling, build resources, BuildLess:
dispatch-module-architecture
- Build machine Agent:
agent-module-architecture
- Worker executor:
worker-module-architecture
- Backend API layering conventions:
backend-microservice-development
- API design:
api-interface-design
- Database design:
database-design
- Quickly determine issue ownership:
- "Who orchestrates and advances the pipeline state" ->
Process
- "How execution resources are allocated and how containers are started" ->
Dispatch
- "How the build machine stays resident, claims tasks, and upgrades" ->
Agent
- "How plugin tasks are executed and how logs and status are reported back" ->
Worker
- "How interfaces should be layered, named, and placed in directories" ->
backend-microservice-development
- "How tables are designed, scripts are managed, and indexes are created" ->
database-design
High-Signal Rules
- The responsibility of this skill is navigation and ownership determination, not a detailed design manual
- For single-module issues, the faster you switch to the corresponding skill, the more efficient the overall context will be
- The global system diagram and common main chain use this skill as the authoritative source and are not expanded repeatedly in each module
Key Pitfalls
- Do not treat this skill as a detailed design document. It is only responsible for navigation and main-chain determination.
- Do not repeat the global system diagram in every module skill; this skill is the source of truth for the common overview.
- For single-module changes, switch to the corresponding module skill as soon as possible to avoid wasting context on global explanations.
Further Reading
- Before single-module development, directly open the skill for the target module
- When specific implementation details are needed, do not continue expanding this file; instead, put the content back into the corresponding module skill or
reference/
