---
name: reversa-arquitetura-3d
description: >
  Creates interactive 3D architecture visualizations of software using Three.js, generating
  standalone HTML with camera-navigable scenes. Use this skill whenever the user asks to
  visualize architecture, modules, dependencies, layers, or call hierarchies in 3D. Should
  be activated when the user mentions terms such as "code city", "3D architecture",
  "dependency graph 3D", "module map 3D", "layer stack 3D", "call graph 3D",
  "architecture tour", "visualize software in 3D", "Three.js" in the context of software,
  or asks to explore the structure of a system with a 3D camera. Works with a module JSON
  (name, folder, LOC, complexity) and a dependency JSON (directed graph). Always generates
  a complete standalone HTML. When run by the Reversa Docs Team, uses Three.js served
  locally from assets/vendor/ (offline-first).
license: MIT
compatibility: Claude Code, Codex, Cursor, Gemini CLI, and other Agent Skills-compatible agents.
metadata:
  author: pnocera
  version: "1.0.0"
  framework: reversa
  team: shared-skills
  role: 3d-renderer
---

# 3D Architecture

Creates 3D visualizations of **software architecture** using Three.js. Always generates **standalone HTML** (single file, self-contained) with an interactive 3D scene, camera controls (mouse, touch, keyboard), a parameter sidebar, and a button to export the viewport as a PNG.

The skill covers five established visual modes in software visualization, each with a dedicated reference in `references/`:

| Mode | When to use | Reference |
|------|-------------|-----------|
| **Code City** | Overview of the size/complexity of each file, "code city" pattern | `references/CODE_CITY.md` |
| **Dependency Graph 3D** | Dependency graph with repulsive force, nodes in 3D | `references/DEPENDENCY_GRAPH_3D.md` |
| **Layer Stack** | Architectural layers (UI / Domain / Infra) stacked with flow arrows | `references/LAYER_STACK.md` |
| **Call Graph 3D** | Depth-explorable call tree | `references/CALL_GRAPH_3D.md` |
| **Architecture Tour** | Animated camera traversing the scene with narrative overlay | `references/ARCH_TOUR.md` |

Shared Three.js patterns, lighting, controls, and performance live in `references/THREE_PATTERNS.md`. Error scenarios and handling in `references/ERRORS.md`.

## Workflow

### 1. Receive the data

Data can come from:

- **Inline JSON**: user provides `modules.json` (list of modules) and/or `deps.json` (dependency graph).
- **File path**: user points to JSONs in `.reversa/documentation/assets/data/` (generated by the `/reversa-documentation` agent).
- **Requested from user**: if the skill is invoked without data, ask for a path or request inline paste.

**Expected schema for `modules.json`**:

```json
[
  {
    "name": "src/auth/login.ts",
    "folder": "src/auth",
    "loc": 142,
    "complexity": 8,
    "type": "code"
  }
]
```

**Expected schema for `deps.json`** (directed):

```json
{
  "nodes": [{ "id": "src/auth/login.ts" }, { "id": "src/auth/jwt.ts" }],
  "edges": [{ "from": "src/auth/login.ts", "to": "src/auth/jwt.ts", "weight": 1 }]
}
```

### 2. Choose the mode

If the user specified the mode, use that one. If not, **suggest 2 or 3 options** based on the data:

| Data type | Recommended modes |
|-----------|-------------------|
| `modules.json` with LOC + complexity | Code City (default), Layer Stack if there are clear folders/layers |
| `deps.json` with many edges | Dependency Graph 3D, Code City coloring hot path |
| Execution trace or call graph | Call Graph 3D |
| Explicit presentation request | Architecture Tour combining two of the above |

When the number of nodes exceeds **500**, apply **folder grouping** automatically and notify the user (record the decision in the footer of the generated HTML).

### 3. Generate the code

Consult `references/THREE_PATTERNS.md` for base setup (renderer, scene, camera, lighting, OrbitControls). Consult the specific reference for the chosen mode for the layout algorithm and materials.

**Fundamental rules**:

1. **Standalone HTML**: single `.html` file with everything embedded (CSS, JS, data inline in `<script id="data">`). When run by the Reversa Docs Team, data comes from `window.RV_DATA.modules` and `window.RV_DATA.deps` (loaded by `assets/js/data.js` which the Publisher generates) and the `<script id="data">` is empty or absent. Final pages **never** call `fetch()` for local files (breaks via `file://`).
2. **Local Three.js**: use `<script src="assets/vendor/three.min.js"></script>` pointing to the file downloaded by the Publisher (version pinned in `agents/reversa-docs-publisher/references/vendor-pins.yaml`, currently `three@0.147.0` IIFE). In isolated invocation outside the Docs team, accept CDN as fallback (`https://unpkg.com/three@0.147.0/build/three.min.js`), but **never** mix versions.
3. **Local OrbitControls**: use `<script src="assets/vendor/OrbitControls.js"></script>` (also IIFE, compatible with `three@0.147`). Do not use `examples/jsm/...` until the skill migrates to importmap + ESM.
4. **Renderer**: WebGLRenderer with antialiasing, device pixelRatio.
5. **Lighting**: HemisphereLight + DirectionalLight with soft shadows. For Code City, extra AmbientLight to fill.
6. **Camera**: PerspectiveCamera, initial position looking at the center of the scene from above and slightly angled. Distance derived from scene size.
7. **Performance**: use `InstancedMesh` when there are more than 200 elements of the same type. Maximum limit of 5,000 buildings in Code City without grouping.
8. **Responsiveness**: resize handler resizes the renderer and adjusts the camera's aspect ratio.
9. **Sidebar**: right side, slider/checkbox/button controls in vertical layout. Each control has a stable ID for `localStorage`.
10. **Export PNG**: button captures the canvas via `renderer.domElement.toBlob()`.

### 4. Structure of the generated HTML

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>3D Architecture | <!-- PROJECT_NAME --></title>
    <script src="assets/vendor/three.min.js"></script>
    <script src="assets/vendor/OrbitControls.js"></script>
    <script src="assets/js/data.js"></script>
    <style>
        body { margin: 0; overflow: hidden; font-family: system-ui, sans-serif; }
        #scene { position: fixed; inset: 0; }
        #sidebar { position: fixed; top: 0; right: 0; width: 280px; height: 100vh; padding: 16px; background: rgba(15,15,20,0.85); color: #eaeaea; overflow-y: auto; }
        #loader { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; font-size: 18px; background: #0a0a10; color: #eaeaea; }
        /* Reversa style: variants derived from data-style on <body> via external CSS from the agent */
    </style>
</head>
<body data-style="exploratory">
    <div id="loader">Loading 3D scene...</div>
    <canvas id="scene"></canvas>
    <aside id="sidebar">
        <h3>Controls</h3>
        <!-- SIDEBAR_CONTROLS -->
        <button id="reset">Reset</button>
        <button id="export-png">Export PNG</button>
    </aside>
    <script id="data" type="application/json"><!-- DATA_JSON --></script>
    <script>
        // OrbitControls IIFE exposes THREE.OrbitControls globally.
        // 1. Load data from window.RV_DATA when running in the Docs team,
        //    or from <script id="data"> in standalone mode.
        // 2. Set up scene, camera, renderer, lighting
        // 3. Build geometry according to mode (Code City, Dep Graph, etc.)
        // 4. Connect sidebar to scene parameters
        // 5. Render loop and event handling
    </script>
</body>
</html>
```

### 5. Save and deliver

The output is always standalone HTML. Save to the path indicated by the orchestrator agent (usually `.reversa/documentation/arquitetura.html`).

When invoked outside the context of `/reversa-documentation`, ask for the destination path or use `<mode>-<timestamp>.html` in the current directory.

## Quality guidelines

- **Intuitive camera**: initial position shows the entire scene; OrbitControls with damping for smooth movement.
- **Cohesive materials**: limited palette (5 to 8 colors maximum); colors loaded indicate attribute (e.g.: red for hot path, blue for lightweight modules).
- **Readable labels**: use CSS2DRenderer or sprites; labels only appear on hover or zoom above a threshold to avoid clutter.
- **Visible loader**: scene starts with "Loading 3D scene..." overlay that disappears when the first `requestAnimationFrame` completes.
- **Graceful fallback**: if Three.js fails to load (no internet), show message "This visualization requires loading the Three.js library. Connect to the internet and reload."
- **Basic accessibility**: keyboard navigation for sidebar buttons; visible focus.
- **Language**: comments and visible text in English. Without em-dashes.

## Code guidelines

- **Modularity**: separate scene creation, geometry construction, and interaction management into clearly named functions.
- **No dependencies beyond Three.js and OrbitControls (local in `assets/vendor/`)**: do not import GSAP, dat.GUI, or any other lib without a clear need.
- **Named constants at the top**: colors, sizes, thresholds in a visible configuration block.
- **Dispose**: when switching modes or regenerating, call `geometry.dispose()` and `material.dispose()` to avoid leaks.
- **Performance check**: before rendering, count nodes; if > 5,000 without instanced mesh, abort and show a warning.

## Error handling

Consult `references/ERRORS.md` for common scenarios (CDN inaccessible, malformed JSON, empty project, WebGL not supported, etc.).
