Architecture That Becomes Code

A working architecture, not a second description

Service Architect models meaningful business stages, data contracts and interactions. Generated wiring turns that composition into executable code; user-owned business functions implement the stages. Architectural changes belong in the model and are carried into the service through generation and the normal regeneration workflow.

The goal is not to generate every line of application code. It is to reduce the context needed to understand a system, make architectural changes explicit and simplify their review. Specifications can explain what a stage should do and why; code implements its behavior.

Model business decisions, not source-code syntax

Expose a stage when it is useful to discuss, change, reuse or observe it separately. A function call, condition, loop, conversion or external request in the source does not automatically need its own node. One node may represent a simple operation or a complete business stage.

For example, two parallel computations followed by combining their results can be modeled as separate stages when their composition is architecturally important. If they are internal details of one business operation, they can remain inside a single function. Both choices are valid.

Likewise, publishing a log or recording statistics can remain part of a business stage. Expose it separately when that boundary is useful for the architecture, not merely because the implementation calls Kafka, a database or another service.

Reveal detail where it helps

Use pipelines and components to navigate meaningful parts of the system. Create small reusable substreams when a flow deserves its own model, and call them from business functions without expanding their internals into every caller pipeline.

An external call may remain inside a function, appear explicitly in the main pipeline or belong to a substream. The developer or architect chooses which view communicates the intended design. See SubStream for its execution and result-collection contract.

What correspondence with code means

Generated wiring implements the connections and contracts described in the model. This is a guarantee about the modeled composition, not a claim that the graph automatically lists every action inside user-written code.

Business implementations remain ordinary code and can call helpers, external services and substreams. Service Architect does not require every such action to become a graph node. The completeness of the model and its level of abstraction are the responsibility of the developer and architect.

Keep architectural wiring changes in the model and implementation changes in user-owned files. Follow safe regeneration when applying a new generated composition; preserving business code does not remove the need to adapt it to changed contracts.

Give people and agents architectural context

The graph provides a compact view of stages, dependencies and contracts to consider when changing functionality. Agree on the intended architectural change, review its model diff, then implement the affected business behavior in code.

Descriptions and specifications complement the graph; they do not need to duplicate its wiring. This context supports engineering decisions without claiming that the tool can enforce the completeness of all user-written behavior.

Next steps

Choose a meaningful business boundary -> model its contracts and composition -> generate or regenerate -> implement business behavior -> review the architectural and code changes

Related documentation