CartoCloud

Cloud infrastructure diagram generation and visualization tools.

Features

• PlantUML Diagram Builder: Generate AWS infrastructure diagrams using a code-based API with AWS stdlib components
• Infrastructure Documentation: Generate comprehensive markdown documentation from CloudMapper and Cartography data
• Multi-Format Support: Output to PlantUML and Mermaid diagram formats

Documentation Generator

The generate_docs.py script generates comprehensive AWS infrastructure documentation from CloudMapper and Cartography data using Jinja2 templates.

Quick Start

# Generate all documentation for an account
python src/generate_docs.py --account <account_name>

# Generate specific documentation types
python src/generate_docs.py --account <account_name> --type organizations --type networks

# Generate for a specific region
python src/generate_docs.py --account <account_name> --region eu-central-1

# Generate only PlantUML diagrams
python src/generate_docs.py --account <account_name> --format plantuml

# Skip Neo4j integration (CloudMapper data only)
python src/generate_docs.py --account <account_name> --no-neo4j

Documentation Types

Type	Description	Output
organizations	AWS Organization hierarchy with master/tenant accounts	organizations.md, diagrams
regions	Regions with custom-created resources and counts	regions.md
networks	VPCs with deployed resources and connectivity	networks.md, per-VPC diagrams
instances	EC2 instances with detailed connectivity info	instances.md, per-instance diagrams

CLI Arguments

Argument	Required	Description
--account	Yes	Account name in account-data/ directory
--account-dir	No	Base directory for account data (default: account-data)
--type	No	Documentation type(s): organizations, regions, networks, instances, all (default: all)
--region	No	AWS region for instances (default: us-east-1)
--output-dir	No	Output directory (default: inventory_documentation)
--neo4j-uri	No	Neo4j connection URI (default: bolt://localhost:7687)
--no-neo4j	No	Skip Neo4j, use CloudMapper only
--format	No	Diagram format: plantuml, mermaid, both (default: both)

Output Structure

inventory_documentation/{account}/
├── organizations.md          # Organization overview
├── organizations/
│   ├── hierarchy.puml      # PlantUML diagram
│   └── hierarchy.mmd       # Mermaid diagram
├── regions.md               # Region summaries
├── networks.md              # VPC documentation
├── networks/
│   └── {vpc_id}/
│       ├── diagram.puml    # VPC PlantUML diagram
│       └── diagram.mmd     # VPC Mermaid diagram
├── instances.md             # Instance documentation
└── instances/
    └── {instance_id}/
        ├── diagram.puml   # Instance connectivity diagram
        └── diagram.mmd    # Instance connectivity diagram

Data Sources

CloudMapper

Primary data source for AWS inventory. Expects data in account-data/{account}/{region}/ structure:

• ec2-describe-vpcs.json - VPCs
• ec2-describe-subnets.json - Subnets
• ec2-describe-instances.json - EC2 instances
• ec2-describe-security-groups.json - Security groups
• organizations-describe-organization.json - Organization details
• organizations-list-accounts.json - Account hierarchy

Cartography (Optional)

Neo4j-based graph database for enhanced relationship discovery:

• Load balancer to instance associations
• IAM role relationships
• Other cross-resource dependencies

Project Structure

src/
├── cartocloud/
│   └── builders/
│       └── plantuml/      # PlantUML diagram builder
├── inventory_shared/
│   ├── diagrams/           # Diagram generator modules
│   │   ├── organization.py
│   │   ├── vpc.py
│   │   └── instance.py
│   ├── template_context.py # Jinja2 context builders
│   ├── models.py           # Data models
│   ├── cloudmapper_loader.py # CloudMapper data loader
│   └── cartography_loader.py # Cartography integration
├── generate_docs.py         # Main CLI entry point
└── templates/               # Jinja2 templates
    ├── base/               # Base templates
    │   ├── layout.md
    │   └── macros.md
    └── pages/              # Page templates
        ├── organizations.md.j2
        ├── networks.md.j2
        ├── instances.md.j2
        └── regions.md.j2

Development

Setup

# Install dependencies (using poetry)
poetry install

Running Tests

# Generate documentation for test account
python src/generate_docs.py --account demo --type all --output-dir ./test_output

Template Customization

Templates are located in templates/ and use Jinja2 syntax. To customize:

1. Edit the template files in templates/pages/ or templates/base/
2. Context variables are provided by functions in src/inventory_shared/template_context.py
3. Diagram generators are in src/inventory_shared/diagrams/

Requirements

• Python 3.12+
• Jinja2
• (Optional) Neo4j for enhanced relationship discovery

License

[Add your license information here]