Overview

Overview

Welcome to Firefly, Amazon Music’s GraphQL aggregation service.

Firefly unifies Amazon Music APIs for first and third party clients, providing a consistent experience across services, faster response times via caching, and built-in query optimization. Currently integrated with Artist, Album, Track, Playlist, Podcast, Likes, and Search data.

Quick Start

New to Firefly? Try your first query in minutes with the Quick Start Guide.

Onboarding Guides

Developers

• Developer Onboarding - Set up your development environment

• Local Development - Run Firefly locally with hot reloading

• Deployed Dev Stack - Deploy your own AWS instance

Integrations

• Client Onboarding - Connect your application to Firefly

• Service Onboarding - Expose your service through Firefly

Tools & Testing

• Insomnia Setup - Configure Insomnia for GraphQL testing

• Query Examples - Common query patterns and examples

Development

Contributing

• Contributing Guidelines - How to contribute to Firefly

• Merge Review Process - Code review and pipeline process

• Development Guidelines - Core development practices

Architecture

• Data Modeling Guide - Schema design best practices

• Schema Design Process - How schema changes are reviewed

Operations

Monitoring & Debugging

• Monitoring Guide - Observability and alerting

• Cache Debugging - Troubleshoot caching issues

• On-Call Runbook - Incident response procedures

Troubleshooting

• Troubleshooting Guide - Common issues and solutions

• Common Error Codes - Quick error reference

Code Structure

src/
├── authorizer/          # Authorization Lambda for validating calls
├── daos/                # Data Access Objects for downstream dependencies
├── decorators/          # Annotation functions used throughout service
├── handlers/            # Lambda entry points
│   ├── graphql.ts       # GraphQL API entrypoints
│   └── graphqlCore.ts   # GraphQL resolution service (internal)
├── models/              # Data models and GraphQL types
├── resolvers/           # GraphQL root and field resolver classes
├── transformers/        # Convert downstream data to Firefly schema
└── utils/               # Utility classes and functions

Getting Help

Support Channels

• Slack: #music-firefly-interest

• Sage: Firefly Q&A

Engagement Model

For feature requests, service integration, design help, or schema changes, see our Engagement Model.

External Resources

• GraphQL Learning: GraphQL Foundation Learn Section

• GraphQL Console: Firefly GraphQL Explorer