Graph Schema¶

Every cloud resource is a CRN-keyed node. Every relationship is a typed edge. Here is the full schema.

Node Schema¶

Every cloud resource is a Node in the graph. The canonical in-memory representation:

Edge Types¶

Edges are typed directed relationships between nodes. The EdgeRelationship enum:

Example Subgraph¶

ec2:instance (i-0abc123)
    ├── SecuredBy → ec2:security-group (sg-0aaa)
    ├── AttachedTo → ebs:volume (vol-0bbb)
    └── Uses → rds:instance (db-prod)
               └── SecuredBy → ec2:security-group (sg-rds)

The Ghost Linker discovers cross-provider edges that no individual plugin can see. For example, a K8s pod's CIDR range overlapping an AWS VPC peering route.

FlatBuffers Specification¶

The graph is serialized using FlatBuffers for zero-copy inter-process transport between the daemon and plugins:

// pkg/graph/graph.fbs
namespace CloudSlash.Graph;

enum EdgeRelationship : byte {
    AttachedTo = 0,
    SecuredBy  = 1,
    Contains   = 2,
    Runs       = 3,
    FlowsTo    = 4,
    Grants     = 5,
    Uses       = 6
}

table Property {
    key:   string;
    value: string;
}

table Node {
    crn:                string (required, key);
    type:               string (required);
    state:              string;
    cost_usd_mo:        float32;
    properties:         [Property];
    creation_timestamp: uint64;
    valid_to:           uint64;   // 0 = active; >0 = logically deleted
}

table Edge {
    source_crn:   string (required);
    target_crn:   string (required);
    relationship: EdgeRelationship;
    properties:   [Property];
    valid_to:     uint64;         // s.a.u isolation boundary
}

table Graph {
    nodes:        [Node];
    edges:        [Edge];
    version:      uint32;
    last_updated: uint64;
}

root_type Graph;

CRN Format¶

The CloudSlash Resource Name (CRN) provides a stable, globally unique identifier for every resource. It is the graph node key, audit ledger key, and history API key.

crn:devi:<provider>:<region>:<service>:<type>:<account_id>:<physical_id>

Examples¶

CRNs are deterministic. The same physical resource always produces the same CRN across scans. This stability is essential for time-travel queries and audit trail correlation.

Temporal Air-Gapping¶

s.a.u does not delete nodes from the graph when resources are removed. It uses logical deletion via the valid_to timestamp:

// When a resource is deleted or purged:
node.valid_to = time.Now().UnixMicro()

All graph traversals filter using:

node.valid_to == 0 || node.valid_to > time.Now().UnixMicro()

Logically deleted nodes remain in the BadgerDB temporal store. This enables time-travel queries (cs diff) and forensic attribution long after the physical resource is gone.

Concurrency Model¶

The graph uses a double-sharded, lock-striped design for high-throughput concurrent writes:

• Node shards: 256 shards keyed by CRN hash. Each shard has its own sync.RWMutex.
• Edge shards: 128 shards keyed by (source_crn + relationship) hash.
• Writer pool: The Swarm AIMD orchestrator sizes the plugin RPC worker pool to runtime.NumCPU().
• Boundary resolution pool: Ghost Linker uses a separate pool of NumCPU workers with an 8192-capacity channel for cross-provider edge discovery.

This design eliminates global lock contention. It allows ingestion of tens of thousands of nodes per second from concurrent plugin streams.

Querying the Graph¶

DEVI AI¶

Natural Language

> Which EC2 instances in us-east-1 have been idle for over 90 days?
> Show all resources with risk_score > 80
> What would break if I deleted the NAT gateway?

Via REST API¶

# List all nodes (paginated)
GET http://localhost:8080/api/v1/graph/nodes?limit=100&provider=aws

# Get a specific node by CRN
GET http://localhost:8080/api/v1/graph/nodes/crn:devi:aws:us-east-1:ec2:instance:123:i-0abc123

# Get a node's edges (neighbors)
GET http://localhost:8080/api/v1/graph/nodes/crn:devi:aws:us-east-1:ec2:instance:123:i-0abc123/edges

# Graph statistics
GET http://localhost:8080/api/v1/graph/stats

Example Stats Response¶

{
  "total_nodes": 10420,
  "active_nodes": 10398,
  "logically_deleted": 22,
  "total_edges": 34102,
  "waste_nodes": 847,
  "total_cost_usd_mo": 142300.0,
  "projected_savings_usd_mo": 14230.0,
  "providers": {
    "aws": 7840,
    "k8s": 1920,
    "gcp": 658
  }
}