# DDC — Dievilz Deploy Control
## Technical Summary for Implementation by LLMs
---
## 1. Project Purpose
**DDC (Dievilz Deploy Control)** is a **CI/CD action executor** designed to replace complex shell scripts, ad-hoc deployers, and CI YAML logic with a **single, deterministic, policy-driven binary**.
DDC is intended to be used from:
- GitLab CI
- GitHub Actions
- Jenkins
- Any CI/CD system capable of running a binary
DDC is **not a CI system** and **not a workflow engine**.
It is a **deployment control tool**.
---
## 2. Design Philosophy
### 2.1 Software Simplicity
- Prefer explicit control flow over abstraction
- Avoid DSLs, reflection, and dynamic configuration
- Favor readability and debuggability over cleverness
- Every decision must be traceable in logs and results
### 2.2 Completeness in Features
- Must handle unreliable infrastructure
- Partial failures are expected and supported
- Fallback, retries, and validation are first-class concepts
- The system must be useful in real production environments
### 2.3 Best-Effort Simplicity
> When simplicity and completeness conflict, prefer completeness,
> but implement it in the simplest explicit way possible.
This principle governs all design decisions in DDC.
---
## 3. What DDC Is and Is Not
### DDC IS
- A single executable
- Action-based
- Policy-driven
- CI vendor agnostic
- Deterministic and reproducible
- Explicit about success and failure
### DDC IS NOT
- A workflow engine
- A CI replacement
- A YAML or JSON DSL interpreter
- An orchestrator
- A magic automation tool
CI systems call DDC.
DDC performs actions.
---
## 4. Core Conceptual Model
DDC is built around four explicit concepts.
---
### 4.1 Action
An **Action** represents a high-level operational intent.
Examples:
- `publish-image`
- `deploy-compose`
- `transfer-artifacts`
- `validate-env`
- `discover-target`
An Action:
- Declares its inputs
- Declares required capabilities
- Executes deterministically
- Produces a structured result
- Does not know about CI systems
---
### 4.2 Capability
A **Capability** is a concrete resource used by an action.
Examples:
- Docker registry
- SSH host
- Local Docker daemon
- Remote Docker daemon
- Filesystem path
Capabilities can be:
- Available
- Unavailable
- Degraded
Capability detection is explicit and cached per execution.
---
### 4.3 Policy
A **Policy** defines how an action uses its capabilities.
Policy controls:
- Minimum number of successful executions
- Priority order of capabilities
- Fail-fast vs best-effort behavior
- Retry and fallback rules
Policy is **data**, not control flow.
---
### 4.4 Executor
The **Executor** is the DDC engine.
Responsibilities:
- Resolve capabilities
- Apply policy
- Execute the action
- Track successes and failures
- Produce logs and artifacts
- Exit deterministically
---
## 5. Unifying Existing CI/CD Problems
DDC intentionally unifies previously separate scripts and jobs.
### Image Publishing
- Action: `publish-image`
- Capabilities: Docker registries
- Policy: `min_success >= 1`
- Result: List of published image references
### Docker Compose Deployment
- Action: `deploy-compose`
- Capabilities: SSH targets
- Policy: Exactly one successful deployment
- Result: Deployment metadata
### Artifact Transfer
- Action: `transfer-artifacts`
- Capabilities: SCP endpoints
- Policy: All transfers must succeed
- Result: Transfer report
### Environment Validation
- Action: `validate-env`
- Capabilities: Filesystem, network, credentials
- Policy: Fail fast
- Result: Validation summary
---
## 6. Execution Model
### 6.1 Binary Model
- Single binary: `ddc`
- Invoked once per CI job
- Stateless execution
- No background services
---
### 6.2 Invocation Pattern
Examples:
- `ddc run publish-image`
- `ddc run deploy-compose`
- `ddc run transfer-artifacts`
- `ddc validate env`
Actions are explicit commands, not scripts.
---
## 7. Inputs and Outputs
### 7.1 Inputs
- Environment variables
- CLI flags
- Optional minimal configuration file
No complex configuration languages.
---
### 7.2 Outputs
1. **Exit Code**
- `0` → Success according to policy
- non-zero → Failure
2. **Human-readable Logs**
- Phase-based
- Concise
- Explicit decisions
3. **Machine-readable Result File**
- JSON format
- Always generated
- Contains:
- Action name
- Capabilities evaluated
- Successes and failures
- Final decision and reason
---
## 8. Error Handling Rules
- Invalid configuration → immediate failure
- Capability detection failures → handled by policy
- Action execution failures → recorded explicitly
- No silent ignores
- No implicit retries
Every failure must be visible and accounted for.
---
## 9. Logging Philosophy
Logs must answer:
- What action ran?
- What capabilities were evaluated?
- Why was a decision made?
- Why did the action succeed or fail?
Logs are for humans under pressure, not decoration.
---
## 10. Language Considerations
### Go (Preferred Initial Implementation)
- Simple and explicit
- Strong standard library
- Easy CI integration
- Fast iteration
### Zig (Future Implementation)
- Explicit memory and error handling
- Long-term infra tooling fit
- Implementation must follow the same model
---
## 11. Non-Goals
DDC explicitly does not attempt to provide:
- Workflow graphs
- CI pipeline definitions
- Plugin systems
- Runtime scripting
- Configuration DSLs
If these are ever added, they must not compromise simplicity.
---
## 12. Success Criteria
DDC is successful if:
- CI YAML becomes trivial glue
- All fallback logic lives inside DDC
- Shell deploy scripts can be removed
- Behavior is predictable under failure
- Results are auditable and machine-readable
---
## 13. Final Statement
**DDC (Dievilz Deploy Control)** exists to impose discipline on CI/CD deployment without adding unnecessary abstraction.
It embodies **Best-Effort Simplicity**:
> As simple as possible.
> As complete as necessary.
> No hidden behavior.
---
**End of Technical Summary**