# Arch Describe

> Generate detailed architectural descriptions of IT systems from short prompts. Produces structured output with overview, components list, connections/integrations, and ASCII diagrams with annotated arrows. Use when user asks to describe, explain, or document architecture of any IT system - specific platforms (Camunda, Kafka, Kubernetes), cloud services (AWS, GCP, Azure), databases, microservices, or custom systems. Use when this capability is needed.

- Skill: `tomevault-io/arch-describe` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/arch-describe`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/arch-describe/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/arch-describe

---


# Architecture Describer

Generate structured IT architecture descriptions with ASCII diagrams.

## Output Structure

1. **Overview** - 2-3 sentences describing the system's purpose and high-level architecture
2. **Components** - Bulleted list of all components with brief descriptions
3. **Connections** - Numbered list of all integrations between components
4. **Diagram** - ASCII diagram showing components and annotated connections

## ASCII Diagram Conventions

Use box-drawing characters:

```
┌──────────────┐
│  Component   │
└──────────────┘
```

Arrow styles with annotations:

```
─────▶  unidirectional
◀────▶  bidirectional
──┬──   split/branch
──┴──   merge/join
```

Annotate arrows with protocol and purpose:

```
┌─────────┐   REST/get orders   ┌─────────┐
│ Service │────────────────────▶│   API   │
└─────────┘                     └─────────┘

┌─────────┐  gRPC/stream jobs   ┌─────────┐
│ Worker  │◀────────────────────│ Broker  │
└─────────┘                     └─────────┘
```

Vertical connections:

```
┌──────────┐
│  Source  │
└────┬─────┘
     │ JDBC/write
     ▼
┌──────────┐
│    DB    │
└──────────┘
```

## Example Output

**Prompt**: "Describe Camunda 8 architecture"

---

### Overview

Camunda 8 is a cloud-native process orchestration platform built on a distributed architecture. The core consists of Zeebe (workflow engine with brokers and gateway), operational tools (Operate, Tasklist, Optimize), and supporting infrastructure (Elasticsearch, Identity).

### Components

- **Zeebe Gateway** - Entry point for client applications, routes commands to brokers
- **Zeebe Broker Cluster** - Distributed workflow engine, processes BPMN workflows, manages state via Raft consensus
- **Elasticsearch** - Stores process data exported from brokers for querying
- **Operate** - Web UI for monitoring and troubleshooting process instances
- **Tasklist** - Web UI for human task management
- **Optimize** - Web UI for process analytics and reporting
- **Identity** - Authentication and authorization service (Keycloak-based)
- **Workers** - External applications that execute job tasks
- **Client Applications** - Applications that start process instances and interact with the platform

### Connections

1. Client Applications → Zeebe Gateway: gRPC/start process, create jobs
2. Zeebe Gateway → Zeebe Brokers: gRPC/route commands
3. Zeebe Brokers ↔ Zeebe Brokers: Raft/replication, leader election
4. Zeebe Brokers → Elasticsearch: HTTP/export process records
5. Workers ↔ Zeebe Gateway: gRPC/poll jobs, complete jobs
6. Operate → Elasticsearch: HTTP/query process data
7. Tasklist → Elasticsearch: HTTP/query tasks
8. Tasklist → Zeebe Gateway: gRPC/complete tasks
9. Optimize → Elasticsearch: HTTP/query analytics data
10. Identity → Operate, Tasklist, Optimize: OAuth2/authentication

### Diagram

```
┌───────────────────┐     gRPC/start process     ┌─────────────────┐
│ Client            │───────────────────────────▶│  Zeebe Gateway  │
│ Applications      │                            └────────┬────────┘
└───────────────────┘                                     │
                                                          │ gRPC/route
┌───────────────────┐     gRPC/poll & complete           ▼
│     Workers       │◀──────────────────────────▶┌─────────────────┐
└───────────────────┘                            │  Zeebe Broker   │
                                                 │    Cluster      │
                                                 │ ┌─────┬─────┐   │
                                                 │ │ B1 ◀─▶ B2 │   │
                                                 │ └──┬──┴──┬──┘   │
                                                 │    └──▶B3◀┘     │
                                                 │   Raft/replicate│
                                                 └────────┬────────┘
                                                          │
                                         HTTP/export      │
                                         records          ▼
┌───────────────┐                            ┌────────────────────┐
│   Identity    │──OAuth2/auth──────────────▶│   Elasticsearch    │
│  (Keycloak)   │                            └─────────┬──────────┘
└───────┬───────┘                                      │
        │                                              │ HTTP/query
        │ OAuth2/auth                                  ▼
        │                            ┌─────────────────────────────┐
        └───────────────────────────▶│  Operate  Tasklist  Optimize│
                                     └─────────────────────────────┘
```

---

## Common Architectures Reference

For common systems (Kafka, Kubernetes, Redis, etc.), see [references/architectures.md](references/architectures.md) for component lists and typical connection patterns.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/dddpaul) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->