Architecture View

Generate cross-repository architectural views by aggregating catalog-info.yaml metadata from all repositories using parallel subagents.

Purpose

Create visual architectural representations (Mermaid diagrams, markdown tables) that show how services fit together, how requests flow through gateways, how events propagate, and how services group by domain/team.

When to Use

Trigger this skill when:

• User asks to "show service dependency graph" or "map the architecture"
• User wants to understand "how services connect"
• User asks about "request flows" or "event topology"
• User wants to "group services by domain/team"
• User mentions "cross-repo architecture" or "system architecture"

Workflow

Phase 1: Discover Repositories

Find all repositories to analyze:

1. Check repos/ directory - Local cloned repositories
2. Optionally fetch from GitHub - Use gh repo list Astrabit-CPT for full list
3. Filter for active repos - Skip archived or template repos

Phase 2: Parallel Metadata Collection

Use subagents IN PARALLEL to read each repository's catalog-info.yaml:

For each repo:
  Launch subagent with: "Read catalog-info.yaml from [repo_path] and return the parsed content"

Parallel processing strategy:

• Launch 5-10 subagents simultaneously
• Collect all results
• Handle missing metadata gracefully (skip or note as missing)

Phase 3: Aggregate and Build Model

Combine all metadata into a unified model:

aggregated = {
    "components": {},  # name -> catalog info
    "dependencies": set(),  # (from, to) tuples
    "gateways": [],
    "services": [],
    "workers": [],
    "domains": {},  # domain -> [components]
    "events": {
        "producers": {},  # topic -> [producers]
        "consumers": {},  # topic -> [consumers]
    },
    "routes": [],  # gateway routes
}

Phase 4: Generate Requested View

Based on user request, generate the appropriate view:

| View | Command/Trigger | Output | |------|-----------------|--------| | Service Dependency Graph | "dependency graph", "show dependencies" | Mermaid graph | | Request Flow Maps | "request flows", "how requests flow" | Mermaid flowchart | | Event Topology | "event topology", "event map" | Mermaid graph | | Service Groupings | "group services", "services by domain" | Markdown tables | | Full Architecture | "architecture view", "full architecture" | All views combined |

View Templates

Service Dependency Graph

graph TD
    Gateway[api-gateway<br/>type: gateway] --> Auth[auth-service<br/>type: service]
    Gateway --> Users[user-service<br/>type: service]
    Gateway --> Orders[order-service<br/>type: service]
    Users --> DB[(user-db<br/>type: database)]
    Auth --> Redis[(redis<br/>type: cache)]
    Orders --> OrdersDB[(order-db<br/>type: database)]
    Orders --> Worker[order-processor<br/>type: worker]

Generation logic:

• Nodes: All components from catalog-info.yaml
• Edges: From dependsOn relationships
• Shape: Database nodes use [(name)], others use [name]
• Labels: Include name and type

Request Flow Map

flowchart LR
    Client[Client] --> Gateway[api-gateway]
    Gateway -->|/api/users/*| Users[user-service]
    Gateway -->|/api/auth/*| Auth[auth-service]
    Gateway -->|/api/orders/*| Orders[order-service]
    Users --> DB[(user-db)]
    Auth --> Redis[(redis)]

Generation logic:

• Start from gateway components (type: gateway)
• Follow routes to find downstream services
• Include route paths as edge labels
• Follow service dependencies to databases

Event Topology

graph LR
    Orders[order-service] -->|order.placed| Kafka1[Kafka: order-placed]
    Orders -->|order.cancelled| Kafka2[Kafka: order-cancelled]
    Kafka1 --> User[user-service]
    Kafka1 --> Notif[notification-service]
    Kafka2 --> User
    Worker[order-processor] -->|order.processed| Kafka3[Kafka: order-processed]
    Kafka1 --> Worker

Generation logic:

• Nodes: Services (from eventProducers) and Kafka topics (from topic field)
• Edges: Producer → Topic, Topic → Consumer
• Labels: Topic names on edges

Service Groupings

By Domain: | Domain | Services | Owner | |--------|----------|-------| | trading | order-service, trade-service, order-processor | trading-team | | platform | api-gateway, user-service, auth-service | platform-team | | shared | shared-utils, shared-types | platform-team |

By Type: | Type | Services | |------|----------| | gateway | api-gateway | | service | user-service, auth-service, order-service | | worker | order-processor, notification-worker | | library | shared-utils, shared-types |

Generation logic:

• Group by spec.domain field
• Show owner for each domain
• Count services per grouping

Scripts

aggregate-metadata.py

Collect all catalog-info.yaml files from repositories:

# Aggregate from repos directory
python skills/arch-view/scripts/aggregate-metadata.py repos/

# Output as JSON
python skills/arch-view/scripts/aggregate-metadata.py repos/ --format json

# Output as summary
python skills/arch-view/scripts/aggregate-metadata.py repos/ --summary

generate-mermaid.py

Convert aggregated metadata to Mermaid diagrams:

# Generate all views
python skills/arch-view/scripts/generate-mermaid.py aggregated.json

# Generate specific view
python skills/arch-view/scripts/generate-mermaid.py aggregated.json --view dependency
python skills/arch-view/scripts/generate-mermaid.py aggregated.json --view request-flow
python skills/arch-view/scripts/generate-mermaid.py aggregated.json --view events

Using Subagents

Launch subagents to read metadata in parallel:

For efficiency, launch multiple subagents simultaneously:

Subagent 1: "Read repos/api-gateway/catalog-info.yaml and return parsed YAML"
Subagent 2: "Read repos/user-service/catalog-info.yaml and return parsed YAML"
Subagent 3: "Read repos/order-service/catalog-info.yaml and return parsed YAML"
... (continue for all repos)

Collect results and aggregate.

Tip: Limit to 5-10 concurrent subagents to avoid overwhelming the system.

Output Format

Present results as:

1. Summary - Quick overview of what was found
2. Visual diagrams - Mermaid graphs that render in supported viewers
3. Tables - Groupings and listings
4. Missing metadata - List of repos without catalog-info.yaml

Example Output Structure

# Architecture View

## Summary
- Total repositories: 15
- Components with metadata: 12
- Missing metadata: 3
- Gateways: 1
- Services: 8
- Workers: 2
- Libraries: 1

## Service Dependency Graph
[Mermaid diagram]

## Request Flow Map
[Mermaid diagram]

## Event Topology
[Mermaid diagram]

## Service Groupings
[Markdown tables]

## Missing Metadata
The following repositories lack catalog-info.yaml:
- repo-a
- repo-b
- repo-c

Additional Resources

Reference Files

• references/view-templates.md - Mermaid templates for each view type
• references/mermaid-guide.md - Mermaid syntax reference

Scripts

• scripts/aggregate-metadata.py - Collect catalog-info.yaml from all repos
• scripts/generate-mermaid.py - Convert metadata to Mermaid diagrams