# Glasswork

> Transparent Serverless Framework

Build OpenAPI-compliant REST APIs with clean architecture, zero magic, and Lambda-first design.

## Table of Contents

### API Reference

- [API Reference](/api.md): Curated API reference for Glasswork 1.0 subpath exports.

### Getting Started

- [What is Glasswork?](/getting-started/what-is-glasswork.md): Overview of Glasswork — a transparent, serverless-optimized TypeScript framework for OpenAPI-compliant REST APIs, with comparisons to NestJS and Hono.
- [Getting Started](/getting-started/quick-start.md): Step-by-step guide to creating your first Glasswork API, including project setup, modules, routes, services, and running locally.
- [Package Exports](/getting-started/package-exports.md): Glasswork 1.0 package exports — subpath imports for core, HTTP, and optional subsystems.

### Application Structure

- [Modules](/application-structure/modules.md): How to define and compose modules in Glasswork to group services, routes, and dependencies into cohesive units.
- [Dependency Injection](/application-structure/dependency-injection.md): Dependency injection in Glasswork using Awilix, including registering providers, scoped containers, and accessing services.
- [Testing](/application-structure/testing.md): Testing strategies for Glasswork applications, including unit testing services, integration testing routes, and using the test helpers.
- [Transactions Across Modules](/application-structure/transactions.md): One explicit transaction per use case across modules, with Prisma, RLS and audit records that commit or roll back together.
- [Outbox and Inbox](/application-structure/outbox-and-inbox.md): At-least-once publication to SQS and other brokers with a transactional outbox, a relay and an idempotent inbox, as application code.
- [Idempotency Keys](/application-structure/idempotency-keys.md): An Idempotency-Key header that keeps a repeated or concurrent request from changing data twice, with the key and response stored in the transaction of the change.
- [Concurrent Changes](/application-structure/concurrency.md): Optimistic concurrency with versions and If-Match, conditional updates and row locks for invariants, gapless numbers, and which conflicts to retry.

### Request Handling

- [Routes & Validation](/request-handling/routes.md): Defining HTTP routes with type-safe request validation using Valibot schemas for body, query, and path parameters.
- [Middleware](/request-handling/middleware.md): Using Hono middleware in Glasswork for cross-cutting concerns like authentication, logging, CORS, and request modification.
- [Error Handling](/request-handling/error-handling.md): Error handling system that maps domain exceptions to HTTP responses with consistent error formats and proper status codes.
- [OpenAPI](/request-handling/openapi.md): Automatic OpenAPI 3.1 spec generation from Valibot route schemas, including Swagger UI setup and customization options.
- [List Query](/request-handling/list-query.md): Type-safe list query system for building filterable, sortable, and paginated API endpoints with Prisma, global search, aggregations, and CASL.

### Configuration

- [Bootstrap Options](/configuration/bootstrap.md): Bootstrap configuration options for Glasswork applications, including OpenAPI, CORS, logging, and Lambda adapter settings.
- [Environment Config](/configuration/environment-config.md): Type-safe environment configuration with validation, dotenv support, and per-environment overrides.

### Observability

- [Observability](/observability/overview.md): Built-in observability with structured JSON logging (Pino), request correlation, and exception tracking for AWS Lambda and CloudWatch.
- [Logging](/observability/logging.md): Structured logging with Pino, automatic request ID correlation, and CloudWatch Logs Insights integration.
- [Exception Tracking](/observability/exception-tracking.md): Built-in exception tracking with CloudWatch integration, including error context, breadcrumbs, and custom reporters.
- [AppSignal Integration](/observability/appsignal-integration.md): Integrating AppSignal for application monitoring, APM, error triage, and uptime monitoring with Glasswork.
- [CloudWatch Logs Insights Queries](/observability/cloudwatch-insights.md): Useful CloudWatch Logs Insights queries for analyzing structured JSON logs from Pino, including error analysis and latency tracking.
- [CloudWatch Application Signals](/observability/cloudwatch-application-signals.md): AWS CloudWatch Application Signals for native APM on Lambda with automatic OpenTelemetry instrumentation and service dependency maps.

### Email

- [Email Module - Getting Started](/email/getting-started.md): Setting up Glasswork's email module with MJML templates, AWS SES, and the two-pass compilation system.
- [Email Templates Guide](/email/templates.md): Two-pass MJML template compilation system with control flow syntax, type-safe render functions, and responsive email layout.
- [Email Customization Guide](/email/customization.md): Customizing email templates with components, styles, helpers, and branding for consistent transactional emails.
- [AWS Setup Guide](/email/aws-setup.md): AWS CDK setup for SES emails, domain verification, SNS delivery tracking, IAM permissions, and reputation alarms.
- [Email API Reference](/email/api.md): Complete API reference for Glasswork's email module, including TemplatedEmailService, transports, and template compilation.

### Jobs

- [Background Jobs](/jobs/getting-started.md): Getting started with background jobs in Glasswork, including defining, enqueueing, and processing jobs with SQS and Lambda.
- [Defining Jobs](/jobs/defining-jobs.md): Defining type-safe jobs with the defineJob helper, including payload schemas, configuration options, and handler functions.
- [Workers](/jobs/workers.md): Lambda-based workers that process background jobs from SQS queues, including setup, batch processing, and concurrency.
- [Worker Observability](/jobs/observability.md): Automatic per-attempt CloudWatch EMF metrics from Glasswork workers, with application-owned CDK dashboards and alarms.
- [Dispatching & Scheduling](/jobs/dispatching.md): Enqueueing jobs immediately, with delays, or at specific times using the JobService, plus cron-based scheduling with EventBridge.
- [Error Handling & Retries](/jobs/error-handling.md): Job error handling and retry system with SQS integration, configurable retry policies, dead letter queues, and per-job retry behavior.
- [AWS Setup Guide](/jobs/aws-setup.md): AWS CDK infrastructure in TypeScript for SQS queues, Lambda workers, dead-letter queues, and EventBridge Scheduler.
- [Best Practices](/jobs/best-practices.md): Best practices for reliable background jobs, including idempotency, payload design, error handling, and monitoring strategies.
- [Testing](/jobs/testing.md): Testing background jobs with MockQueueDriver, unit testing enqueuing, and verifying job payloads.

### Auth

- [Authentication - Getting Started](/auth/getting-started.md): Setting up authentication with Better Auth and authorization with CASL for type-safe, role-based access control.
- [Abilities (CASL)](/auth/abilities.md): Defining abilities with CASL for fine-grained, role-based authorization including Prisma query filtering and field-level permissions.
- [Auth Middleware](/auth/middleware.md): Auth middleware for protecting routes, requiring authentication, and injecting session and user context into request handlers.
- [OpenAPI Integration](/auth/openapi.md): Documenting auth requirements in OpenAPI specs with security schemes, bearer tokens, and per-route security annotations.
- [Row Level Security](/auth/row-level-security.md): Tenant isolation with PostgreSQL RLS, Prisma Client Extensions, and transaction-scoped context.
- [Testing Auth](/auth/testing.md): Testing authentication and authorization in Glasswork, including mocking sessions, testing abilities, and integration testing protected routes.

### Deployment

- [Production Readiness](/deployment/production-readiness.md): Production readiness checklist for Glasswork applications, covering security, performance, monitoring, and deployment preparation.
- [Lambda Deployment](/deployment/lambda.md): Deploying Glasswork to AWS Lambda with AWS CDK in TypeScript, including ESM bundling, Function URLs, and alternative deployment tools.
- [Node.js Server](/deployment/node.md): Running a Glasswork application as a long-running Node.js server, for containers and hosts other than Lambda.

### Uploads

- [Uploads Module - Getting Started](/uploads/getting-started.md): Secure S3 presigned URL file uploads optimized for serverless, bypassing Lambda body size limits with direct-to-S3 uploads.
- [Malware Scanning with GuardDuty](/uploads/malware-scanning.md): Read GuardDuty malware scan results and finalize the same checked S3 object version.

### Server-Sent Events

- [Server-Sent Events](/sse/getting-started.md): Server-sent event notifications in Glasswork, with setup, reconnect behavior, and deployment limitations.

### Architecture

- [The Transparency Principle](/architecture/transparency.md): The transparency principle — how Glasswork provides direct access to underlying libraries without heavy abstractions.
- [Architecture Philosophy](/architecture/philosophy.md): Glasswork's architecture philosophy — separating services, routes, and modules for clean, testable, serverless-first design.