v0.1.0 Architecture and Design Review Baseline

1. Objective¶

Define one implementation-ready baseline for devflow so we can:

Agree architecture boundaries.
Lock design details and non-goals.
Run a review gate before implementation starts.

This document consolidates the existing brainstorm and decision docs into one practical plan.

2. Scope and Non-Goals¶

In scope for v0.1.0:

Standalone devflow CLI (devflow, alias dwf).
Canonical command graph and deterministic execution model.
Rust-first extension with Node baseline extension.
Container and cache strategy for local and CI parity.
GitHub Actions rendering and required-check contracts.

Out of scope for v0.1.0:

Full multi-format serialization matrix for all paths.
Broad plugin marketplace/runtime distribution.
Advanced multi-provider CI backends beyond GitHub Actions.

3. Architecture Overview¶

Architecture constraints:

devflow-core is fundamentally stack-agnostic. It coordinates executors but has zero knowledge of toolchains.
devflow-cli is also stack-agnostic. It blindly maps arguments and volume mounts to container/host engines without interpreting them.
Stack-specific logic lives strictly inside the devflow-ext-* extensions (e.g., .cargo paths, or cargo nextest aliases).
CI YAML orchestrates only; command semantics stay in devflow.

4. Workspace Structure (Target)¶

devflow/
  Cargo.toml
  crates/
    devflow-core/
    devflow-cli/
    devflow-policy/
    devflow-gh/
    devflow-ext-rust/
    devflow-ext-node/
  examples/
    rust-lib/
    node-ts/
  docs/

Ownership boundaries:

devflow-core: task graph, execution engine, cache key coordination.
devflow-cli: UX, argument parsing, command dispatch.
devflow-policy: gate profiles, required check contracts.
devflow-gh: workflow generation and validation.
devflow-ext-*: command-to-toolchain translation.

5. Canonical Command Contract¶

Command hierarchy for developer experience¶

Based on common workflows across Rust, Node, Python, JVM, and polyglot repos, commands work best when split into two levels:

Primary commands: stable verbs developers run daily.
Secondary commands: scoped variants selected by policy, profile, or explicit command target.

First-principles rules used:

Keep top-level verbs small and stable.
Make mutating vs non-mutating behavior explicit (for example fmt:fix vs fmt:check).
Push environment-specific behavior to selectors, not new top-level commands.
Model policy gates as composition (check:*), not as a separate legacy workflow command.

Primary commands (v0.1.0 baseline)¶

Primary command	Purpose	Typical effect
`setup`	Prepare local/CI prerequisites.	Installs/syncs toolchains, dependencies, and optional container prerequisites.
`fmt`	Format source according to project rules.	Uses selectors such as `fmt:check` (read-only) and `fmt:fix` (mutating).
`lint`	Run static and policy checks.	Reports code quality and policy violations.
`build`	Compile/package artifacts.	Produces build outputs for current profile.
`test`	Run automated tests.	Executes selected test suites (`test:unit`, `test:integration`, etc.).
`package`	Assemble distributable outputs.	Produces artifacts/images/bundles and metadata.
`check`	Execute policy-defined non-mutating gate.	Composes selectors for contexts like `check:pr`, `check:main`, `check:release`.
`release`	Execute release orchestration steps.	Produces release candidates, publish steps, and release metadata.
`ci`	Manage CI contract generation and validation.	Handles selectors such as `ci:generate`, `ci:check`, and `ci:plan`.

Secondary command families¶

setup: setup:toolchain, setup:deps, setup:container, setup:doctor
fmt: fmt:check, fmt:fix
lint: lint:static, lint:security, lint:policy, lint:fix
build: build:debug, build:release
test: test:unit, test:integration, test:contract, test:e2e, test:smoke, test:load
package: package:artifact, package:image, package:sbom
check: check:pr, check:main, check:release
release: release:candidate, release:publish, release:notes
ci: ci:generate, ci:check, ci:plan

Secondary commands may be exposed as:

explicit subcommands (for example dwf test unit mapped to test:unit), or
profile aliases in config (for example targets.pr = ["fmt:check", "lint:static", "build:debug", "test:unit", "test:integration"]).

Command behavior rules¶

Same command names across stacks.
Primary commands are contract-stable; secondary commands are extension-capability dependent.
Extension maps canonical commands and secondary variants to stack-native operations.
check is policy-driven composition of primary and secondary commands.

Alternative considered¶

Alternative: many narrow top-level commands (unit-test, integration-test, security-scan, package, release-check). Decision: reject for v0.1.0 because it increases cognitive load and weakens cross-stack portability.

6. Configuration Contract (`devflow.toml`)¶

Minimum schema for v0.1.0:

[project]
name = "example"
stack = ["rust"]

[container]
image = "ghcr.io/org/repo-ci"
fingerprint_inputs = ["Dockerfile", "Makefile", "src-scripts/**", "rust-toolchain.toml"]

[cache]
root = ".cache/devflow"
strategy = "layered"

[targets]
pr = ["fmt:check", "lint:static", "build:debug", "test:unit", "test:integration"]
main = ["fmt:check", "lint:static", "build:release", "test:unit", "test:integration", "test:smoke"]
staging = ["fmt:check", "lint:static", "build:release", "test:unit", "test:integration", "test:smoke", "package:artifact"]

Rules:

Unknown keys fail validation.
Target profiles are dynamic map keys (for example pr, main, develop, staging, hotfix).
Missing required fields fail fast with actionable diagnostics.
Defaults exist for local bootstrap where safe.

7. Execution and Runtime Design¶

Execution model:

Load devflow.toml.
Resolve stack extensions.
Build command DAG.
Select runtime profile (container, host, or auto).
Resolve execution identity (container fingerprint or host toolchain fingerprint).
Resolve and restore cache layers.
Execute task graph with deterministic ordering.
Emit check status and artifacts.

Runtime profile policy:

container: default for CI and recommended for reproducibility. The executor translates generic volumes and commands into a seamless container instance proxy.
host: allowed when projects explicitly opt out of container-first execution.
auto: use container when available, otherwise host with compatibility checks.

Determinism & Orchestration constraints:

Engine Determinism: The container profile requires explicit configuration (engine="docker" or "podman"). If requested and missing from the host $PATH, execution must fail-fast instead of guessing.
Execution identity must include all declared fingerprint inputs and runtime profile.
Cache keys must include os, arch, toolchain lock dimensions.
Correctness must not depend on cache hits.
Container Lifecycle Optimization: CI environments should warm up caches during a baseline build job. Subsequent parallel verify jobs (lint, fmt, test) MUST restore the warmed cache as read-only and execute inside the identical fingerprinted image. To prevent overwhelming initialization overhead, sequential validations should be grouped within a single container spin-up where computationally appropriate.

8. Container and Cache Design¶

Deep Dive: For a dedicated exploration of container debugging, engine determinism, and exact stack-agnostic volume mappings, refer to the Container and Cache Execution Design document.

Canonical cache root:

DWF_CACHE_ROOT (default .cache/devflow)
Extensions dictate what paths are mapped to this host root generically (e.g., Rust demands .cargo/registry, Node demands ~/.npm).
Subdirectories inside the root:
- registry/
- git/
- sccache/
- target-ci/
- image-tar/
- buildx/

Policy:

Project-scoped cache by default.
Unified caching architecture: Identical host roots and volume mapping logic applies regardless of whether the profile is host or container.
Treat cache as optimization only.
Implement robust devflow cache prune workflows to prevent unbounded local/CI disk growth. Validate image invalidation aggressively upon fingerprint hash drifts.

9. CI Design Contract (GitHub Actions)¶

Job topology:

prep: fingerprint resolution and image selection.
build: compile baseline once in CI container.
fmt, lint, test-unit, test-integration, test-smoke (optional): parallel check jobs with clear status visibility.

CI contract:

CI uses dwf/Make entrypoints only.
No business logic in workflow YAML.
Required checks and branch policy generated from config.

10. Extension System Design¶

Extension API requirements:

Implement the Extension trait (name, capabilities, build_action).
Map canonical commands to executable executable definitions (ExecutionAction).
Decouple from core logic via dynamic registration in the ExtensionRegistry.

Extension discovery model¶

v0.1.0 supports two discovery sources:

Built-in extensions linked with the binary.
Local project extensions declared by path in config.

Post-v0.1.0 registry support (planned):

named extension source (registry = "ghcr|git|custom")
signed metadata and integrity checks
registry index pinning for reproducibility

Extension declaration (proposed)¶

[extensions.rust]
source = "builtin"
version = "^0.1"

[extensions.node]
source = "builtin"
version = "^0.1"

[extensions.custom_lint]
source = "path"
path = "./tools/devflow-ext-custom-lint"
version = "0.1.0"

Versioning and compatibility checks¶

Extension API has an explicit api_version (for example 1).
Core checks compatibility before loading:
- API compatibility: extension api_version == core.api_version
- semantic version policy: extension version satisfies configured range
- capability contract: required capabilities exist for selected command/profile
Incompatible extension behavior:
- hard fail for required extensions
- warning + skip for optional extensions

Extension loading lifecycle¶

Discover configured extensions.
Resolve versions against lock/constraints.
Validate checksums/signatures (when source supports it).
Run compatibility checks.
Build command capability map.
Load execution adapter and run health probe.
Register into command dispatcher.

Compatibility lock file (proposed)¶

devflow.lock captures:

resolved extension versions
source and integrity digest
resolved capability map
runtime profile constraints

v0.1.0 extension sequence:

devflow-ext-rust (first class).
devflow-ext-node (baseline parity).

Deferred:

remote registry distribution and install workflows.

11. Phase-Gated Delivery Plan¶

Phase A0: governance and ADRs. Phase A1: core engine + command graph + container/cache contract. Phase A2: extension API with Rust and Node support. Phase A3: distribution and docs.

Mandatory phase gates:

Quality gate: fmt:check, lint:static, build:debug/release, test:unit, test:integration (and test:smoke where required).
Architecture gate: command contract stability, extension API checks, CI/local parity audit.

12. Design Review Findings¶

Key strengths:

Clear separation between core orchestration and stack extensions.
Stable command surface for developers.
Deterministic CI/local model with explicit cache contracts.

Key risks:

Over-abstraction too early in extension APIs.
Fingerprint input drift between code and docs.
Policy/YAML divergence if rendering contract is weakly enforced.

Required mitigations:

Keep v0.1.0 API minimal and measured.
Add fingerprint conformance test.
Add CI rendering snapshot tests and policy validation checks.

13. Review Checklist (Pre-Implementation Gate)¶

Architecture:

Core crate has no stack-specific logic.
Extension API is minimal and documented.
Command contract is finalized and versioned.

Runtime:

Fingerprint inputs are single-sourced and test-covered.
Cache key dimensions are explicit and documented.
Container fallback behavior is defined.

CI/Policy:

Workflow render output is deterministic.
Required checks align with target profiles.
YAML contains orchestration only.

Developer UX:

Error messages include clear next actions.
Local command names exactly match CI targets.
dwf check behavior is documented and reproducible.
Primary and secondary command semantics are documented.

Extensions:

Extension discovery sources are explicitly configured.
Compatibility checks are enforced before execution.
Required extension failures are deterministic and actionable.

14. Decisions to Confirm Before Implementation¶

Cache env var name: DEVFLOW_CACHE_ROOT.
PR gate defaults: keep test:smoke required in PR or move to main only.
Runtime profile default: container for all projects, or auto with host fallback by default.
Node extension scope in v0.1.0: baseline (fmt/lint/test/build) or full parity including test:smoke.
Extension discovery scope in v0.1.0: built-in only, or built-in + local-path extensions.
Workflow ownership: generated files committed to repo or generated on-demand in CI.

15. Implementation Start Condition¶

Implementation begins only when section 14 decisions are confirmed and section 13 checklist is approved.