---
name: archigraph-reverse-engineer
description: Reverse-engineer any codebase into a correct ArchiGraph 0.3 document and companion schema. Use this skill when you need to analyze an existing repository and produce architecture YAML that describes how the system actually works — its components, APIs, data stores, boundaries, and the connections between them.
---

# ArchiGraph Reverse-Engineering Skill

Analyze any codebase and produce two YAML files that describe its architecture:

1. **`schema.yaml`** — defines the vocabulary: what layers, node kinds, edge kinds, and custom fields are valid for this system
2. **`archigraph.yaml`** — the architecture document itself: every component, relationship, and view

The output is machine-readable and renders in the ArchiGraph Viewer (Cytoscape.js graph visualization).

---

## Part 1: The Two Files

### schema.yaml (the vocabulary)

The schema defines what kinds of things exist in this architecture and what metadata they carry. It does NOT contain any specific components — only the rules and field definitions.

```yaml
schemaVersion: "1.0"

meta:
  name: "My App Schema"
  description: "Architecture schema for [describe the system's tech stack and domain]"
  version: "1.0"

layers:
  # Ordered from highest abstraction to lowest
  product:    { label: "Product",    order: 10, ui: { color: "#42A5F5" } }
  logical:    { label: "Logical",    order: 20, ui: { color: "#9C27B0" } }
  api:        { label: "API",        order: 30, ui: { color: "#E91E63" } }
  runtime:    { label: "Runtime",    order: 40, ui: { color: "#FF9800" } }
  data:       { label: "Data",       order: 50, ui: { color: "#795548" } }
  messaging:  { label: "Messaging",  order: 60, ui: { color: "#FF4F8B" } }
  security:   { label: "Security",   order: 70, ui: { color: "#F44336" } }
  monitoring: { label: "Monitoring", order: 80, ui: { color: "#4CAF50" } }

nodeKinds:
  # Each kind needs: label, ui.shape, ui.color
  # Optional: description, recursive, implementable
  actor:          { label: "Actor",          ui: { shape: "ellipse",          color: "#42A5F5" } }
  ui:             { label: "UI",             ui: { shape: "round-rectangle",  color: "#42A5F5" }, recursive: true, implementable: true }
  component:      { label: "Component",      ui: { shape: "ellipse",          color: "#9C27B0" } }
  interface:      { label: "Interface",      ui: { shape: "diamond",          color: "#E91E63" } }
  datastore:      { label: "Datastore",      ui: { shape: "hexagon",          color: "#795548" } }
  queue:          { label: "Queue",           ui: { shape: "barrel",           color: "#FF4F8B" } }
  gateway:        { label: "Gateway",        ui: { shape: "diamond",          color: "#FF9800" } }
  lambda:         { label: "Lambda",         ui: { shape: "round-rectangle",  color: "#FF9800" }, implementable: true }
  container:      { label: "Container",      ui: { shape: "ellipse",          color: "#FF9800" }, recursive: true, implementable: true }
  auth:           { label: "Auth",           ui: { shape: "ellipse",          color: "#DD344C" } }
  boundary:       { label: "Boundary",       ui: { shape: "rectangle",        color: "#607D8B" } }
  infrastructure: { label: "Infrastructure", ui: { shape: "round-rectangle",  color: "#FF6F00" }, implementable: true }
  artifact:       { label: "Artifact",       ui: { shape: "round-tag",        color: "#78909C" } }
  cdn:            { label: "CDN",            ui: { shape: "round-rectangle",  color: "#8C4FFF" } }

edgeKinds:
  uses:           { label: "Uses" }
  triggers:       { label: "Triggers" }
  routes:         { label: "Routes" }
  serves:         { label: "Serves" }
  calls:          { label: "Calls" }
  reads:          { label: "Reads" }
  writes:         { label: "Writes" }
  publishes:      { label: "Publishes" }
  subscribes:     { label: "Subscribes" }
  authenticates:  { label: "Authenticates" }
  authorizes:     { label: "Authorizes" }
  implements:     { label: "Implements" }
  references:     { label: "References" }
  contains:       { label: "Contains" }
  provisions:     { label: "Provisions" }
  emits:          { label: "Emits" }

connectionRules:
  # Constrains which node kinds can appear as source/target for each edge kind
  uses:
    - from: [actor]
      to: [ui]
  triggers:
    - from: [ui]
      to: [interface]
  routes:
    - from: [cdn, gateway]
      to: [gateway, lambda, container, datastore]
  serves:
    - from: [cdn]
      to: [ui, component]
  calls:
    - from: [component, lambda, container, gateway]
      to: [component, lambda, container, interface]
  reads:
    - from: [component, lambda, container]
      to: [datastore]
  writes:
    - from: [component, lambda, container]
      to: [datastore]
  publishes:
    - from: [component, lambda, container]
      to: [queue]
  subscribes:
    - from: [component, lambda, container]
      to: [queue]
  authenticates:
    - from: [ui, gateway]
      to: [auth]
  authorizes:
    - from: [gateway]
      to: [auth]
  implements:
    - from: [component, lambda, container]
      to: [interface, component, lambda, container]
  provisions:
    - from: [infrastructure]
      to: [lambda, container, gateway, cdn, datastore, queue, auth, boundary]
  contains:
    - from: [boundary]
      to: [component, lambda, container, gateway, datastore, queue, auth, infrastructure]
    - from: [ui]
      to: [ui]
    - from: [container]
      to: [component, container]
  emits:
    - from: [component, lambda, container]
      to: [queue]

fields:
  # Custom fields are stored in the node/edge `x` bag
  # Key format: x.{section}.{fieldName}
  # See "Field Catalog" section below for the full reference

  # Example:
  x.docs.description:
    type: string
    label: "Description"
    appliesTo: { nodes: true, edges: true }
    ui: { widget: "textarea", section: "Documentation", order: 10 }

# ... (add fields, validation, forms as needed — see Field Catalog)
```

### archigraph.yaml (the architecture)

The document contains the actual architecture: specific nodes (components), edges (relationships), views, and rules.

```yaml
archigraph: "0.3"

meta:
  system: "My App Name"
  description: "One-sentence description of the system."
  environment: [prod, qa, local]
  tags: [relevant, tech, tags]
  owners:
    - platform-team

nodes:
  - id: actor.end_user
    kind: actor
    layer: product
    name: "End User"
    x:
      docs:
        description: "Who this actor is and what they do."

  # ... more nodes

edges:
  - kind: uses
    layer: product
    from: actor.end_user
    to: ui.app
    x:
      protocol: "https"

  # ... more edges

views:
  - id: view.overview
    name: "System Overview"
    description: "End-to-end request path"
    include:
      nodes: [actor.end_user, ui.app, ...]
      layers: [product, logical, runtime, data]
    layout: "flow"

rules:
  - id: R001
    name: "Datastores must have data classification"
    severity: error
    match:
      node_kind: datastore
    where:
      x.security.dataClassification: "present"
```

---

## Part 2: Node Reference

Every node requires `id`, `kind`, and `layer`. All other fields are optional but recommended.

### Node Structure

```yaml
- id: <kind>.<descriptive_name>     # Unique. Convention: kind.name or kind.parent.name
  kind: <nodeKind>                   # Must match a key in schema.nodeKinds
  layer: <layerName>                 # Must match a key in schema.layers
  name: "Human-Readable Name"       # Display label
  type: <subtype>                    # Freeform qualifier (e.g., "rest_api", "postgres", "frontend")
  owners: [team.name]               # Who owns this
  tags: [relevant, tags]            # Searchable labels
  locator:                           # For code/artifact traceability
    uri: "git://repo.example.com/org/repo"
    path: "src/handlers/myFile.ts"
    line_start: 1
    line_end: 200
    symbol: "functionName"
  links:
    repo: "https://github.com/org/repo"
  x:                                 # Extension bag — all custom fields go here
    docs:
      description: "Detailed description"
    # ... other x.* fields matching schema.fields
```

### Node Kind Guide — What to Use When

| Kind | Use for | Layer | ID Convention |
|------|---------|-------|---------------|
| `actor` | End users, external systems, third-party services | product | `actor.{name}` |
| `ui` | SPA apps, web pages, screens, mobile apps | product | `ui.{app}` or `ui.{app}.{page}` |
| `component` | Logical services, modules, internal libraries | logical | `component.{name}` or `svc.{name}` |
| `interface` | REST endpoints, GraphQL queries, gRPC methods | api / logical | `api.{service}.{operation}` |
| `datastore` | Databases, caches, object stores, file systems | data | `db.{name}`, `cache.{name}`, `store.{name}` |
| `queue` | Message queues, event buses, streams | messaging | `queue.{name}` |
| `gateway` | API gateways, load balancers, reverse proxies | runtime | `gw.{name}` |
| `lambda` | Serverless functions, cloud functions | runtime | `lambda.{purpose}` |
| `container` | Dockerized apps, ECS/K8s services | runtime | `svc.{name}` |
| `cdn` | CloudFront, Cloudflare, CDN distributions | runtime | `cdn.{name}` |
| `auth` | Cognito, Auth0, Okta, identity providers | security | `auth.{name}` |
| `boundary` | Trust zones, network segments, VPCs | runtime | `boundary.{name}` |
| `infrastructure` | Terraform/CDK/CloudFormation projects | runtime | `infra.{appname}` |
| `artifact` | Design docs, specs, OpenAPI specs, Figma files | product / logical | `art.{type}.{name}` |

### Recursive Kinds

`ui` and `container` are **recursive** — they can contain children of their own kind via `contains` edges:

- **UI hierarchy**: `ui.app` contains `ui.app.dashboard`, `ui.app.settings`, etc.
- **Container hierarchy**: `svc.api` contains `component.auth_service`, `component.user_service`, etc.

---

## Part 3: Edge Reference

Every edge requires `kind`, `from`, and `to`. The `layer` field is recommended.

### Edge Structure

```yaml
- kind: <edgeKind>                   # Must match a key in schema.edgeKinds
  from: <source_node_id>            # Must reference a valid node id
  to: <target_node_id>              # Must reference a valid node id
  layer: <layerName>                 # Layer where this relationship exists
  type: <subtype>                    # Optional qualifier (e.g., "http", "sql")
  tags: [optional, tags]
  semantics:                         # Human-readable description of the interaction
    action: "Click 'Save'"
    operation: "PUT /customers/{id}"
    description: "User saves edited customer data"
  data:                              # What data flows across this edge
    fields: [name, email, phone]
    request: { ... }
    response: { ... }
    query: "SELECT * FROM customers WHERE id = ?"
  x:                                 # Extension bag — custom fields
    protocol: "https"
    auth:
      mechanism: "jwt"
    security:
      encryptionInTransit: true
      dataClassification: "pii"
```

### Edge Kind Guide — What Connects What

| Edge Kind | From → To | Meaning | Key x.* fields |
|-----------|-----------|---------|-----------------|
| `uses` | actor → ui | User interacts with a screen | |
| `triggers` | ui → interface | User action calls an API endpoint | `x.protocol`, `x.auth.mechanism` |
| `routes` | cdn/gateway → container/lambda | Infrastructure routes traffic | `x.protocol`, `x.auth.mechanism` |
| `serves` | cdn → ui/component | CDN serves static assets | `x.protocol` |
| `calls` | component → component/interface | Service-to-service call | `x.protocol`, `x.auth.mechanism` |
| `reads` | component → datastore | Read from database/cache | `x.protocol` |
| `writes` | component → datastore | Write to database/cache | `x.protocol` |
| `publishes` | component → queue | Send message to queue | `x.protocol` |
| `subscribes` | component → queue | Consume messages from queue | `x.protocol` |
| `emits` | component → queue | Emit events (alias for publishes) | `x.protocol` |
| `authenticates` | ui/gateway → auth | Authenticate users/requests | `x.protocol`, `x.auth.mechanism` |
| `authorizes` | gateway → auth | Check authorization | `x.protocol`, `x.auth.mechanism` |
| `implements` | component → interface | This service handles this endpoint | |
| `contains` | parent → child | Hierarchy: boundary membership, UI nesting | |
| `provisions` | infrastructure → resource | IaC manages this AWS resource | |
| `references` | any → artifact | Links to design docs, specs | |

---

## Part 4: Layer Model

Layers organize nodes by abstraction level. Order from highest (user-facing) to lowest (infrastructure).

| Layer | Order | What goes here |
|-------|-------|----------------|
| `product` | 10 | Actors, UI screens, mockups/artifacts — what users see |
| `logical` | 20 | Components, services, modules — logical building blocks |
| `api` | 30 | API interfaces (REST endpoints, GraphQL, gRPC methods) |
| `runtime` | 40 | Containers, gateways, lambdas, CDNs — deployed compute |
| `data` | 50 | Databases, caches, object stores — persistent state |
| `messaging` | 60 | Queues, event buses, streams — async communication |
| `security` | 70 | Auth providers, identity pools — authentication/authorization |
| `monitoring` | 80 | Log groups, dashboards, alarms — observability |

You can add custom layers for your domain (e.g., `aws.edge`, `aws.compute`, `code`, `ops`). Always keep the `order` field consistent so layers render in the correct stack.

---

## Part 5: Field Catalog

Fields are custom metadata stored in the `x` bag on nodes and edges. The schema defines what fields are valid and where they apply.

### Defining Fields in schema.yaml

```yaml
fields:
  x.section.fieldName:
    type: string                         # string | number | integer | boolean | object | array
    label: "Human-Readable Label"
    description: "What this field means"
    enum: [option1, option2, option3]    # Optional: restrict to specific values
    format: uri                          # Optional: hint (uri, json, code, markdown, date-time)
    default: "default_value"             # Optional: default value
    appliesTo:
      nodes: true                        # Does this field apply to nodes?
      edges: false                       # Does this field apply to edges?
      nodeKinds: [lambda, container]     # Optional: restrict to specific kinds
      edgeKinds: [calls, routes]         # Optional: restrict to specific edge kinds
    ui:
      widget: "select"                   # text | textarea | number | checkbox | select | tags | json | code | markdown | url | date | color
      section: "Section Name"           # Groups fields in the editor UI
      order: 10                          # Sort order within section
```

### Standard Field Sections

These are the commonly used field groups. Include the ones relevant to your system:

**AWS Infrastructure** (`x.aws.*`): arn, region, accountId — for cloud-hosted resources
**UI Screen** (`x.ui.*`): route, pageType, framework, stateManagement — for frontend screens
**Service** (`x.service.*`): language, framework, port, healthCheck — for backend services
**API Endpoint** (`x.api.*`): method, path, auth, requestBody, responseBody — for interfaces
**Lambda** (`x.lambda.*`): runtime, handler, memory, timeout, envVars — for serverless
**Container** (`x.container.*`): image, port, cpu, memory, desiredCount — for containers
**Gateway** (`x.gateway.*`): type, stage, throttle, cors — for API gateways
**CDN** (`x.cdn.*`): origin, priceClass, cacheTtl, customDomain — for CDN distributions
**Auth** (`x.auth.*`): provider, flows, mfa, tokenExpiry — for auth providers
**Database** (`x.db.*`): engine, version, instanceClass, tables — for datastores
**Queue** (`x.queue.*`): type, dlq, maxRetries, messageSchema — for message queues
**Security** (`x.security.*`): dataClassification, encryptionAtRest, encryptionInTransit
**Edge/Connection** (`x.protocol`, `x.auth.mechanism`): transport details for edges
**Ops** (`x.ops.*`): runbook, dashboard, alarmArn — operational links
**FinOps** (`x.finops.*`): costCenter — cost attribution
**Deployment** (`x.deploy.*`): environments, strategy, local, qa, prod
**Documentation** (`x.docs.*`): description, notes — freeform documentation

### Using Fields on Nodes

Fields are stored in the `x` bag with nested structure matching the dotted key:

```yaml
# Field key: x.aws.region → stored as:
- id: lambda.my_func
  kind: lambda
  layer: runtime
  name: "My Lambda"
  x:
    aws:
      region: "us-east-1"
      arn: "arn:aws:lambda:..."
    lambda:
      runtime: "nodejs20.x"
      handler: "index.handler"
      memory: 256
      timeout: 30
    security:
      dataClassification: "pii"
    deploy:
      environments: "local, qa, prod"
      strategy: "rolling"
      local: "docker-compose"
```

---

## Part 6: Views and Rules

### Views

Views define named subsets of the graph for focused diagrams.

```yaml
views:
  - id: view.request_path
    name: "Request Path: Browser → API → Database"
    description: "The main request flow through the system"
    include:
      nodes:
        - actor.end_user
        - ui.app
        - gw.api
        - svc.backend
        - db.main
      layers: [product, logical, runtime, data]
    layout: "flow"

  - id: view.data_layer
    name: "Data Architecture"
    include:
      layers: [data, messaging]
    layout: "flow"
```

**Include strategies:**
- `nodes`: Explicit list of node IDs — most precise
- `layers`: All nodes in these layers
- `kinds`: All nodes of these kinds
- `tags`: All nodes with these tags

You can combine these — they are additive. Use `exclude` to remove specific nodes.

### Rules

Rules define validation constraints that are checked in the viewer.

```yaml
rules:
  - id: R001
    name: "Datastores must declare data classification"
    severity: error
    match:
      node_kind: datastore
    where:
      x.security.dataClassification: "present"

  - id: R002
    name: "API endpoints must have method and path"
    severity: error
    match:
      node_kind: interface
    where:
      x.api.method: "present"
      x.api.path: "present"

  - id: R003
    name: "PII datastores should have encryption at rest"
    severity: warning
    match:
      node_kind: datastore
    where:
      x.security.dataClassification: "pii"
      x.security.encryptionAtRest: true
```

---

## Part 7: How to Reverse-Engineer a Codebase

Follow this process to analyze an existing codebase and produce a correct archigraph.

### Step 1: Survey the Repository Structure

Explore the top-level directory, looking for:

- **Package files**: `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml` — identifies languages and frameworks
- **Docker files**: `Dockerfile`, `docker-compose.yml` — identifies deployable services and local dev setup
- **IaC files**: `terraform/`, `cdk/`, `cloudformation/`, `serverless.yml` — identifies infrastructure
- **Config files**: `.env`, `.env.example`, `config/` — identifies external dependencies (DB URLs, API keys, queue URLs)
- **Source directories**: `src/`, `app/`, `lib/`, `cmd/` — identifies major code modules
- **API definitions**: `openapi.yaml`, `swagger.json`, `schema.graphql`, `proto/` — identifies interfaces
- **Frontend**: `src/pages/`, `src/routes/`, `src/components/` — identifies UI screens

### Step 2: Identify Actors

Ask: who or what triggers this system from the outside?

- End users (via browser, mobile app, CLI)
- External services that call into this system (webhooks, partner APIs)
- Scheduled triggers (cron jobs, CloudWatch events)
- Other internal systems that depend on this one

Create one `actor` node per distinct actor.

### Step 3: Identify UI Screens (if applicable)

Look at the router configuration:

- **React**: `react-router` routes, pages directory
- **Next.js**: `app/` or `pages/` directory
- **Vue**: `router/index.ts`
- **Angular**: route modules

Create a parent `ui` node for the app, and child `ui` nodes for each major page/route. Use `contains` edges for the hierarchy.

### Step 4: Identify Backend Services and Components

Look for:

- **Express/Fastify/Koa/Flask/Django/Gin**: main app file, route definitions
- **Microservices**: separate `Dockerfile`s or separate deployment configs
- **Internal modules**: clearly separated service classes or handlers

For monoliths, create one `container` node and child `component` nodes for each logical service area (auth, users, billing, etc.).

For microservices, create one `container` node per service.

### Step 5: Identify API Interfaces

Parse the route definitions to extract endpoints:

- **Express**: `app.get('/api/users', handler)` → interface node: `api.users.list`
- **REST convention**: One interface node per HTTP method + path combination
- **GraphQL**: One interface node per query/mutation
- **gRPC**: One interface node per RPC method

Include `x.api.method`, `x.api.path`, and `x.api.auth` on each.

### Step 6: Identify Data Stores

Look for:

- **Database connections**: Prisma schema, Sequelize models, Knex config, SQLAlchemy, GORM
- **Cache connections**: Redis/Memcached clients
- **Object storage**: S3 client initialization
- **Search engines**: Elasticsearch/OpenSearch clients
- **Key-value**: DynamoDB clients

Create one `datastore` node per distinct database/cache/store. Include `x.db.engine` and `x.security.dataClassification`.

### Step 7: Identify Message Queues and Events

Look for:

- **SQS/RabbitMQ**: queue consumer/producer code
- **SNS/EventBridge**: event publisher/subscriber code
- **Kafka**: producer/consumer configuration
- **Redis Pub/Sub**: pub/sub client code

Create `queue` nodes and connect with `publishes`/`subscribes`/`emits` edges.

### Step 8: Identify Auth and Security

Look for:

- **Auth middleware**: JWT verification, session checks, OAuth flows
- **Auth providers**: Cognito, Auth0, Firebase Auth configuration
- **IAM roles**: Lambda execution roles, service roles

Create `auth` nodes for identity providers.

### Step 9: Identify Infrastructure

Look for:

- **CDN**: CloudFront distributions, Cloudflare config
- **API Gateway**: AWS API Gateway, Kong, Nginx configs
- **IaC**: Terraform modules, CDK stacks
- **CI/CD**: GitHub Actions, CodePipeline, GitLab CI

Create `gateway`, `cdn`, and `infrastructure` nodes as appropriate.

### Step 10: Identify Trust Boundaries

Look for:

- Public internet vs internal network
- VPC boundaries
- AWS account boundaries
- Different security zones

Create `boundary` nodes and use `contains` edges to place resources within them.

### Step 11: Draw the Edges

Trace every connection in the code:

1. **Actor → UI**: `uses` edges from actors to screens they interact with
2. **UI → API**: `triggers` edges from screens to API endpoints they call (look at `fetch()`, `axios`, API client code)
3. **CDN/Gateway → Service**: `routes` edges from infrastructure to the services that handle requests
4. **Service → Service**: `calls` edges for HTTP/gRPC calls between services
5. **Service → Interface**: `implements` edges from components to the interfaces they handle
6. **Service → Datastore**: `reads`/`writes` edges (look at query code, ORM calls)
7. **Service → Queue**: `publishes`/`subscribes` edges
8. **UI/Gateway → Auth**: `authenticates`/`authorizes` edges
9. **Infrastructure → Resources**: `provisions` edges from IaC to managed resources
10. **Boundary → Resources**: `contains` edges

For each transport edge, set:
- `x.protocol`: https, http, grpc, sql, kv, event, websocket
- `x.auth.mechanism`: none, cookie, jwt, oauth2, sigv4, mtls, api-key
- `x.security.dataClassification`: none, internal, pii, pci, phi
- `x.security.encryptionInTransit`: true/false

### Step 12: Create Views

Create at least these views:

1. **System Overview**: The full end-to-end request path (Actor → UI → Gateway → Service → Data)
2. **Data Architecture**: All datastores, queues, and their read/write connections
3. **Security**: Auth flows, trust boundaries, and sensitive data paths

### Step 13: Create the Schema

Based on what you discovered, build the schema:

1. **Layers**: Include only the layers you actually used
2. **Node Kinds**: Include only the kinds you actually used, with appropriate shapes and colors
3. **Edge Kinds**: Include only the edge kinds you actually used
4. **Connection Rules**: Encode which kinds can connect (based on the edges you drew)
5. **Fields**: Define every `x.*` field you used on nodes and edges
6. **Validation**: Add `requiredByNodeKind` and `requiredByEdgeKind` for critical fields
7. **Forms**: Define the editing form layout for each node kind

### Step 14: Validate

Check your output against these rules:

- [ ] Every `from` and `to` in edges references a valid node `id`
- [ ] Every node `kind` matches a key in schema `nodeKinds`
- [ ] Every node `layer` matches a key in schema `layers`
- [ ] Every edge `kind` matches a key in schema `edgeKinds`
- [ ] Every edge satisfies its `connectionRules` (correct from/to kind pairs)
- [ ] No orphan nodes (every node has at least one edge)
- [ ] No duplicate node IDs
- [ ] Every UI screen has a `triggers` edge to at least one interface
- [ ] Every interface has an `implements` edge from at least one component
- [ ] Every datastore has `reads` or `writes` edges
- [ ] The `x.*` fields on nodes match the field definitions in the schema
- [ ] Views reference only node IDs that exist

---

## Part 8: Naming Conventions

### Node IDs

Use dotted, lowercase identifiers. The first segment should indicate the kind or role:

```
actor.end_user                  # Actors
actor.stripe                    # External system actors

ui.app                          # Parent SPA
ui.app.dashboard                # Child page
ui.app.settings                 # Child page

svc.api                         # Container (main API server)
component.auth_service          # Component within a container
component.user_service          # Component within a container

api.auth.login                  # POST /login
api.users.list                  # GET /users
api.users.get                   # GET /users/:id
api.users.update                # PUT /users/:id

db.main                         # Primary database
db.analytics                    # Analytics database
cache.sessions                  # Session cache
store.uploads                   # S3 / object storage

queue.email_notifications       # SQS queue
queue.audit_events              # Event bus

gw.api                          # API Gateway
cdn.web                         # CloudFront distribution
auth.cognito                    # Cognito user pool

lambda.email_sender             # Lambda function
lambda.image_processor          # Lambda function

boundary.public                 # Public internet
boundary.vpc                    # VPC boundary

infra.myapp                     # Infrastructure project

art.openapi.api                 # OpenAPI spec
art.figma.designs               # Figma designs
```

### View IDs

```
view.overview                   # System overview
view.request_path               # End-to-end request path
view.data_architecture          # Data layer
view.security                   # Auth and security
```

---

## Part 9: Adapting the Schema to the Codebase

Not every codebase needs every node kind, layer, or field. Tailor the schema:

**Simple SPA + API + DB** — you need:
- Layers: product, logical, api, runtime, data
- Node kinds: actor, ui, component, interface, datastore
- Edge kinds: uses, triggers, implements, reads, writes, contains

**Microservices on AWS** — you need everything plus:
- Layers: messaging, security, monitoring
- Node kinds: queue, gateway, lambda, cdn, auth, boundary, infrastructure
- Edge kinds: routes, serves, calls, publishes, subscribes, authenticates, authorizes, provisions

**Serverless** — emphasize:
- Node kinds: lambda, gateway, datastore, queue, auth, infrastructure
- Edge kinds: routes, reads, writes, publishes, subscribes, provisions

**Monolith** — emphasize:
- One container node with multiple component children
- More interface nodes (one per endpoint)
- Fewer infrastructure nodes

### Custom Layers

If the standard layers don't fit, add domain-specific ones:

```yaml
layers:
  product:     { label: "Product",     order: 10 }
  logical:     { label: "Logical",     order: 20 }
  api:         { label: "API",         order: 30 }
  runtime:     { label: "Runtime",     order: 40 }
  data:        { label: "Data",        order: 50 }
  # Custom:
  ml:          { label: "ML Pipeline", order: 55, ui: { color: "#00BCD4" } }
  code:        { label: "Code",        order: 90, ui: { color: "#546E7A" } }
```

### Custom Node Kinds

If you discover entities that don't fit existing kinds:

```yaml
nodeKinds:
  # Standard kinds...
  scheduler:
    label: "Scheduler"
    description: "Cron job or scheduled task runner"
    ui: { shape: "octagon", color: "#9E9E9E" }
  ml_model:
    label: "ML Model"
    description: "Trained machine learning model"
    ui: { shape: "star", color: "#00BCD4" }
```

Add corresponding connection rules and update edge kinds as needed.

---

## Part 10: Common Patterns

### Pattern: SPA → API Gateway → Service → Database

```yaml
nodes:
  - id: actor.user
    kind: actor
    layer: product
    name: "User"

  - id: ui.app
    kind: ui
    layer: product
    name: "Web App"
    x: { ui: { route: "/", framework: "React + Vite", stateManagement: "Zustand" } }

  - id: gw.api
    kind: gateway
    layer: runtime
    name: "API Gateway"
    x: { gateway: { type: "HTTP" } }

  - id: svc.backend
    kind: container
    layer: runtime
    name: "API Server"
    x: { service: { language: "TypeScript", framework: "Express.js" }, container: { port: 3000 } }

  - id: api.users.list
    kind: interface
    layer: api
    name: "GET /api/users"
    x: { api: { method: "GET", path: "/api/users", auth: "jwt" } }

  - id: db.main
    kind: datastore
    layer: data
    name: "PostgreSQL"
    x: { db: { engine: "PostgreSQL" }, security: { dataClassification: "pii", encryptionAtRest: true } }

edges:
  - kind: uses
    from: actor.user
    to: ui.app
    layer: product

  - kind: triggers
    from: ui.app
    to: api.users.list
    layer: runtime
    x: { protocol: "https", auth: { mechanism: "jwt" } }

  - kind: routes
    from: gw.api
    to: svc.backend
    layer: runtime
    x: { protocol: "https" }

  - kind: implements
    from: svc.backend
    to: api.users.list
    layer: logical

  - kind: reads
    from: svc.backend
    to: db.main
    layer: data
    x: { protocol: "sql", security: { dataClassification: "pii" } }
```

### Pattern: Event-Driven (Pub/Sub)

```yaml
nodes:
  - id: svc.order_service
    kind: container
    layer: runtime
    name: "Order Service"

  - id: queue.order_events
    kind: queue
    layer: messaging
    name: "Order Events"
    x: { queue: { type: "standard" } }

  - id: lambda.email_notifier
    kind: lambda
    layer: runtime
    name: "Email Notifier"
    x: { lambda: { runtime: "nodejs20.x", handler: "index.handler" } }

edges:
  - kind: publishes
    from: svc.order_service
    to: queue.order_events
    layer: messaging
    x: { protocol: "event" }

  - kind: subscribes
    from: lambda.email_notifier
    to: queue.order_events
    layer: messaging
    x: { protocol: "event" }
```

### Pattern: Auth Flow

```yaml
nodes:
  - id: ui.app
    kind: ui
    layer: product
    name: "Web App"

  - id: auth.cognito
    kind: auth
    layer: security
    name: "Cognito User Pool"
    x: { auth: { provider: "Cognito", flows: "OAuth2 PKCE", mfa: "OPTIONAL" } }

  - id: gw.api
    kind: gateway
    layer: runtime
    name: "API Gateway"

edges:
  - kind: authenticates
    from: ui.app
    to: auth.cognito
    layer: security
    x: { protocol: "https", auth: { mechanism: "oauth2" } }

  - kind: authorizes
    from: gw.api
    to: auth.cognito
    layer: security
    x: { protocol: "https", auth: { mechanism: "jwt" } }
```

---

## Part 11: Tips for Accuracy

1. **Read the code, not just the docs.** Documentation lies. Database connections, HTTP clients, and queue producers in the actual source code are ground truth.

2. **Follow the imports.** A service's imports reveal its dependencies: database drivers, HTTP clients, queue SDKs, auth libraries.

3. **Check environment variables.** `.env.example` or config files reveal external dependencies: `DATABASE_URL`, `REDIS_URL`, `SQS_QUEUE_URL`, `COGNITO_USER_POOL_ID`.

4. **Check Docker Compose.** `docker-compose.yml` reveals the local development topology: which databases, caches, and services run together.

5. **Check infrastructure code.** Terraform/CDK files are the definitive source for what AWS resources exist and how they're configured.

6. **Don't invent nodes for things that don't exist.** Only model what the code actually does, not what it theoretically could do.

7. **Every edge must be traceable.** If you draw a `reads` edge from service A to database B, you should be able to point to the code in service A that connects to database B.

8. **Be thorough with interfaces.** Every API endpoint the codebase exposes should be an `interface` node. This is where most archigraphs are too sparse.

9. **Capture the full request path.** Trace a request from actor → UI → gateway → service → database. If any step is missing, the archigraph is incomplete.

10. **Set data classification on everything that touches user data.** PII flows through the system along edges — classify them.

---

## Part 12: Cytoscape Shape Reference

Available shapes for `nodeKinds.*.ui.shape`:

| Shape | Best for |
|-------|----------|
| `ellipse` | Actors, components, services, auth |
| `round-rectangle` | UIs, lambdas, CDNs, containers, infrastructure |
| `rectangle` | Boundaries |
| `diamond` | Interfaces, gateways |
| `hexagon` | Datastores |
| `barrel` | Queues |
| `round-tag` | Artifacts |
| `tag` | Labels, annotations |
| `octagon` | Special/custom kinds |
| `star` | Highlighted/important nodes |
| `triangle` | Directional/flow indicators |
| `vee` | Decision points |

---

## Quick Start Checklist

When analyzing a new codebase, produce output in this order:

1. Read `package.json` / equivalent + `docker-compose.yml` + IaC files
2. List actors (who uses this system?)
3. List UI screens (if frontend exists)
4. List backend services/containers
5. List all API endpoints → interface nodes
6. List all databases/caches/stores → datastore nodes
7. List all queues/events → queue nodes
8. List auth providers, gateways, CDNs
9. List trust boundaries
10. Draw all edges (trace every connection in code)
11. Create views (overview, data layer, security)
12. Build schema.yaml (layers, kinds, fields, rules)
13. Build archigraph.yaml (meta, nodes, edges, views, rules)
14. Validate (all IDs resolve, connection rules hold, no orphans)