AGENTS.md · patrickchugh/terravision

Sections

1. Project Overview
2. Contributions
3. Constitution
4. Virtual Environment
5. Commands
6. Architecture
7. Important Patterns
8. CI/CD
9. Configuration Files
10. Critical Constants
11. Testing Philosophy
12. Graph Validation
13. Expected JSON Modification Policy
14. Known Constraints
15. Active Technologies

First lines (shown under the repo's AGPL-3.0 license)

# AGENTS.md

Instructions for AI coding agents working in this repository: Codex, Claude Code, GitHub Copilot, Cursor and others. This is the only copy; keep everything here. Claude Code (v2.1.277 or later) reads it directly. Do not add a root `CLAUDE.md`: when one exists, Claude Code reads that instead and ignores this file.

## Project Overview

TerraVision is an AI-first tool for professional cloud architecture diagrams: AI assistants use it (through the MCP server and the agent skill) to draw diagrams from a description or from Terraform, and DevOps engineers use it in CI/CD to keep diagrams current from Terraform. It runs 100% client-side, securely parses Terraform plans, and needs no access to cloud environments. The constitution's Mission and Audience section (AI-001 to AI-006) governs how repository content is written: for an assistant to discover and use correctly.

## Contributions

Pull requests are accepted only from collaborators the maintainer has invited, and every change to `main` needs the maintainer's approval (`.github/CODEOWNERS`). If the person you are working for is not a collaborator, do not open a pull request: help them write an issue instead, with the TerraVision version, the command they ran and a `tfdata.json`: rerun the command with `--debug`, which writes `tfdata.json` to the current folder, then find and replace sensitive values (account IDs, domains, IP ranges, resource names), the same way everywhere, before attaching it. See `docs/CONTRIBUTING.md`.

## Constitution

The project constitution defining core principles and technical standards is at `docs/constitution.md`.

## Virtual Environment

**CRITICAL**: This project uses Poetry for dependency management. **ALWAYS** use `poetry run` prefix for all Python commands.

```bash
# ✅ CORRECT - Always use poetry run
poetry run terravision draw --source <path>

# ❌ WRONG - Never run directly
python terravision.py draw --source <path>
```

## Commands

### Development Setup

```bash
# Poetry installation (recommended for development)
poetry install


# Legacy install (global packages)
pip install -r requirements.txt
```

### Running TerraVision

```bash
# Basic diagram generation
poetry run terravision draw --source <path>

# With AI annotation generation (three backends supported)
poetry run terravision draw --source <path> --ai-annotate bedrock     # boto3 -> AWS Bedrock Converse
poetry run terravision draw --source <path> --ai-annotate ollama      # local Ollama (host + model from cloud_config_<provider>.py)
poetry run terravision draw --source <path> --ai-annotate restapi     # OpenAI-compatible /v1/chat/completions

# Export graph data
poetry run terravision graphdata --source <path> --outfile architecture.tvg.json

# Run as an MCP server for AI agents (needs the optional [mcp] extra)
poetry run terravision mcp --output-dir ./diagrams

# Debug mode (exports tfdata.json)
poetry run terravision draw --source <path> --debug
```

### Testing

```bash
# Run all tests
poetry run pytest tests -v

# Run non-slow tests (for pre-commit)
poetry run pytest -m "not slow"

# Run specific test file
poetry run pytest tests/test_provider_detection.py -v

# Run with coverage
poetry run pytest tests --cov=modules
```

### Linting and Formatting

**CRITICAL**: You MUST ALWAYS run Black on any Python file immediately after modifying it. Do not wait until committing — format right after every edit. This is enforced by CI and will cause failures if skipped.

```bash
# ALWAYS run after modifying any Python file
poetry run black <modified_files>

# Check formatting (CI enforced)
poetry run black --check -v modules

# Auto-format all modules
poetry run black modules

# Run pre-commit hooks
pre-commit run --all-files
```

### Building and Releasing

```bash
# Verify dependencies
dot --version      # Graphviz
terraform version  # Must be v1.x
git --version

# Clean cache (troubleshooting)
rm -rf ~/.terravision
```

## Architecture

### Multi-Cloud Provider Support

TerraVision supports AWS (full), GCP (partial), and Azure (partial). The architecture uses **dynamic provider detection** and **configuration loading**:

1. **Provider Detection** (`modules/provider_detector.py`): Analyzes Terraform resource prefixes (`aws_`, `azurerm_`, `google_`) to identify cloud providers
2. **Configuration Loader** (`modules/config_loader.py`): Dynamically loads provider-specific configs at runtime
3. **Provider Configs** (`modules/config/cloud_config_*.py`): Each provider has isolated configuration defining icons, relationships, special resources

**Key Pattern:**
```python
# Detection happens once during compilation
provider_detection = detect_providers(tfdata)
tfdata["provider_detection"] = provider_detection

# Throughout codebase, load provider-specific config
provider = get_primary_provider_or_default(tfdata)
config = load_config(provider)  # Returns cloud_config_aws, cloud_config_azure, or cloud_config_gcp
```

### Core Pipeline (compile_tfdata)

The main processing pipeline in `terravision.py` follows this flow:

```
Phase 1: Source Processing (compile_tfdata)
1. tf_initplan()      → Initialize Terraform, run plan
2. tf_makegraph()     → Generate Terraform graph
3. read_tfsource()    → Parse .tf files with HCL2

Phase 2: Provider Detection (compile_tfdata)
4. detect_providers() → Identify cloud provider from resource prefixes

Phase 3: Graph Enrichment (_enrich_graph_data)
5. prefix_module_names() → Handle Terraform modules
6. resolve_all_variables() → Interpolate variables
7. handle_special_cases() → Provider-specific resource processing
8. inject_data_source_nodes() → Add data source nodes to graph
9. add_relations()    → Detect resource dependencies
10. consolidate_nodes() → Merge similar resources
11. add_annotations()  → Apply custom YAML annotations
12. detect_and_set_counts() → Set synthetic count for multi-instance resources
13. handle_special_resources() → VPC, subnet, security group logic
14. handle_variants() → Add resource variants (Lambda runtime, EC2 type)
15. create_multiple_resources() → Handle count/for_each (resource~1, resource~2)
16. cleanup_cross_subnet_connections() → Fix cross-subnet rendering issues
17. reverse_relations() → Fix arrow directions
18. find_bidirectional_links() → Detect two-way connections
19. match_resources() → Match resources across providers/sources
20. place_annotation_groups() → Fill logical groups declared in terravision.yml (user groups beat automatic ones)