process-module-architecture

Process Module Architecture

Applicable Scenarios

• Modify pipeline creation, update, deletion, and version management
• Handle build startup, runtime state, and execution progression
• Modify engine Control, event-driven, or database persistence logic
• Troubleshoot core behavior in the pipeline main chain

Inapplicable Scenarios

• Only modifying templates, YAML conversion, or plugin definitions
• Only modifying scheduling, Agent, or Worker executors
• Only modifying the permission platform or supporting modules
• Only modifying the integration point of a peripheral service

Quick Guidance

1. This skill focuses on "how the pipeline main chain is saved, triggered, advanced, and ended".
2. Process is the core orchestration module of BK-CI. When reading it, first divide it into the entry layer, service layer, engine layer, and data layer.
3. The main entry only performs module routing. For deeper dives, go directly to the existing reference documents:
   • API layer:reference/1-api-layer.md
   • Service layer:reference/2-service-layer.md
   • Engine control:reference/3-engine-control.md
   • DAO and database:reference/4-dao-database.md
   • Event-driven:reference/5-event-driven.md
4. If you are modifying the model structure itself, also look at pipeline-model-architecture。
5. If you are modifying template or YAML input/output, also look at pipeline-template-module or yaml-pipeline-transfer。
6. If you are modifying execution resource dispatch or build machine-side execution, switch to dispatch-module-architecture、agent-module-architecture、worker-module-architecture。

High-Signal Rules

• The core of Process is not a single interface, but the combination of "pipeline data + runtime state + progression control"
• CRUD, build startup, controllers, events, and persistence must be understood as one main chain
• Changes to the main chain often affect permissions, models, templates, scheduling, and logs
• When troubleshooting, first distinguish whether it is a definition-time issue or a runtime issue

Key Pitfalls

• Looking only at a certain Resource or Service without looking at the entire main chain
• Mixing model issues, execution issues, and event issues together
• Changing runtime state transitions without synchronizing events or persistence
• Misjudging a peripheral integration point issue as a Process kernel issue

Further Reading

• API layer:reference/1-api-layer.md
• Service layer:reference/2-service-layer.md
• Engine control:reference/3-engine-control.md
• DAO and database:reference/4-dao-database.md
• Event-driven:reference/5-event-driven.md
• If you are modifying the pipeline model: also look at pipeline-model-architecture