[E] AI Language Agnostic Model - RobertArtigas/DCT2CLASS_Docs GitHub Wiki

Language‑Agnostic Workflow for Generated + Handcrafted Software Systems

This document maps the structured workflow for generated + handcrafted systems to a language‑agnostic implementation model.

It applies equally to:

  • compiled and interpreted languages,
  • monoliths and microservices,
  • template‑based generators and AI‑assisted generators.

The goal is to describe what must exist, not how a specific language does it.

Overview: The Five Universal Phases

Every sustainable generated system follows five phases:

  1. Architecture Design
  2. Metadata Definition
  3. Code Generation
  4. Handcrafted Extension
  5. Testing and Integration

These phases are conceptual, not tool‑specific.

1) Design the Architecture (Language‑Agnostic)

Purpose: Decide structure before implementation.

Universal Concepts

  • System boundaries
  • Modules / services / components
  • Data ownership and responsibility
  • Interaction patterns (sync, async, events)

Typical Implementations

  • Architecture decision records (ADRs)
  • Diagrams (C4, UML, simple boxes and arrows)
  • Explicit layering or service boundaries

Applies To

  • Java, C#, Go, Rust, Python, JavaScript
  • Monoliths, modular monoliths, microservices
  • Backend, frontend, and mixed systems

Invariant

Architecture constrains generation. Generation must not invent architecture.

2) Collect and Manage Metadata (Language‑Agnostic)

Purpose: Define the system declaratively.

Universal Metadata Types

  • Data schemas (tables, entities, documents)
  • API contracts (requests, responses, events)
  • Validation rules and constraints
  • Deployment and environment metadata

Typical Implementations

  • SQL catalogs / schema introspection
  • OpenAPI / AsyncAPI
  • JSON Schema / Protobuf / Avro
  • DSLs or configuration files (YAML/JSON/TOML)

Invariants

  • Metadata exists independently of code
  • Metadata is versioned and validated
  • Multiple consumers can use the same metadata

3) Build and Run Generators (Language‑Agnostic)

Purpose: Transform metadata + architecture into code.

Universal Generator Responsibilities

  • Deterministic output
  • Idempotent regeneration
  • Clear ownership of generated files

Typical Implementations

  • Template engines (Mustache, Jinja, Handlebars)
  • Build‑time generators
  • CLI‑driven generation pipelines
  • AI‑assisted generation with pinned prompts

Invariants

  • Same inputs → same outputs
  • Generators are replaceable
  • Generated code is disposable

4) Handcraft and Extend Code (Language‑Agnostic)

Purpose: Add human intent safely.

Universal Extension Mechanisms

  • Inheritance or composition
  • Interfaces / ports / adapters
  • Hooks, callbacks, extension points
  • Partial classes or separate modules

Typical Implementations

  • Domain layers separate from generated layers
  • Explicit “do not edit” boundaries
  • Human‑owned directories or packages

Invariants

  • Handwritten code is never overwritten
  • Regeneration is always safe
  • Human intent remains authoritative

5) Test and Integrate (Language‑Agnostic)

Purpose: Validate the whole system, not just the output.

Universal Test Layers

  • Schema and contract validation
  • Generated code compilation/linting
  • Unit tests for handwritten logic
  • Integration tests across boundaries

Typical Implementations

  • CI pipelines validate regeneration
  • Diff‑based checks (generation produces no drift)
  • Automated deployment tests

Invariants

  • Generated and handwritten code are tested together
  • Regeneration is part of CI
  • Failures are traceable to source (metadata, template, or code)

Cross‑Language Mapping Table

Concept Language‑Specific Example Language‑Agnostic Equivalent
Dictionary Clarion dictionary Schema / model definition
Template Clarion / ABC templates Generator template / prompt
Embed Named embed point Extension hook / adapter
Generated file .clw Generated module
Handwritten code Embed / parent class Domain logic
Regenerate App generation Deterministic rebuild

What Must Never Change (Hard Rules)

These rules apply regardless of language:

  1. Architecture is designed, not inferred
  2. Metadata is explicit and independent
  3. Generation is deterministic
  4. Handwritten code is protected
  5. Quality is never reduced by automation

Summary

This workflow works because it separates intent from mechanics:

  • Architecture expresses intent
  • Metadata encodes intent
  • Generators automate mechanics
  • Humans write meaning

When these roles are respected, systems:

  • scale across languages,
  • survive tooling changes,
  • and remain maintainable for decades.

Closing Insight

Languages change. Tools change.
This workflow endures because it encodes responsibility, not syntax.

Code Wiki Main Repositories