Plantuml architecture diagram

PlantUML Architecture Diagram

Start from the same logical content as a component diagram, then add the runtime location of every element.

Architecture diagram
  = logical components and interfaces
  + execution/deployment containment
  + infrastructure and network channels

Boundary

Include:

• the same applications, modules, services, adapters, repositories, logical data dependencies, external systems, responsibilities, and interfaces that belong in the corresponding component diagram;
• client devices and external platforms;
• cloud/on-premise boundaries, accounts, regions, networks, and trust zones when known;
• nodes, hosts, containers, runtime processes, deployed artifacts;
• databases, queues, storage, gateways, and load balancers;
• network channels, protocols, ports, and TLS termination when known.

Exclude:

• internal classes, methods, domain fields, and source packages;
• temporal message ordering and database entity cardinalities.

Workflow

1. Build or reuse the logical component inventory first.
2. Preserve component names, responsibilities, aliases, system boundaries, and provided/required interfaces. Expand external ingress connectors through gateways instead of duplicating logical and deployment paths.
3. Build a placement map: logical component -> runtime location.
4. Nest every component inside a square-cornered rectangular location container labeled by kind (<<device>>, <<process>>, <<container>>, <<node>>, or <<environment>>). Mark placement as unknown when absent.
5. Add infrastructure elements required to explain that placement without replacing the logical components. Preserve every explicitly named deployment service relevant to the selected scope.
6. Start ingress at the named frontend/channel locations used by the user. Do not insert a generic Internet location when those entry points are known.
7. Keep external systems outside the owned infrastructure boundary.
8. Preserve assembly connectors for internal functional contracts. For an external ingress routed through a gateway, replace the direct frontend-to- adapter connector with one continuous frontend-to-gateway-to-adapter path. Add network/process binding details only when known.
9. Show public and internal connectors separately when a gateway terminates TLS.
10. Apply conventions.md and the shared semantic visual style. Apply LANG-001 and LANG-002 to every user-visible label and response field.
11. Render and inspect placement, nesting, crossings, and label readability.
12. Return one @startuml ... @enduml block plus assumptions and unknowns.

Hard rules

• Do not remove a logical component or interface merely because infrastructure is being added.
• Generate explanatory content in Spanish. Preserve official names, protocols, identifiers, and the controlled technical vocabulary allowed by LANG-002.
• When named frontends exist, show users entering through them and route their deployment channels toward the ingress; do not originate traffic at a generic Internet box.
• Draw one ingress path per channel. Do not show both a direct frontend-to-adapter connector and a frontend-to-gateway-to-adapter path.
• Do not omit an explicitly named cloud, external platform, gateway, runtime, database, search service, model provider, queue, storage service, or scheduler that participates in the selected architecture scope.
• Show where every primary runtime component lives; flag unknown placement.
• Do not flatten software and infrastructure into peers when containment is known.
• Do not infer a region, subnet, port, TLS, replicas, or container platform.
• HTTPS terminates at a specific runtime element; do not imply end-to-end TLS.
• Represent a known API, SDK, port, or HTTPS contract with a UML interface connector, placing the interface symbol against the provider. Keep generic arrows for event publication and asynchronous delivery.
• Name functional interfaces before their technical binding, as in the component diagram.
• Draw every location boundary as a flat, square-cornered rectangle container. Do not use PlantUML cloud, node, frame, or other decorative shapes for places.
• Express location kind with a stereotype such as <<device>>, <<runtime>>, <<container>>, <<network>>, or <<environment>>.
• Elements with established non-location semantics, such as database, queue, storage, and artifact, may retain their notation inside a rectangular location boundary.
• Preserve each logical component's semantic color from the component diagram; add a light-blue location background without recoloring nested components.
• Use unique aliases and no remote includes.

When user feedback is reusable, update references/conventions.md; otherwise keep the decision local to the diagram.