Architecture Editor

The architecture editor is an interactive visual tool for composing multiple appgrammars into system architecture diagrams. Add appgrammars as nodes, connect them with typed edges, and arrange layouts to document how your systems fit together.

Creating an Architecture

In the web UI, go to My Architectures in the sidebar and click Create. Give it a name (a slug is auto-generated) and optional description.

Via the API:

POST /api/architectures

{
  "name": "E-Commerce Platform",
  "description": "Microservice architecture for our storefront",
  "visibility": "public"
}

Adding Nodes

Each node represents an appgrammar in your architecture. In the editor, click Edit in the header bar to enter edit mode, then click the + button in the toolbar to open the Add Appgrammar modal.

The modal offers two sources:

• Public Registry -- search public appgrammars by name or description
• My Appgrammars -- browse and filter your own appgrammars, including private ones

New nodes are automatically positioned in a grid layout so they don't stack on top of each other.

You can also add nodes via the API:

POST /api/architectures/:slug/nodes

{
  "appgrammar_id": "uuid-of-appgrammar",
  "position_x": 100,
  "position_y": 200
}

Nodes display the appgrammar name, star count, module/step counts, success rate, and a module composition bar showing the relative size of each module.

Removing Nodes

In edit mode, hover over a node to reveal the delete button (red X in the top-right corner). Click it to remove the node from the architecture.

Connecting with Edges

Edges represent relationships between appgrammars. In edit mode, drag from a node's connection handle (the cyan dot at the top or bottom of a node) to another node's handle. An edge type selector will appear where you can choose the connection type and add an optional label.

You can also create edges via the API:

POST /api/architectures/:slug/edges

{
  "source_node_id": "node-uuid-1",
  "target_node_id": "node-uuid-2",
  "edge_type": "api_call",
  "label": "REST /api/orders"
}

Edge Types

Type	Description
api_call	HTTP/gRPC communication between services
event	Event-driven messaging (queues, pub/sub)
shared_db	Shared database access
auth	Authentication/authorization dependency
lineage_fork	Auto-computed fork relationship
lineage_breed	Auto-computed breed relationship
custom	User-defined relationship with custom label

Lineage edges (lineage_fork, lineage_breed) are auto-computed from fork and breed ancestry data and cannot be manually created or deleted.

Deleting Edges

In edit mode, click on any non-lineage edge to delete it after confirmation.

Layout Management

In edit mode, drag nodes to reposition them. Positions are saved automatically when you stop dragging.

You can also batch-update positions via the API:

PUT /api/architectures/:slug/layout

The request body contains an array of { nodeId, position: { x, y } } pairs.

Transferring to a Team

Move an architecture to a team for shared access:

POST /api/architectures/:slug/transfer

{
  "team_id": "team-uuid"
}

Browsing Public Architectures

Anyone can browse public architectures at /architecture without authentication:

GET /api/architectures?limit=20&offset=0

View a specific architecture by slug: GET /api/architectures/:slug.

Zoom Levels

The architecture viewer supports three zoom levels:

• Level 1 (Ecosystem) -- appgrammars as nodes with module composition bars
• Level 2 (Architecture) -- expand into individual modules with dependency edges, auto-laid out via ELK
• Level 3 (Module Detail) -- drill into steps within a module, displayed in swimlanes

For the read-only module graph viewer embedded in appgrammar detail pages, see Architecture Visualization.