---
name: plantuml-architecture-diagram
description: Generate and refine architecture diagrams in PlantUML by preserving the logical components, responsibilities, and provided/required interfaces of a component diagram, then adding where every element lives. Use when the user asks for arquitectura, infrastructure placement, deployment, cloud/on-premise boundaries, devices, processes, containers, hosts, regions, networks, load balancers, databases, queues, protocols, ports, or TLS termination. This is a component view plus runtime location; do not reduce it to infrastructure alone.
---

# PlantUML Architecture Diagram

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

```text
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](references/conventions.md) and the shared
   [semantic visual style](references/visual-style.md).
    Apply [LANG-001 and LANG-002](references/language.md) 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.