Architecture as Code with Python and a Visual Designer

Edit a typed architecture model, validate it and exchange the same topology with the visual designer without maintaining competing sources of truth.

Describe architectural objects instead of application behavior

The Python DSL declares services, streams, types, endpoints and their ownership. It is an authoring language for a topology that can generate multiple runtime languages. Keep runtime business logic in the generated service extension points.

Start with the DSL installation instructions and the canonical modular example in sa-python-dsl.

Inspect and validate before generating

After installing the package, run the CLI from its repository root against examples/processorder. Validation errors describe unresolved references, invalid contracts or unsupported combinations; fix the model rather than editing generated YAML by hand.

sa-dsl inspect --project examples/processorder --format json
sa-dsl validate --project examples/processorder --format json
sa-dsl export --project examples/processorder --format json

Understand the Python, YAML and canvas boundary

Canonical YAML is an interchange format. Import can reconstruct typed Python architecture, but cannot recover arbitrary original comments, helper functions or file organization. The guarantee concerns model semantics, not identical source formatting.

The browser workspace supports modular Python authoring, and Apply and merge conflicts explains how graph and Python revisions are reconciled.

Generate a project through the authenticated API

Create a revocable API key as described in authentication. Use the generation client to validate the response and download the archive. Keep credentials out of topology files and Git.

sa-dsl generate --project examples/processorder --format json

Next steps

Typed Python → validate → canonical YAML → designer / generation API → native service code