Architecture Overview
The Earthquake Data Platform is built on AWS serverless architecture, providing scalable earthquake data ingestion, querying, and analytics.
System Architecture
Query Flow Sequence
Database Schema
The platform uses a single DynamoDB table with composite keys, a time-ordered GSI, and TTL-driven log retention. The schema below captures every attribute, key pattern, and access strategy referenced by our ingestion and query services.
Visual Schema
Single-table design with GSI and access patterns
Table Configuration
Physical layout
- Table Name
- earthquake-events
- Billing Mode
- On-demand (PAY_PER_REQUEST)
- Region
- us-east-1 (LocalStack / AWS)
- Primary Key
- pk (partition key), sk (sort key)
- Entities
- Earthquake events, request logs
- TTL Attribute
- ttl (epoch seconds)
TimeOrderedIndex
Global secondary index
- Index Name
- TimeOrderedIndex
- Purpose
- Query events by day bucket
- Partition Key
- gsi1pk (DAY#YYYYMMDD)
- Sort Key
- gsi1sk (eventTsMs)
- Projection
- ALL attributes
Earthquake Event Entity
Immutable seismic event records
Attributes
| Field | Type | Requirement | Notes |
|---|---|---|---|
| pk | String | Required | EVENT#<usgsEventId> composite identifier |
| sk | String | Required | Literal EVENT for scoped queries |
| entity | String | Required | Always EVENT for type guards |
| eventId | String | Required | USGS event identifier (<= 64 chars) |
| eventTsMs | Number | Required | Event timestamp (epoch ms) |
| mag | Number | Required | Magnitude clamped to -2.0 .. 10.0 |
| place | String | Required | Human-readable location (<= 512 chars) |
| lat | Number | Required | Latitude -90 .. 90 |
| lon | Number | Required | Longitude -180 .. 180 |
| depth | Number | null | Optional | Depth in km (non-negative) |
| dayBucket | String | Required | YYYYMMDD derived from eventTsMs |
| gsi1pk | String | Required | DAY#<dayBucket> partition for GSI |
| gsi1sk | Number | Required | eventTsMs reused as GSI sort key |
| source | String | Required | Data source (USGS) |
| ingestedAt | Number | Required | Ingestion timestamp (epoch ms) |
Request Log Entity
Operational telemetry for ingestion/query endpoints
Attributes
| Field | Type | Requirement | Notes |
|---|---|---|---|
| pk | String | Required | LOG#<YYYYMMDD> day bucket |
| sk | String | Required | <epochMs>#<requestId> composite sorter |
| entity | String | Required | Always LOG |
| logType | String | Required | INGEST or QUERY |
| requestId | String | Required | UUID v4 for traceability |
| timestamp | Number | Required | Request start time (epoch ms) |
| route | String | Required | API path (/ingest/recent, /earthquakes, etc.) |
| status | Number | Required | HTTP status code (200-599) |
| latencyMs | Number | Required | End-to-end latency |
| fetched | Number | Optional | Events fetched from upstream (INGEST) |
| upserted | Number | Optional | Events inserted (INGEST) |
| skipped | Number | Optional | Duplicates filtered (INGEST) |
| retries | Number | Optional | Retry attempts |
| upstreamSize | Number | Optional | USGS payload size in bytes |
| upstreamHash | String | Optional | SHA-256 fingerprint of upstream payload |
| starttime | Number | Optional | Query parameter, epoch ms |
| endtime | Number | Optional | Query parameter, epoch ms |
| minmagnitude | Number | Optional | Query parameter, magnitude floor |
| pageSize | Number | Optional | Page size used for query |
| resultCount | Number | Optional | Returned items for the page |
| hasNextToken | Boolean | Optional | Indicates paginated response |
| bucketsScanned | Number | Optional | Day buckets traversed during query |
| error | String | Optional | Stable error code for failures |
| ttl | Number | Required | Expiration timestamp (now + 7 days) |
Canonical Access Patterns
How services interact with the table
Insert Event (Idempotent)
PutItem with condition attribute_not_exists(pk) to prevent duplicates during ingestion.
Query Events by Day
Query TimeOrderedIndex with gsi1pk = DAY#YYYYMMDD and gsi1sk BETWEEN bounds; filter on magnitude if needed.
Insert Request Log
Unconditional PutItem scoped by LOG#YYYYMMDD partition; ttl controls retention.
Query Request Logs
Query base table where pk = LOG#YYYYMMDD to inspect ingestion or query activity.
API Reference
Interactive documentation for all API endpoints
Loading API Documentation...