dispatch-module-architecture_skill

Overview

This skill is a practical architecture guide for implementing a build dispatch module. It documents submodule layout, dispatch types (third-party agents, Docker, Kubernetes), core data models, quota and queue management, and integration points to help teams design or extend scheduling functionality.

How this skill works

The guide inspects the dispatch module layers: API, business services, DAO, listeners, and agent endpoints. It explains the dispatch lifecycle — receiving pipeline requests, quota checks, agent selection, creating dispatch records, notifying agents, and handling task completion and quota release. It also details database tables, enums, and service responsibilities for concrete implementation.

When to use it

• Designing or extending a build scheduler for CI/CD pipelines
• Adding a new execution type (custom agent, VM, serverless)
• Implementing quota, queueing or load‑balanced agent selection
• Integrating Docker or Kubernetes-based build runners
• Auditing or documenting dispatch-related services and DB schema

Best practices

• Keep dispatch logic layered: listeners -> service -> DAO to simplify testing and tracing
• Enforce quota checks at dispatch time and release quota on task completion or failure
• Use environment ID, agent health and load metrics for fair agent selection
• Persist dispatch records and queue state to enable recovery and auditing
• Provide clear REST resources for agent claim and finish flows and validate agent identity

Example use cases

• Implement a ThirdPartyDispatchService to route jobs to private build machines with per-project quotas
• Add a Kubernetes scheduler module that creates Pod-based build executors and records container IDs
• Create a Docker dispatch flow for ephemeral container-based builds with DockerIP and CONTAINER_ID tracking
• Introduce a new VM type by extending JobQuotaVmType, adding quota rows and service implementation
• Build an operator UI to adjust project/system quotas via OpJobQuotaProjectResource and OpJobQuotaSystemResource