Islets

Event-driven infrastructure and SDKs for webhooks, messaging, and platform services.

Quick Start

Install CLI

Quick Install (End Users):

curl -fsSL https://get-islets.soupilar.com.br/install.sh | sh

Development Install:

cd cli
pip install -e .

Create a Service

islets new service --name="scorekeeper" --team="scoring-team"

Add Event Consumer

cd scorekeeper
islets new consumer --service="scorekeeper" --event="listing.sold"

Deploy

make deploy

Project Structure

islets/
├── cli/                       # Islets CLI tool (service scaffolding)
│   ├── src/islets_cli/       # CLI implementation
│   └── README.md             # CLI documentation
├── pyslets/                   # Python SDK
│   ├── src/pyslets/          # SDK implementation
│   │   ├── events.py         # Event classes
│   │   ├── config.py         # Configuration
│   │   └── pulumi_components/ # Reusable Pulumi components
│   └── README.md             # SDK documentation
├── events/                    # Language-agnostic event schemas
│   ├── listing.yaml          # Listing events
│   ├── company.yaml          # Company events
│   └── README.md             # Event schema documentation
├── services/                  # Service registry
│   ├── scorekeeper.yaml      # Service definitions
│   └── listing-management.yaml
├── infra/                     # Platform infrastructure (Pulumi)
│   ├── topics.py             # SNS topics
│   ├── webhooks.py           # Webhook infrastructure
│   └── code_bucket.py        # Lambda deployment bucket
└── scripts/                   # Utility scripts
    └── test_deployed_webhook.py

Components

Islets CLI

Command-line tool for scaffolding event-driven services.

Installation:

cd cli
pip install -e .

Usage:

# Create a new service
islets new service --name="myservice" --team="myteam"

# Add a consumer
cd myservice
islets new consumer --service="myservice" --event="listing.sold"

See cli/README.md for full documentation.

Events SDK (pyslets.events)

Dynamically generated, type-safe domain event classes with automatic SNS publishing.

Features: - Event classes auto-generated from YAML schemas at module load time - Pydantic validation for type safety - Built-in SNS publishing with topic ARN resolution - Language-agnostic schemas (shared across SDKs)

Usage:

from pyslets.events import ListingSold

# Create and publish event
event = ListingSold(
    listing_id="listing-123",
    sold_price=500000.00,
    sold_date="2026-02-12T10:00:00Z",
    agent_id="agent-456"
)
message_id = event.publish()  # Auto-publishes to listing-events topic

# Or with custom configuration
from pyslets.events import EventPublisher

publisher = EventPublisher(
    region_name="us-east-2",
    topic_arn_overrides={
        'listing-events': 'arn:aws:sns:us-east-2:123:listing-events'
    }
)
message_id = publisher.publish(event)

Adding New Events: See events/README.md for instructions on adding new aggregates and events.

Pulumi Components (pyslets.pulumi_components)

EventTopic

Creates an encrypted SNS topic for event publishing.

TopicQueueSubscription

Creates an SQS queue subscribed to an SNS topic, with DLQ configured.

MongoDBQueueProcessingLambda

Creates Lambda + SQS + SNS subscription for message processing with MongoDB connection.

from pyslets.pulumi_components.messaging import MongoDBQueueProcessingLambda

handler = MongoDBQueueProcessingLambda(
    url_mongo="mongodb+srv://...",
    topic_arn="arn:aws:sns:...",
    consumer_name="MyProcessor",
    lambda_config={
        "code_path": "./lambda",
        "handler": "dist/src/index.handler",
        "timeout": 60,
        "memory_size": 512,
        "environment_variables": {
            "MY_VAR": "value",
        },
    }
)

WebhookApiGateway & WebhookLambdaHandler

Creates API Gateway with custom domain and Lambda handler for webhook processing.

Webhook SDK (pyslets.webhooks)

Provides signature validation for third-party webhook integrations: - HubSpot v3 signature validation - Extensible base validator for custom integrations

Installation

For Development

# Setup all environments at once
make setup

# Or setup individually:
cd pyslets && make setup       # Python SDK
cd infra && make setup          # Infrastructure
cd scripts && make setup        # Scripts

As a Package

pip install git+https://github.com/pilar/islets.git@main#subdirectory=pyslets

Development

Commands

Project-wide:

make help                       # Show all available commands
make setup                      # Set up all environments
make clean                      # Clean all build artifacts

Python SDK (pyslets):

# From root
make pyslets-test               # Run tests
make pyslets-lint               # Run linting
make pyslets-format             # Format code
make pyslets-clean              # Clean artifacts

# Or from pyslets/ directory
cd pyslets
make test                       # Run tests
make lint                       # Run linting
make format                     # Format code
make build-lambda               # Build Lambda deployment package

Infrastructure (infra):

# From root
make infra-deploy-sandbox       # Deploy to sandbox
make infra-deploy-production    # Deploy to production
make infra-preview-sandbox      # Preview sandbox changes
make infra-preview-production   # Preview production changes

# Or from infra/ directory
cd infra
make deploy-sandbox             # Deploy to sandbox
make preview-sandbox            # Preview changes

Scripts:

# From root
make scripts-test-e2e-sandbox   # E2E test (sandbox)
make scripts-test-e2e-production # E2E test (production)

# Or from scripts/ directory
cd scripts
make test-e2e-sandbox           # Requires HUBSPOT_WEBHOOK_SECRET

Running Tests

Unit Tests:

# From root
make pyslets-test

# Or from pyslets/ directory
cd pyslets
make test

# Run specific test file
pytest tests/test_events.py -v

End-to-End Tests:

# Test deployed webhook endpoint
HUBSPOT_WEBHOOK_SECRET=your-secret make scripts-test-e2e-sandbox

Deploying Infrastructure

# From root
make infra-deploy-sandbox
make infra-deploy-production

# Or from infra/ directory
cd infra
make deploy-sandbox
make deploy-production

# Preview changes before deploying
make preview-sandbox

Configuration

Event Schemas

Event schemas are defined in events/*.yaml (language-agnostic, shared across SDKs): - Each aggregate has its own YAML file (listing.yaml, company.yaml, etc.) - JSON Schema format for validation - Automatically discovered by SDKs at runtime

Default location: <project_root>/events/

Override with environment variable:

export ISLETS_EVENTS_CONFIG_PATH=/custom/path/to/events

Infrastructure Configuration

Infrastructure configuration is defined in infra/config.yaml: - Webhook domains and integrations - Event aggregates and SNS topic names - Lambda handler settings

The configuration is loaded using infra.config.load_config() which supports: - Explicit path: load_config('/path/to/config.yaml') - Environment variable: ISLETS_CONFIG_PATH=/path/to/config.yaml - Default: config.yaml in infra directory

Multi-Language SDK Support

The project is structured to support SDKs in multiple languages:

Event schemas are language-agnostic (JSON Schema in YAML files)
Shared at project root (events/) for all SDKs to consume
Each SDK has its own directory with dedicated Makefile
Infrastructure is independent of SDK implementation

Future SDKs (Node.js, Go, etc.) can: 1. Add a new directory (e.g., jslets/, golets/) 2. Implement event class generation from events/*.yaml 3. Add their own Makefile for commands 4. Share the same infrastructure and event schemas

Pre-commit Hooks

pre-commit: Ruff lint + format (auto-fix)
pre-push: Runs pytest