Linear Reference Architecture

Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Production-grade architectural patterns for Linear integrations. Covers simple, service-oriented, event-driven, and CQRS architectures.

Prerequisites

• Understanding of distributed systems
• Experience with cloud infrastructure
• Familiarity with event-driven architecture

Instructions

Step 1: Choose Architecture Pattern

Step 2: Implement Core Components

1. Linear Gateway - Centralized API access with rate limiting and caching
2. Webhook Ingester - Receive and validate Linear webhook events
3. Event Processor - Apply business logic to incoming events
4. State Store - Persist synchronized data locally

Step 3: Configure Infrastructure

• Set up caching layer (Redis for multi-service, in-memory for simple)
• Configure rate limiting (stay under 1500 req/min Linear limit)
• Deploy webhook endpoint with signature verification
• Set up monitoring and health checks

See detailed implementation for full code examples of all four architecture patterns plus project structure.

Output

• Architecture pattern selected and justified
• Core infrastructure components configured
• Rate limiting and caching in place
• Webhook handling operational

Error Handling

Examples

Quick Start: Simple Integration

import { LinearClient } from "@linear/sdk";

const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY! });
const teams = await client.teams();
console.log(teams.nodes.map(t => t.name));

Resources

• Linear API Best Practices
• Event-Driven Architecture
• CQRS Pattern

Next Steps

Configure multi-environment setup with linear-multi-env-setup.