Arc guide

Write the architecture you intend.

An Arc is a versioned YAML file in your GitHub repository. It describes intended components, their relationships, and the requirements Astory should evaluate against observed code.

Give your coding agent the instructions.

The public JSON endpoint includes the authoring contract, a complete YAML example, identity mapping rules, and validation steps. It can be fetched by an agent or an MCP HTTP tool without signing in.

Read agent instructions (JSON) ↗

Read https://astory.dev/api/arc/instructions and follow it to author an Arc for this repository’s architecture goal. Inspect existing Arc versions first. Use exact observed IDs from Astory; ask me for missing mappings rather than inventing them.

1. Scan your repository and choose a target.

Use the current architecture as your starting point. Select a graph node and open Arc mapping IDs in its source inspector. An existing service needs its exact service ID in observed_id. A new component can remain unmapped until the scanner observes it.

2. Add an Arc file to a branch.

Create .astory/arcs/order-flow/001.yaml. The directory must match arc.id, and the filename number must match arc.version. This example asks an existing API to publish to an SQS queue.

Replace service:OWNER/REPOSITORY:. with the exact service ID from your scan. Names alone do not establish a match. system: aws-sqs lets Astory match a uniquely observed SQS queue.

Download example YAML

schema_version: 1
arc:
  id: order-flow
  name: Order Flow
  version: 1
  predecessor: null
base:
  type: empty
operations:
  - type: add_entity
    id: api
    entity_type: service
    name: Orders API
    observed_id: service:OWNER/REPOSITORY:.
  - type: add_entity
    id: orders
    entity_type: queue
    name: Orders Queue
    system: aws-sqs
  - type: add_relationship
    id: publish-orders
    from: api
    to: orders
    relationship_type: publishes
requirements:
  - id: orders-are-published
    type: architecture
    required: true
    relationship:
      from: api
      to: orders
      type: publishes

3. Scan the branch through a pull request.

Commit the file and open or update a pull request. With the Astory GitHub App installed, the signed PR webhook prepares a comparison. You can also select the PR in Astory and scan it manually. Choose Order Flow · v1 from Arc overlay to inspect the intended architecture and requirement results.

Dotted nodes represent intended entities that have not been matched. A detached proposed service means it lacks an observed mapping; it does not prove your running application is disconnected. Matched entities reuse the observed graph. Inspect the evidence behind each requirement’s state.

4. Keep each version immutable.

When the intent changes, add 002.yaml with version: 2 and predecessor: 1. Keep the first file unchanged. Each example with base: {type: empty} describes its complete intended target. The current product scan does not resolve observed snapshot bases.

Architecture and code-change requirements

The example’s architecture requirement checks for the API → queue publishes relationship. To check implementation changes, add a code_change requirement with paths and/or symbols, plus a top-level source_base: {commit: FULL_40_CHARACTER_BASE_SHA}. Use the immutable commit before the implementation change. A requirement needs source evidence; adding YAML does not satisfy it by itself.

What AWS infrastructure can the scanner recognize?

The default scanner recognizes concrete SDK calls in JavaScript/TypeScript, Python (boto3), and Java. Coverage depends on the source pattern; these are inferred dependencies with source evidence.

System	Observed operations	Arc system
Amazon S3	Object reads and writes	`aws-s3`
DynamoDB	Item reads and writes	`aws-dynamodb`
Amazon SNS	Publishing messages	`aws-sns`
Amazon SQS	Publishing and consuming messages	`aws-sqs`

It does not inventory your AWS account or reconstruct deployed VPC, EC2, ECS, RDS, or Lambda topology from infrastructure configuration. Dynamic client construction, wrappers, and resource names may be unresolved. The current graph can group calls by AWS system rather than distinguish every bucket, table, or queue.

Open Astory