# alexa/skill-components architecture

> Architecture diagram of the GitHub repository alexa/skill-components, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexa/skill-components
- Repository: https://github.com/alexa/skill-components

## Overview

Alexa Skill Components is a collection of reusable Alexa skill experiences, implemented here as separate TypeScript Lambda components. The principal runtime pattern is an Alexa request reaching a component handler, which performs a domain operation and returns a skill response; catalog search and item selection also use provider and session-state abstractions. The README documents feedback, catalog exploration, list navigation, account linking, in-skill purchases, and checkout. Scheduling is present in the tree as a further booking workflow. Source excerpts are partial, so edges are limited to documented or indexed relationships; unsampled handler wiring is not inferred.

Main entry points: [`catalog-explorer/lambda/interface.ts`](https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/interface.ts) (Catalog APIs), [`scheduling/lambda/handlers`](https://github.com/alexa/skill-components/tree/main/scheduling/lambda/handlers) (Booking handlers), [`checkout/lambda/handlers`](https://github.com/alexa/skill-components/tree/main/checkout/lambda/handlers) (Checkout handlers), [`list-navigation/lambda/handlers/base-api-handler.ts`](https://github.com/alexa/skill-components/blob/main/list-navigation/lambda/handlers/base-api-handler.ts) (List APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog exploration"]
  node_catalog_api["Catalog APIs<br/>[interface.ts]"]
  node_catalog_search["Search handler<br/>[search-handler.ts]"]
  node_catalog_select["Item selection"]
  node_catalog_provider["Catalog provider"]
  node_catalog_state["Catalog session<br/>[state.ts]"]
end

subgraph group_navigation["List navigation"]
  node_list_api["List APIs"]
  node_list_state["List session<br/>[session-state.ts]"]
end

subgraph group_commerce["Commerce"]
  node_checkout_api["Checkout handlers"]
  node_checkout_provider["Checkout provider"]
  node_purchase_flow["Purchase handlers"]
end

subgraph group_booking["Scheduling"]
  node_booking_api["Booking handlers"]
  node_booking_provider["Scheduling provider<br/>[provider.ts]"]
  node_booking_state["Scheduling session<br/>[state.ts]"]
end

subgraph group_account["Account linking"]
  node_account_link["Account linking"]
end

subgraph group_feedback["Feedback"]
  node_feedback_handler["Save rating"]
  node_rating_recorder["Rating recorder<br/>[rating-recorder.ts]"]
  node_log_recorder["Log recorder"]
end

node_skill_user(("Skill user"))
node_skill_dev(("Skill developer"))

node_skill_dev -->|"imports component"| node_catalog_api
node_skill_dev -->|"imports component"| node_list_api
node_skill_dev -->|"imports component"| node_checkout_api
node_skill_dev -->|"imports component"| node_purchase_flow
node_skill_dev -->|"imports component"| node_account_link
node_skill_dev -->|"imports component"| node_feedback_handler
node_skill_user -.->|"uses experience"| node_catalog_api
node_skill_user -.->|"uses experience"| node_list_api
node_skill_user -.->|"uses experience"| node_checkout_api
node_skill_user -.->|"uses experience"| node_purchase_flow
node_skill_user -.->|"uses experience"| node_account_link
node_skill_user -.->|"uses experience"| node_feedback_handler
node_skill_user -.->|"uses booking"| node_booking_api
node_catalog_api -->|"registers handler"| node_catalog_search
node_catalog_api -->|"registers handler"| node_catalog_select
node_catalog_search -->|"searches catalog"| node_catalog_provider
node_catalog_search -->|"saves session"| node_catalog_state
node_catalog_select -->|"selects item"| node_catalog_provider
node_catalog_api -->|"saves state"| node_catalog_state
node_list_api -->|"loads session"| node_list_state
node_checkout_api -->|"calls provider"| node_checkout_provider
node_checkout_api -->|"validates order"| node_checkout_provider
node_booking_api -->|"booking operations"| node_booking_provider
node_booking_api -->|"loads session"| node_booking_state
node_booking_api -->|"uses list navigation"| node_list_api
node_feedback_handler -->|"records rating"| node_rating_recorder
node_log_recorder -->|"implements"| node_rating_recorder

click node_catalog_api "https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/interface.ts"
click node_catalog_search "https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/handlers/search-handler.ts"
click node_catalog_select "https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/handlers/select-item-handler.ts"
click node_catalog_provider "https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/catalog-provider.ts"
click node_catalog_state "https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/state.ts"
click node_list_api "https://github.com/alexa/skill-components/blob/main/list-navigation/lambda/handlers/base-api-handler.ts"
click node_list_state "https://github.com/alexa/skill-components/blob/main/list-navigation/lambda/session-state.ts"
click node_checkout_api "https://github.com/alexa/skill-components/tree/main/checkout/lambda/handlers"
click node_checkout_provider "https://github.com/alexa/skill-components/blob/main/checkout/lambda/checkout-provider.ts"
click node_purchase_flow "https://github.com/alexa/skill-components/tree/main/in-skill-purchase/lambda/handlers"
click node_booking_api "https://github.com/alexa/skill-components/tree/main/scheduling/lambda/handlers"
click node_booking_provider "https://github.com/alexa/skill-components/blob/main/scheduling/lambda/provider.ts"
click node_booking_state "https://github.com/alexa/skill-components/blob/main/scheduling/lambda/state.ts"
click node_account_link "https://github.com/alexa/skill-components/blob/main/account-linking/lambda/get-account-linking-details-handler.ts"
click node_feedback_handler "https://github.com/alexa/skill-components/blob/main/feedback-elicitation/lambda/handlers/save-rating-handler.ts"
click node_rating_recorder "https://github.com/alexa/skill-components/blob/main/feedback-elicitation/lambda/recorders/rating-recorder.ts"
click node_log_recorder "https://github.com/alexa/skill-components/blob/main/feedback-elicitation/lambda/recorders/log-rating-recorder.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_catalog_api,node_catalog_search,node_catalog_select,node_catalog_provider,node_catalog_state,node_skill_user toneBlue
class node_list_api,node_list_state toneAmber
class node_checkout_api,node_checkout_provider,node_purchase_flow toneMint
class node_booking_api,node_booking_provider,node_booking_state toneRose
class node_account_link,node_skill_dev toneIndigo
class node_feedback_handler,node_rating_recorder,node_log_recorder toneTeal
```

## Components

### Catalog exploration

- [Catalog APIs](https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/interface.ts): `catalog-explorer/lambda/interface.ts`
- [Search handler](https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/handlers/search-handler.ts): `catalog-explorer/lambda/handlers/search-handler.ts`
- [Item selection](https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/handlers/select-item-handler.ts): `catalog-explorer/lambda/handlers/select-item-handler.ts`
- [Catalog provider](https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/catalog-provider.ts): `catalog-explorer/lambda/catalog-provider.ts`
- [Catalog session](https://github.com/alexa/skill-components/blob/main/catalog-explorer/lambda/state.ts): `catalog-explorer/lambda/state.ts`

### List navigation

- [List APIs](https://github.com/alexa/skill-components/blob/main/list-navigation/lambda/handlers/base-api-handler.ts): `list-navigation/lambda/handlers/base-api-handler.ts`
- [List session](https://github.com/alexa/skill-components/blob/main/list-navigation/lambda/session-state.ts): `list-navigation/lambda/session-state.ts`

### Commerce

- [Checkout handlers](https://github.com/alexa/skill-components/tree/main/checkout/lambda/handlers): `checkout/lambda/handlers`
- [Checkout provider](https://github.com/alexa/skill-components/blob/main/checkout/lambda/checkout-provider.ts): `checkout/lambda/checkout-provider.ts`
- [Purchase handlers](https://github.com/alexa/skill-components/tree/main/in-skill-purchase/lambda/handlers): `in-skill-purchase/lambda/handlers`

### Scheduling

- [Booking handlers](https://github.com/alexa/skill-components/tree/main/scheduling/lambda/handlers): `scheduling/lambda/handlers`
- [Scheduling provider](https://github.com/alexa/skill-components/blob/main/scheduling/lambda/provider.ts): `scheduling/lambda/provider.ts`
- [Scheduling session](https://github.com/alexa/skill-components/blob/main/scheduling/lambda/state.ts): `scheduling/lambda/state.ts`

### Account linking

- [Account linking](https://github.com/alexa/skill-components/blob/main/account-linking/lambda/get-account-linking-details-handler.ts): `account-linking/lambda/get-account-linking-details-handler.ts`

### Feedback

- [Save rating](https://github.com/alexa/skill-components/blob/main/feedback-elicitation/lambda/handlers/save-rating-handler.ts): `feedback-elicitation/lambda/handlers/save-rating-handler.ts`
- [Rating recorder](https://github.com/alexa/skill-components/blob/main/feedback-elicitation/lambda/recorders/rating-recorder.ts): `feedback-elicitation/lambda/recorders/rating-recorder.ts`
- [Log recorder](https://github.com/alexa/skill-components/blob/main/feedback-elicitation/lambda/recorders/log-rating-recorder.ts): `feedback-elicitation/lambda/recorders/log-rating-recorder.ts`

### Other components

- **Skill user**
- **Skill developer**

## Connections

- Skill developer → Catalog APIs: imports component (evidence: `README.md`)
- Skill developer → List APIs: imports component (evidence: `README.md`)
- Skill developer → Checkout handlers: imports component (evidence: `README.md`)
- Skill developer → Purchase handlers: imports component (evidence: `README.md`)
- Skill developer → Account linking: imports component (evidence: `README.md`)
- Skill developer → Save rating: imports component (evidence: `README.md`)
- Skill user → Catalog APIs: uses experience (evidence: `README.md`)
- Skill user → List APIs: uses experience (evidence: `README.md`)
- Skill user → Checkout handlers: uses experience (evidence: `README.md`)
- Skill user → Purchase handlers: uses experience (evidence: `README.md`)
- Skill user → Account linking: uses experience (evidence: `README.md`)
- Skill user → Save rating: uses experience (evidence: `README.md`)
- Skill user → Booking handlers: uses booking
- Catalog APIs → Search handler: registers handler (evidence: `catalog-explorer/lambda/interface.ts`)
- Catalog APIs → Item selection: registers handler (evidence: `catalog-explorer/lambda/interface.ts`)
- Search handler → Catalog provider: searches catalog (evidence: `catalog-explorer/lambda/handlers/search-handler.ts`)
- Search handler → Catalog session: saves session (evidence: `catalog-explorer/lambda/handlers/search-handler.ts`)
- Item selection → Catalog provider: selects item (evidence: `catalog-explorer/lambda/handlers/select-item-handler.ts`)
- Catalog APIs → Catalog session: saves state (evidence: `catalog-explorer/lambda/interface.ts`)
- List APIs → List session: loads session (evidence: `list-navigation/lambda/handlers/base-api-handler.ts`)
- Checkout handlers → Checkout provider: calls provider (evidence: `checkout/lambda/handlers/checkout-handler.ts`)
- Checkout handlers → Checkout provider: validates order (evidence: `checkout/lambda/handlers/validate-order-handler.ts`)
- Booking handlers → Scheduling provider: booking operations (evidence: `scheduling/lambda/handlers/cancel-booking-handler.ts`)
- Booking handlers → Scheduling session: loads session (evidence: `scheduling/lambda/handlers/cancel-booking-handler.ts`)
- Booking handlers → List APIs: uses list navigation
- Save rating → Rating recorder: records rating (evidence: `feedback-elicitation/lambda/handlers/save-rating-handler.ts`)
- Log recorder → Rating recorder: implements (evidence: `feedback-elicitation/lambda/recorders/log-rating-recorder.ts`)
