Architecture

drive-apig is a Serverless Framework monorepo of 18 deployable services sharing one Terraform-managed API Gateway REST API. API keys, usage plans, WAF, SSM, and telemetry are centralized; route ownership remains per service.

Topology

flowchart LR
  Client[Browser / App / Partner] --> AGW[API Gateway REST API]
  AGW --> WAF[WAF stage association]
  AGW -->|route| S1[leads]
  AGW -->|route| S2[marketplace]
  AGW -->|route| S3[geo]
  AGW -->|route| SN[other services]
  S1 --> DDB[(DynamoDB)]
  S1 --> SQS[(SQS)]
  S1 --> SF[Salesforce / Carsales / AHG]
  S2 --> LLM[OpenRouter / Portkey]
  SN --> TAIL[Tailpipe / Carsforsale GraphQL]

Principles

• One shared REST API. Terraform creates the API Gateway REST API and publishes ids to SSM. Services read those ids and attach their own resources/methods.
• Per-service stacks. Each services/<name> folder with a serverless.yml is independently packaged and deployed. Shared config in serverless.common.yml is included via YAML ${file(...)}; there is no inheritance unless a section is explicitly included.
• API key auth by method. API key enforcement is controlled by each HTTP event's private flag. Public routes must set private: false.
• Event-driven workers are first-class. SQS/SNS/EventBridge workers are documented, but not described as deployed HTTP unless API Gateway mounts them. Local replay harnesses are marked in OpenAPI.
• Shared observability. Every service includes shared logging, OpenTelemetry env vars, and collector config unless it deliberately overrides them.

Pages

Service inventory: Services. Each documented HTTP or local-harness contract lives in docs/site/openapi/<service>.yaml.