# ArcSync — Full Technical Documentation

> Automatically generate interactive architecture diagrams from infrastructure-as-code.

ArcSync parses Terraform (HCL) and CloudFormation (CDK, templates) to produce editable Fabric.js canvas diagrams and Mermaid diagrams.

## Architecture Overview

ArcSync is a TypeScript monorepo (Turborepo + pnpm workspaces) with five packages:

- `packages/core` — Shared IaC parsing, graph model, Dagre layout engine, Mermaid renderer
- `packages/cli` — CLI tool for local diagram generation
- `packages/frontend` — PWA built with LitElement, Tailwind CSS, Material Web, Fabric.js
- `packages/backend` — Serverless API using AWS CDK, Lambda, DynamoDB, S3
- `packages/github-action` — GitHub Action for CI/CD diagram generation

## Parsing Pipeline

1. **Input**: Terraform `.tf` files or CloudFormation templates (single or multi-stack)
2. **Parser** (`packages/core`): Extracts resources, relationships, and metadata into `ArchGraph`
3. **Transform pipeline**: `analyzeAccessPatterns → collapseIntegrations → groupByStack → layoutGraph`
4. **Layout** (`layoutGraph`): Dagre computes node positions and edge bend points
5. **Renderer**: Fabric.js canvas (interactive) or Mermaid markdown (static)

## Graph Model

`ArchGraph` is a directed graph where nodes are cloud resources and edges are relationships.

### Node Types (ResourceNode)

Each node has: id, type, provider (aws/azure/gcp), name, position, size.

### Edge Types (ResourceEdge)

Each edge has: source, target, type, direction, points.

Edge types: REFERENCE, DEPENDENCY, NETWORK, IAM, CONTAINS.

### Diagram Overrides

Users can customize diagrams with: repositioned nodes, renamed labels, hidden groups. Overrides are persisted separately from the generated graph.

## Supported Resource Types

### AWS (40+ types)

Lambda, API Gateway, DynamoDB, S3, CloudFront, Route53, EC2, ECS, EKS, RDS, ElastiCache, SQS, SNS, EventBridge, Step Functions, Kinesis, MSK, OpenSearch, Redshift, CodeBuild, CodePipeline, ACM, IAM, KMS, Secrets Manager, WAF, VPC, ELB, Auto Scaling, EFS, ECR, CloudFormation, Cognito, AppSync, Kinesis Firehose, Transit Gateway.

### Azure (18+ types)

Virtual Machine, App Services, Function Apps, Container Instances, Kubernetes, SQL Database, Cosmos DB, Storage, Virtual Network, Load Balancer, Application Gateway, Front Door, API Management, Key Vault, Service Bus, Active Directory, DNS, Azure SQL.

### GCP (17+ types)

Compute Engine, Cloud Run, Cloud Functions, GKE, Cloud SQL, Cloud Spanner, Firestore, Cloud Storage, VPC, Cloud Load Balancing, Cloud CDN, Cloud DNS, Cloud Armor, Pub/Sub, BigQuery, Memorystore, API Gateway.

## Data Flow

### Web Application

1. User submits a Git repository URL
2. Sandbox Lambda clones the repo and detects IaC type
3. Parser Lambda extracts resources and relationships
4. Results stored in DynamoDB (metadata) + S3 (graph data)
5. WebSocket pushes status updates to the frontend
6. Frontend renders the interactive Fabric.js canvas

### CLI / GitHub Action

1. Reads local IaC files
2. Core parser extracts the graph
3. Layout engine positions nodes
4. Outputs Mermaid markdown

## API Reference

Base URL: `https://api.arcsync.dev`

### POST /graphs/generate

Start async graph generation from a repository.

**Auth**: Required (Bearer token)

**Body**:
```json
{
  "repoUrl": "https://github.com/org/repo",
  "branch": "main"
}
```

**Response**: `{ "graphId": "uuid", "status": "PENDING" }`

### POST /graphs/ingest

Upload graph data directly.

**Auth**: Required

**Body**: `{ "graphData": { ... } }`

### GET /graphs

List the authenticated user's graphs, paginated.

**Auth**: Required

**Query params**: `limit`, `cursor`

### GET /graphs/{id}

Get full graph data for a specific graph.

**Auth**: Required

### GET /graphs/{id}/status

Get the generation status of a graph.

**Auth**: Required

**Response**: `{ "graphId": "uuid", "status": "PENDING" | "PROCESSING" | "COMPLETE" | "FAILED" }`

### PUT /graphs/{id}/overrides

Save layout and label overrides.

**Auth**: Required

**Body**: `{ "positions": {...}, "labels": {...}, "hiddenGroups": [...] }`

### PUT /graphs/{id}/visibility

Toggle public/private visibility.

**Auth**: Required

**Body**: `{ "isPublic": true }`

### DELETE /graphs/{id}

Soft-delete a graph (30-day TTL).

**Auth**: Required

### GET /gallery

List public graphs, paginated. No auth required.

### GET /gallery/{id}

Get a public graph by ID. No auth required.

## Frontend Routes

| Path | Description |
|------|-------------|
| `/` | Landing page with repository URL input |
| `/canvas/:graphId` | Interactive Fabric.js diagram editor |
| `/diagram/:graphId` | Mermaid SVG diagram view |
| `/markdown/:graphId` | Raw Mermaid source view |
| `/gallery` | Public diagram gallery |
| `/gallery/:graphId` | Public graph viewer |
| `/diagrams` | User's saved diagrams |

## CLI Usage

```bash
npx @auto-arch-diagram/cli [directory]
```

Scans the given directory (or current directory) for Terraform/CloudFormation files and outputs a Mermaid diagram to stdout.

## GitHub Action Usage

```yaml
- uses: neilvanlandingham/arcsync@v1
  with:
    path: ./infrastructure
    format: mermaid
```

Generates a diagram and posts it as a PR comment.

## Technology Stack

- TypeScript (all packages)
- LitElement + Tailwind CSS + Material Web (frontend)
- Fabric.js v6 (interactive canvas)
- Dagre (graph layout)
- AWS CDK + Lambda + DynamoDB + S3 (backend)
- Auth0 SPA SDK (authentication)
- Vite (frontend build)
- Vitest (testing)
- Biome (linting/formatting)