Skip to content

SYSTEM

Introduction

Renderflow's system model defines the major capability-bearing systems that make up the project.

Conformance

This document is authored in conformance with:

  • .github/specs/architecture/document.spec.md
  • .github/specs/architecture/foundation/system.spec.md

Purpose & Scope

This document identifies the major systems Renderflow contains, what each system owns, and how their responsibilities stay distinct.

It does not define source-code modules or implementation classes.

Definitions

  • System: a cohesive capability area with explicit responsibility.
  • Boundary: the limit of what a system owns.
  • Capability ownership: the principle that one system is the canonical home of a concern.

Renderflow System Model

1. Intent System

The Intent System owns source specifications, declared outputs, variables, transform definitions, and the normalized understanding of what work is being requested.

It answers: What is the operator asking Renderflow to do?

2. Planning System

The Planning System owns transform graphs, optimization modes, reachability, path selection, multi-target planning, and execution-plan rendering.

It answers: What paths are available, and which plan best satisfies the request?

3. Transformation System

The Transformation System owns content mutation before and during conversion, including built-in transforms, command-defined transforms, AI transforms, and plugin-backed transforms.

It answers: How can content change while preserving declared intent?

4. Execution System

The Execution System owns render strategies, DAG execution, concurrency, artifact production, and cache-aware reuse during work execution.

It answers: How is the chosen work carried out efficiently and repeatably?

5. Trust System

The Trust System owns diagnostics, dry-run behavior, dependency awareness, incremental correctness, documentation-facing explanations, and validation signals that help operators trust results.

It answers: Why should people believe what Renderflow is about to do or has already done?

6. Extension and Delivery System

The Extension and Delivery System owns plugin participation, AI provider boundary management, packaging pathways, documentation publication, CI validation, and release distribution.

It answers: How does Renderflow grow and travel without losing coherence?

System Boundaries

  • The Intent System defines requested work but does not choose paths.
  • The Planning System chooses paths but does not perform transformations.
  • The Transformation System defines executable capability but does not own final artifact policy.
  • The Execution System performs work but does not define the ontology or purpose of that work.
  • The Trust System explains and validates behavior but does not replace execution.
  • The Extension and Delivery System expands and distributes Renderflow but does not redefine the core model.

Requirements, Constraints & Guidelines

Requirements

  • Each major capability must have a clear owning system.
  • System responsibilities must support Renderflow's purpose and principles.
  • Overlap between systems must be minimized.

Constraints

  • Systems must not be defined by file layout.
  • Frameworks and crates must not replace conceptual ownership.
  • This document must not become an implementation inventory.

Guidelines

  • Prefer cohesive capability boundaries.
  • Prefer stable ownership over exhaustive detail.
  • Prefer boundaries that explain current and future growth.

Authoring Contract

Purpose

Own the major system decomposition of Renderflow.

Responsibilities

This document owns:

  • major systems,
  • capability ownership,
  • conceptual boundaries,
  • system-level relationships.

Non-Responsibilities

This document does not own:

  • architectural layer ordering,
  • detailed implementation structure,
  • design philosophy,
  • roadmap phases.

Inputs

  • PURPOSE.md
  • PRINCIPLES.md
  • FOUNDATIONS.md
  • ONTOLOGY.md

Outputs

  • ARCHITECTURE.md
  • DECISIONS.md
  • ROADMAP.md
  • implementation decomposition

AI Generation Rules

AI systems should define capability-bearing systems, not a file tree.

Validation

A contributor should be able to explain every major Renderflow capability by placing it under one primary system boundary.

Acceptance Criteria

  • Major systems are clearly defined.
  • Ownership boundaries are explicit.
  • The system model aligns with purpose, principles, and foundations.
  • Implementation details are absent.

AI Authoring Strategy

AI systems should:

  1. read purpose, principles, foundations, and ontology,
  2. group capabilities into cohesive systems,
  3. minimize overlap,
  4. define boundaries that will survive implementation change.

Rationale & Context

Renderflow already spans configuration, planning, execution, diagnostics, extensibility, and delivery. The system model prevents those concerns from being flattened into one generic "engine" and gives each concern explicit ownership.

Dependencies & External Integrations

Upstream Dependencies

  • PURPOSE.md
  • PRINCIPLES.md
  • FOUNDATIONS.md
  • ONTOLOGY.md

Downstream Dependencies

  • ARCHITECTURE.md
  • DECISIONS.md
  • ROADMAP.md
  • module and interface organization

Examples & Edge Cases

Example

Execution-plan export belongs to the Planning System because it expresses the chosen path, even though operators may view it as part of diagnostics.

Edge Case

A plugin may introduce new transformation capability, but plugin governance itself belongs to the Extension and Delivery System while the transform behavior still participates in the Transformation System.

Validation Criteria

This document is valid when new capabilities can be added without blurring which system owns them.

  • .github/specs/architecture/document.spec.md
  • .github/specs/architecture/foundation/system.spec.md