project-module-architecture

Project Module Architecture

Applicable Scenarios

• Create, update, or migrate projects
• Handle project attributes, tags, channels, and approval status
• Troubleshoot members, permissions, and project resource boundaries
• Determine the real meaning of projectId in other modules
• Handle project sharding, routing, and project-level basic configuration

Inapplicable Scenarios

• It is only the business logic of a certain pipeline, code repository, or artifact itself
• It is only ordinary permission model design and does not involve the project as a resource domain
• It is only database script design and does not involve project module semantics

Quick Guidance

1. First confirm which main line the problem belongs to:
   • Project basic mental model: see reference/1-project-foundation.md
   • Project attributes, permissions, sharding, and extension: see reference/2-project-operations.md
2. In BK-CI, what most business interfaces call projectIdis actually closer to T_PROJECT.english_name, not the UUID primary key field in the database.
3. Project is a basic module. Many problems appear to occur in other modules, but the root cause is that project attributes, project start/stop status, project boundaries, or project permissions are not aligned.
4. Whenever project fields, project attributes, or project routing logic are changed, the impact on other modules must also be considered.

High-Signal Rules

• A project is the basic boundary for BK-CI resource isolation
• Other modules depend on Project, but should not bypass it to define project semantics on their own
• Project attributes often determine subsequent pipeline, code repository, permission, and PAC behavior
• Project sharding and routing are infrastructure capabilities, not ordinary business fields

Key Pitfalls

• Confusing T_PROJECT.PROJECT_ID with the projectId in the business
• Only changing the project table without synchronously checking project attributes and downstream dependent modules
• Misjudging a project problem as a permission problem, or misjudging a permission problem as the project not existing
• Ignoring the impact of project sharding, channels, and approval status on overall behavior

Further Reading

• Project basics:reference/1-project-foundation.md
• Project attributes and sharding:reference/2-project-operations.md
• When global module collaboration is involved: also see 00-bkci-global-architecture
• When permission implementation is involved: also see auth-module-architecture