DynamoDB Graph Metadata Schema
This table stores metadata and indexing information for AppLens graph runs. The full graph structure (nodes and edges) is stored in S3.
DynamoDB is used strictly for:
- Run tracking
- Status management
- Fast querying (by user, run, environment)
- Linking to S3 artifacts
- Storing summary statistics
Table Name
applens-graph-metadata
Primary Key Design
| Attribute | Type | Example |
|---|---|---|
PK |
String | USER#12345 |
SK |
String | RUN#2026-02-22T19:12:11Z#c8a91e |
Key Pattern
PK = USER#<userId>
SK = RUN#<timestamp>#<runId>
This allows:
- Query all runs for a user
- Retrieve latest run efficiently
- Maintain chronological ordering
Core Attributes
| Attribute | Type | Description |
|---|---|---|
runId |
String | Unique identifier for this graph run |
status |
String | UPLOADED, PROCESSING, COMPLETE, FAILED |
environment |
String | dev or prod |
createdAt |
ISO 8601 String | Timestamp of run creation |
updatedAt |
ISO 8601 String | Last status update |
graphS3Key |
String | S3 key for full graph JSON |
iacS3Key |
String | S3 key for uploaded IaC file |
analysisS3Key |
String | S3 key for risk report output |
Summary Fields (Precomputed)
These allow fast dashboard rendering without loading the full graph.
| Attribute | Type | Description |
|---|---|---|
nodeCount |
Number | Total nodes |
edgeCount |
Number | Total edges |
internetExposedCount |
Number | Public-facing services |
datastoreCount |
Number | Number of storage services |
graphHash |
String | SHA-256 hash of canonical graph JSON |
Optional Provenance Metadata
| Attribute | Type | Description |
|---|---|---|
iacCommitSha |
String | Git commit of Terraform source |
terraformWorkspace |
String | Terraform workspace |
accountId |
String | AWS account ID |
region |
String | Primary region of graph |
Example Item
{
"PK": "USER#12345",
"SK": "RUN#2026-02-22T19:12:11Z#c8a91e",
"runId": "c8a91e",
"status": "COMPLETE",
"environment": "prod",
"createdAt": "2026-02-22T19:12:11Z",
"updatedAt": "2026-02-22T19:13:02Z",
"graphS3Key": "graphs/prod/12345/c8a91e/graph.json",
"iacS3Key": "uploads/prod/12345/main.tf.json",
"analysisS3Key": "reports/prod/12345/c8a91e/risk.json",
"nodeCount": 42,
"edgeCount": 67,
"internetExposedCount": 2,
"datastoreCount": 4,
"graphHash": "sha256:abc123..."
}
Recommended GSIs
GSI1 — Lookup by runId
| Attribute | Value |
|---|---|
GSI1PK |
RUN#<runId> |
GSI1SK |
USER#<userId> |
Allows:
- Resolve run from asynchronous Lambda callback
- Direct lookup when only runId is known
Design Principles
- DynamoDB stores indexes and metadata only
- Large graph payloads remain in S3
- Graph JSON is immutable per run
- Metadata supports fast dashboard and orchestration queries
- Additive schema changes preferred over breaking changes