Convenciones de diagramas

Todos los diagramas C4 de Octopus comparten un theme (architecture/theme/) que se publica junto con este sitio en /c4-theme/theme.json. Cualquier otro workspace Structurizr (por ejemplo el de cards) lo consume con themes https://<docs>/c4-theme/theme.json.

Modelo de tags: tres ejes ortogonales

Cada elemento lleva a lo sumo un tag por eje. Los tags son PascalCase y se escriben exactamente como en esta tabla.

Eje	Tags	Qué cambia
Layer: a qué pertenece	Kernel Service Library Tooling Demo External	el color del borde
Kind: qué es	Api Worker Poller Database Replica Outbox Ledger EventBus WebApp Cli Package Protos Identity Simulator	la forma y el icono
State: cómo leerlo hoy	Planned Optional Deprecated Generated Guarantee	borde punteado u opacidad, o el sello dorado

Reglas:

• Los sistemas van en navy sólido; el tag Octopus es para el kernel como sistema.
• Los containers y componentes tienen fondo claro; la semántica va en el borde (Layer).
• Guarantee es el único lugar donde aparece el ámbar #b45309: marca los componentes que hacen cumplir una fila de la matriz de garantías. No se usa para otra cosa.
• Generated se aplica a todo lo que escribe un generador (modules/shared, grpc/).
• Planned y Optional existen también como tags de relación.

Personas: Operator y Developer.

Grupos. Group:sdk, Group:platform, Group:modules y Group:apps para la vista de componentes de octopus-api (un grupo por capa Gradle, con esos nombres exactos); Group:Kernel, Group:Services, Group:Libraries y Group:Tooling para landscape y containers.

Relaciones. Por defecto son sólidas (gRPC, SQL). Se etiquetan Async, Optional, Planned, Deprecated y Highlight. Para vistas dinámicas de una transacción hay además Debit, Credit, Hold, Release y Capture.

Si falta un tag o un archetype, se agrega primero al theme y recién después se usa en el modelo.

Archetypes

Los tags de Layer y Kind no se escriben a mano: se aplican por construcción con los archetypes de architecture/theme/src/archetypes.dsl. Los elementos y las relaciones del modelo se crean desde un archetype, y los tags sueltos son solo de State (Planned, Optional, Deprecated, Generated, Guarantee). La única excepción es eventBus, que es Optional por definición del ADR-001. Un tipo nuevo de elemento es un archetype nuevo en el theme, antes de usarlo en el modelo.

Archetype	Base	Technology	Tags
kernelContainer	container	Kotlin / Spring Boot	Kernel
kernelComponent	component	Kotlin	Kernel
service	container	Kotlin / Spring Boot	Service
library	container	—	Library
tooling	container	—	Tooling
demo	softwareSystem	—	Demo
externalSystem	softwareSystem	—	External
kernelApi	kernelContainer	Kotlin / Spring Boot	Kernel, Api
kernelWorker	kernelContainer	Kotlin / Spring Boot	Kernel, Worker
kernelPoller	kernelContainer	Kotlin / Spring Boot	Kernel, Poller
sdkComponent	kernelComponent	Kotlin	Kernel (gradle.layer=sdk)
platformComponent	kernelComponent	Kotlin	Kernel (gradle.layer=platform)
moduleComponent	kernelComponent	Kotlin	Kernel (gradle.layer=modules)
appComponent	kernelComponent	Kotlin	Kernel (gradle.layer=apps)
postgres	container	PostgreSQL 18	Database
postgresReplica	container	PostgreSQL 18	Replica
eventBus	container	Kafka / Redpanda	EventBus, Optional
identityProvider	externalSystem	—	External, Identity
protos	library	Protobuf	Library, Protos
kotlinPackage	library	Kotlin	Library, Package
goPackage	library	Go	Library, Package
cli	tooling	Go / Cobra	Tooling, Cli
webApp	tooling	Angular / PrimeNG	Tooling, WebApp
goApi	tooling	Go	Tooling, Api
simulator	service	Go	Service, Simulator
operator	person	—	Operator
developer	person	—	Developer
grpc	->	gRPC	—
sql	->	R2DBC / JDBC	—
oidc	->	OIDC / JWT	—
event	->	event	Async
optionalEvent	--event->	—	Optional
iso8583	->	ISO 8583	—

Guía de estilo

Un elemento por tag, generado desde architecture/theme/src/examples/workspace.dsl.

Diagram: Guía de estilo: sistemas

Diagram: Guía de estilo: containers, capas y estados

Diagram: Guía de estilo: componentes