eventsource-py 0.1.2__tar.gz → 0.2.0__tar.gz

{eventsource_py-0.1.2 → eventsource_py-0.2.0}/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,7 +1,9 @@
 ---
 name: Bug Report
-description: Report a bug or unexpected behavior
-labels: ["bug"]
+about: Report a bug or unexpected behavior
+title: ''
+labels: bug
+assignees: ''
 ---
 
 ## Description

{eventsource_py-0.1.2 → eventsource_py-0.2.0}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,8 @@
 blank_issues_enabled: false
 contact_links:
   - name: Documentation
-    url: https://[ORGANIZATION].github.io/eventsource-py
+    url: https://tyevans.github.io/eventsource-py
     about: Check our documentation for answers
   - name: Questions & Discussions
-    url: https://github.com/[ORGANIZATION]/eventsource-py/discussions
+    url: https://github.com/tyevans/eventsource-py/discussions
     about: Ask questions and discuss ideas

{eventsource_py-0.1.2 → eventsource_py-0.2.0}/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,7 +1,9 @@
 ---
 name: Feature Request
-description: Suggest a new feature or enhancement
-labels: ["enhancement"]
+about: Suggest a new feature or enhancement
+title: ''
+labels: enhancement
+assignees: ''
 ---
 
 ## Problem Statement

{eventsource_py-0.1.2 → eventsource_py-0.2.0}/.github/workflows/docs.yml

@@ -117,7 +117,7 @@ jobs:
             --accept 200,204,206
             --exclude-mail
             --exclude-path './site'
-            --exclude 'your-org'
+            --exclude 'tyevans.github.io'
             --exclude 'localhost'
             --exclude '127.0.0.1'
             'docs/**/*.md'

{eventsource_py-0.1.2 → eventsource_py-0.2.0}/.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
       - id: debug-statements
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.2
+    rev: v0.14.8
     hooks:
       - id: ruff
         args: [--fix]
@@ -25,6 +25,8 @@ repos:
           - sqlalchemy>=2.0
           - redis==5.3.1
           - opentelemetry-api>=1.0
+          - aio-pika>=9.0.0
+          - aiosqlite>=0.20.0
         args: [--config-file=pyproject.toml]
         files: ^src/
 

eventsource_py-0.2.0/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2025-12-08
+
+### Added
+
+#### Observability & Telemetry
+
+- **Observability Module** (`eventsource.observability`) - Reusable OpenTelemetry utilities
+  - `OTEL_AVAILABLE` constant for checking OpenTelemetry availability
+  - `get_tracer()` and `should_trace()` helper functions
+  - `@traced` decorator for method-level tracing
+  - `TracingMixin` class for consistent tracing across components
+- **Kafka Event Bus Metrics** - Comprehensive OpenTelemetry metrics
+  - Counters: `messages.published`, `messages.consumed`, `handler.invocations`, `handler.errors`, `messages.dlq`, `connection.errors`, `reconnections`, `rebalances`, `publish.errors`
+  - Histograms: `publish.duration`, `consume.duration`, `handler.duration`, `batch.size`
+  - Gauges: `connections.active`, `consumer.lag` (per partition)
+  - New `KafkaEventBusMetrics` class with `enable_metrics` config option
+  - Less than 5% performance overhead
+- **SQLiteEventStore Tracing** - `enable_tracing` parameter for `append_events` and `get_events` operations
+- **InMemoryEventBus Tracing** - `enable_tracing` parameter for event dispatch and handler execution
+
+#### Aggregate Snapshotting
+
+- `Snapshot` dataclass for point-in-time aggregate state capture
+- `SnapshotStore` interface with `InMemorySnapshotStore`, `PostgreSQLSnapshotStore`, and `SQLiteSnapshotStore` implementations
+- `AggregateRepository` snapshot support: `snapshot_store`, `snapshot_threshold`, and `snapshot_mode` parameters
+- `AggregateRoot.schema_version` for snapshot schema evolution with automatic invalidation
+- `create_snapshot()` and `await_pending_snapshots()` methods
+- Snapshot exceptions: `SnapshotError`, `SnapshotDeserializationError`, `SnapshotSchemaVersionError`, `SnapshotNotFoundError`
+- Database migrations for `snapshots` table (PostgreSQL and SQLite)
+
+#### Event Handling & Validation
+
+- `EventVersionError` exception and configurable version validation via `AggregateRoot.validate_versions`
+- `UnhandledEventError` exception with configurable handling via `unregistered_event_handling` attribute ("ignore", "warn", "error")
+- `FlexibleEventHandler` and `FlexibleEventSubscriber` protocols for sync/async handler signatures
+- Consolidated `eventsource.protocols` module as canonical location for protocol definitions
+
+#### Database & Repository
+
+- `DatabaseProjection` class for projections requiring raw database connection access
+- `execute_with_connection` helper for consistent connection handling
+- Configurable UUID field detection in `PostgreSQLEventStore` via `uuid_fields`, `string_id_fields`, and `auto_detect_uuid` parameters
+- `PostgreSQLEventStore.with_strict_uuid_detection()` class method
+
+#### Developer Experience
+
+- Pre-commit hooks with ruff, mypy, and bandit
+- GitHub Actions workflow for performance benchmarks with baseline tracking and PR comparison
+- Shared test fixtures module (`tests/fixtures/`) with reusable components
+
+### Changed
+
+- Improved type annotations for better mypy compatibility
+- Consolidated `@handles` decorator to `eventsource.projections.decorators` (old location deprecated)
+- Consolidated protocol definitions to `eventsource.protocols` (old locations deprecated)
+- Repository methods `get_pending_events`, `get_failed_events`, `get_failed_event_by_id` now return typed dataclasses (`OutboxEntry`, `DLQEntry`) instead of dicts
+- Unified `get_events_by_type()` timestamp parameters to use `datetime` instead of `float`
+- Refactored repositories to use `execute_with_connection` helper
+- In-memory repositories now use `asyncio.Lock` for proper async concurrency
+
+### Removed
+
+- `SyncEventStore` abstract class (use `asyncio.run()` for sync access; see ADR-0007)
+
+### Fixed
+
+- Broken documentation links in ADRs and guides
+- Mypy type errors in projections, repositories, and event bus modules
+- `DeclarativeProjection` connection handling for proper transaction sharing
+
+## [0.1.3] - 2025-12-07
+
+### Documentation
+
+- Added documentation badge linking to GitHub Pages
+- Updated all documentation URLs to point to https://tyevans.github.io/eventsource-py
+- Fixed mkdocs.yml site configuration with correct repository URLs
+- Simplified README documentation section with links to hosted docs
+
+## [0.1.2] - 2025-12-07
+
+### Fixed
+
+- Fixed release workflow version validation
+
+## [0.1.1] - 2025-12-07
+
+### Fixed
+
+- Release infrastructure corrections
+
+## [0.1.0] - 2025-12-07
+
+### Added
+
+- Initial release of eventsource-py library
+- Event Store with PostgreSQL, SQLite, and In-Memory backends
+- Domain Events with Pydantic validation
+- Aggregate base class with optimistic concurrency control
+- Projection system for building read models with checkpoint tracking
+- Dead Letter Queue (DLQ) for failed event handling
+- Snapshot support for aggregate state caching
+- Multi-tenant support with tenant isolation
+- Async-first API design throughout
+- Comprehensive type hints and mypy compatibility
+- Event registry for type-safe event deserialization
+- Event Bus with In-Memory and Redis Streams backends
+- Transactional Outbox pattern implementation
+- `DatabaseProjection` class for projections requiring raw database connection access
+- Pre-commit hooks configuration with ruff, mypy, and bandit
+
+### Infrastructure
+
+- PostgreSQL backend with connection pooling (asyncpg)
+- SQLite backend for lightweight deployments, development, and testing
+- Redis Streams backend for distributed event bus
+- In-Memory backends for testing and development
+- Automatic schema creation and migrations
+- GitHub Actions CI/CD pipeline
+
+[Unreleased]: https://github.com/tyevans/eventsource-py/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/tyevans/eventsource-py/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/tyevans/eventsource-py/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/tyevans/eventsource-py/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/tyevans/eventsource-py/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/tyevans/eventsource-py/releases/tag/v0.1.0

{eventsource_py-0.1.2 → eventsource_py-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eventsource-py
-Version: 0.1.2
+Version: 0.2.0
 Summary: Production-ready event sourcing library for Python
 Project-URL: Homepage, https://github.com/tyevans/eventsource-py
 Project-URL: Documentation, https://tyevans.github.io/eventsource-py
@@ -24,6 +24,8 @@ Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: redis>=5.0
 Requires-Dist: sqlalchemy<3.0,>=2.0
 Provides-Extra: all
+Requires-Dist: aio-pika>=9.0.0; extra == 'all'
+Requires-Dist: aiokafka<1.0.0,>=0.9.0; extra == 'all'
 Requires-Dist: aiosqlite<1.0,>=0.19.0; extra == 'all'
 Requires-Dist: asyncpg<1.0,>=0.27.0; extra == 'all'
 Requires-Dist: opentelemetry-api<2.0,>=1.0; extra == 'all'
@@ -32,21 +34,31 @@ Requires-Dist: redis<6.0,>=5.0; extra == 'all'
 Provides-Extra: all-backends
 Requires-Dist: aiosqlite<1.0,>=0.19.0; extra == 'all-backends'
 Requires-Dist: asyncpg<1.0,>=0.27.0; extra == 'all-backends'
+Provides-Extra: benchmark
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'benchmark'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pre-commit>=4.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.3; extra == 'dev'
+Requires-Dist: ruff>=0.14.8; extra == 'dev'
 Requires-Dist: testcontainers>=4.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocs>=1.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
+Provides-Extra: kafka
+Requires-Dist: aiokafka<1.0.0,>=0.9.0; extra == 'kafka'
+Provides-Extra: kafka-schema-registry
+Requires-Dist: aiokafka<1.0.0,>=0.9.0; extra == 'kafka-schema-registry'
+Requires-Dist: confluent-kafka<3.0.0,>=2.0.0; extra == 'kafka-schema-registry'
 Provides-Extra: postgresql
 Requires-Dist: asyncpg<1.0,>=0.27.0; extra == 'postgresql'
+Provides-Extra: rabbitmq
+Requires-Dist: aio-pika>=9.0.0; extra == 'rabbitmq'
 Provides-Extra: redis
 Requires-Dist: redis<6.0,>=5.0; extra == 'redis'
 Provides-Extra: sqlite
@@ -62,6 +74,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 [![PyPI version](https://img.shields.io/pypi/v/eventsource-py.svg)](https://pypi.org/project/eventsource-py/)
 [![CI](https://github.com/tyevans/eventsource-py/actions/workflows/ci.yml/badge.svg)](https://github.com/tyevans/eventsource-py/actions)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://tyevans.github.io/eventsource-py)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 
 A production-ready event sourcing library for Python 3.11+.
@@ -73,39 +86,69 @@ A production-ready event sourcing library for Python 3.11+.
 - **Event Registry** - Thread-safe event type registration for serialization/deserialization
 - **Aggregate Pattern** - Base classes for event-sourced aggregates with state reconstruction
 - **Repository Pattern** - Clean abstractions for loading and saving aggregates
+- **Aggregate Snapshotting** - Optimize load performance for long-lived aggregates
 - **Projection System** - Checkpoint tracking, retry logic, and dead letter queue support
-- **Event Bus** - In-Memory and Redis Streams backends for event distribution
+- **Event Bus** - In-Memory, Redis Streams, RabbitMQ, and Kafka backends for event distribution
 - **Transactional Outbox** - Reliable event publishing pattern
 - **Multi-tenancy** - Built-in tenant isolation support
 - **Observability** - Optional OpenTelemetry integration
 
 ## Installation
 
+### Basic Installation
+
 ```bash
-# Basic installation
 pip install eventsource-py
+```
+
+### With Optional Dependencies
 
-# With PostgreSQL support
+eventsource uses optional dependencies to keep the core package lightweight. Install only what you need:
+
+```bash
+# PostgreSQL support - production event store with asyncpg
 pip install eventsource-py[postgresql]
 
-# With SQLite support
+# SQLite support - lightweight deployments
 pip install eventsource-py[sqlite]
 
-# With Redis support
+# Redis support - distributed event bus with Redis Streams
 pip install eventsource-py[redis]
 
-# With OpenTelemetry support
+# RabbitMQ support - distributed event bus with RabbitMQ
+pip install eventsource-py[rabbitmq]
+
+# Kafka support - distributed event bus with Apache Kafka
+pip install eventsource-py[kafka]
+
+# Telemetry support - OpenTelemetry tracing integration
 pip install eventsource-py[telemetry]
 
 # All optional dependencies
 pip install eventsource-py[all]
+
+# Multiple extras
+pip install eventsource-py[postgresql,redis,telemetry]
 ```
 
+| Extra | Enables | Dependencies |
+|-------|---------|--------------|
+| `postgresql` | `PostgreSQLEventStore`, checkpoint/outbox/DLQ repositories | asyncpg |
+| `sqlite` | `SQLiteEventStore` for lightweight deployments | aiosqlite |
+| `redis` | `RedisEventBus` with consumer groups and DLQ | redis |
+| `rabbitmq` | `RabbitMQEventBus` with exchange routing and DLQ | aio-pika |
+| `kafka` | `KafkaEventBus` with consumer groups, DLQ, and tracing | aiokafka |
+| `telemetry` | Distributed tracing for event operations | opentelemetry-api, opentelemetry-sdk |
+| `all` | All of the above | All of the above |
+| `dev` | Development tools | pytest, mypy, ruff, pre-commit |
+
+For detailed installation instructions, troubleshooting, and version compatibility, see the [Installation Guide](docs/installation.md).
+
 ## Requirements
 
 - Python 3.11+
 - pydantic >= 2.0
-- sqlalchemy >= 2.0 (for PostgreSQL backend)
+- sqlalchemy >= 2.0
 
 ## Quick Start
 
@@ -263,47 +306,12 @@ asyncio.run(main())
 
 ## Documentation
 
-For comprehensive documentation, see the [Documentation Index](docs/index.md).
-
-### Getting Started
-
-- [Getting Started Guide](docs/getting-started.md) - Installation and first steps
-- [Architecture Overview](docs/architecture.md) - System design and concepts
-- [FAQ](docs/faq.md) - Frequently asked questions
-
-### Guides
-
-- [Multi-tenant Setup](docs/guides/multi-tenant.md) - Tenant isolation patterns and configuration
-- [Error Handling](docs/guides/error-handling.md) - Exception handling best practices
-- [Authentication](docs/guides/authentication.md) - Security integration patterns
-- [Production Deployment](docs/guides/production.md) - Production readiness checklist
-
-### API Reference
-
-- [Events API](docs/api/events.md) - DomainEvent and EventRegistry
-- [Event Stores](docs/api/stores.md) - EventStore interface and implementations
-- [Aggregates](docs/api/aggregates.md) - AggregateRoot and Repository
-- [Projections](docs/api/projections.md) - Projection system
-- [Event Bus](docs/api/bus.md) - Event distribution
-
-### Examples
-
-- [Basic Usage](docs/examples/basic-order.md) - Simple order example
-- [Multi-tenant Setup](docs/examples/multi-tenant.md) - Multi-tenancy configuration
-- [Projections](docs/examples/projections.md) - Building read models
-- [Testing Patterns](docs/examples/testing.md) - Unit and integration testing
-
-### Architecture Decision Records
-
-- [ADR Index](docs/adrs/index.md) - All architectural decisions
-- [ADR-0001: Async-First Design](docs/adrs/0001-async-first-design.md)
-- [ADR-0002: Pydantic Event Models](docs/adrs/0002-pydantic-event-models.md)
-- [ADR-0003: Optimistic Locking](docs/adrs/0003-optimistic-locking.md)
-
-### Developer Documentation
+📚 **[Full Documentation](https://tyevans.github.io/eventsource-py)**
 
-- [Code Structure](docs/development/code-structure.md) - Project organization
-- [Testing Guide](docs/development/testing.md) - Testing strategies and patterns
+- [Getting Started Guide](https://tyevans.github.io/eventsource-py/getting-started/) - Installation and first steps
+- [Architecture Overview](https://tyevans.github.io/eventsource-py/architecture/) - System design and concepts
+- [API Reference](https://tyevans.github.io/eventsource-py/api/) - Complete API documentation
+- [FAQ](https://tyevans.github.io/eventsource-py/faq/) - Frequently asked questions
 
 ## Development
 

{eventsource_py-0.1.2 → eventsource_py-0.2.0}/README.md

@@ -4,6 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 [![PyPI version](https://img.shields.io/pypi/v/eventsource-py.svg)](https://pypi.org/project/eventsource-py/)
 [![CI](https://github.com/tyevans/eventsource-py/actions/workflows/ci.yml/badge.svg)](https://github.com/tyevans/eventsource-py/actions)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://tyevans.github.io/eventsource-py)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 
 A production-ready event sourcing library for Python 3.11+.
@@ -15,39 +16,69 @@ A production-ready event sourcing library for Python 3.11+.
 - **Event Registry** - Thread-safe event type registration for serialization/deserialization
 - **Aggregate Pattern** - Base classes for event-sourced aggregates with state reconstruction
 - **Repository Pattern** - Clean abstractions for loading and saving aggregates
+- **Aggregate Snapshotting** - Optimize load performance for long-lived aggregates
 - **Projection System** - Checkpoint tracking, retry logic, and dead letter queue support
-- **Event Bus** - In-Memory and Redis Streams backends for event distribution
+- **Event Bus** - In-Memory, Redis Streams, RabbitMQ, and Kafka backends for event distribution
 - **Transactional Outbox** - Reliable event publishing pattern
 - **Multi-tenancy** - Built-in tenant isolation support
 - **Observability** - Optional OpenTelemetry integration
 
 ## Installation
 
+### Basic Installation
+
 ```bash
-# Basic installation
 pip install eventsource-py
+```
+
+### With Optional Dependencies
 
-# With PostgreSQL support
+eventsource uses optional dependencies to keep the core package lightweight. Install only what you need:
+
+```bash
+# PostgreSQL support - production event store with asyncpg
 pip install eventsource-py[postgresql]
 
-# With SQLite support
+# SQLite support - lightweight deployments
 pip install eventsource-py[sqlite]
 
-# With Redis support
+# Redis support - distributed event bus with Redis Streams
 pip install eventsource-py[redis]
 
-# With OpenTelemetry support
+# RabbitMQ support - distributed event bus with RabbitMQ
+pip install eventsource-py[rabbitmq]
+
+# Kafka support - distributed event bus with Apache Kafka
+pip install eventsource-py[kafka]
+
+# Telemetry support - OpenTelemetry tracing integration
 pip install eventsource-py[telemetry]
 
 # All optional dependencies
 pip install eventsource-py[all]
+
+# Multiple extras
+pip install eventsource-py[postgresql,redis,telemetry]
 ```
 
+| Extra | Enables | Dependencies |
+|-------|---------|--------------|
+| `postgresql` | `PostgreSQLEventStore`, checkpoint/outbox/DLQ repositories | asyncpg |
+| `sqlite` | `SQLiteEventStore` for lightweight deployments | aiosqlite |
+| `redis` | `RedisEventBus` with consumer groups and DLQ | redis |
+| `rabbitmq` | `RabbitMQEventBus` with exchange routing and DLQ | aio-pika |
+| `kafka` | `KafkaEventBus` with consumer groups, DLQ, and tracing | aiokafka |
+| `telemetry` | Distributed tracing for event operations | opentelemetry-api, opentelemetry-sdk |
+| `all` | All of the above | All of the above |
+| `dev` | Development tools | pytest, mypy, ruff, pre-commit |
+
+For detailed installation instructions, troubleshooting, and version compatibility, see the [Installation Guide](docs/installation.md).
+
 ## Requirements
 
 - Python 3.11+
 - pydantic >= 2.0
-- sqlalchemy >= 2.0 (for PostgreSQL backend)
+- sqlalchemy >= 2.0
 
 ## Quick Start
 
@@ -205,47 +236,12 @@ asyncio.run(main())
 
 ## Documentation
 
-For comprehensive documentation, see the [Documentation Index](docs/index.md).
-
-### Getting Started
-
-- [Getting Started Guide](docs/getting-started.md) - Installation and first steps
-- [Architecture Overview](docs/architecture.md) - System design and concepts
-- [FAQ](docs/faq.md) - Frequently asked questions
-
-### Guides
-
-- [Multi-tenant Setup](docs/guides/multi-tenant.md) - Tenant isolation patterns and configuration
-- [Error Handling](docs/guides/error-handling.md) - Exception handling best practices
-- [Authentication](docs/guides/authentication.md) - Security integration patterns
-- [Production Deployment](docs/guides/production.md) - Production readiness checklist
-
-### API Reference
-
-- [Events API](docs/api/events.md) - DomainEvent and EventRegistry
-- [Event Stores](docs/api/stores.md) - EventStore interface and implementations
-- [Aggregates](docs/api/aggregates.md) - AggregateRoot and Repository
-- [Projections](docs/api/projections.md) - Projection system
-- [Event Bus](docs/api/bus.md) - Event distribution
-
-### Examples
-
-- [Basic Usage](docs/examples/basic-order.md) - Simple order example
-- [Multi-tenant Setup](docs/examples/multi-tenant.md) - Multi-tenancy configuration
-- [Projections](docs/examples/projections.md) - Building read models
-- [Testing Patterns](docs/examples/testing.md) - Unit and integration testing
-
-### Architecture Decision Records
-
-- [ADR Index](docs/adrs/index.md) - All architectural decisions
-- [ADR-0001: Async-First Design](docs/adrs/0001-async-first-design.md)
-- [ADR-0002: Pydantic Event Models](docs/adrs/0002-pydantic-event-models.md)
-- [ADR-0003: Optimistic Locking](docs/adrs/0003-optimistic-locking.md)
-
-### Developer Documentation
+📚 **[Full Documentation](https://tyevans.github.io/eventsource-py)**
 
-- [Code Structure](docs/development/code-structure.md) - Project organization
-- [Testing Guide](docs/development/testing.md) - Testing strategies and patterns
+- [Getting Started Guide](https://tyevans.github.io/eventsource-py/getting-started/) - Installation and first steps
+- [Architecture Overview](https://tyevans.github.io/eventsource-py/architecture/) - System design and concepts
+- [API Reference](https://tyevans.github.io/eventsource-py/api/) - Complete API documentation
+- [FAQ](https://tyevans.github.io/eventsource-py/faq/) - Frequently asked questions
 
 ## Development
 

{eventsource_py-0.1.2 → eventsource_py-0.2.0}/docs/adrs/0001-async-first-design.md

@@ -106,35 +106,33 @@ class EventStore(ABC):
         ...
 ```
 
-#### Sync Compatibility Layer
+#### Sync Usage via asyncio.run()
 
-For contexts where async is not available, we provide a synchronous interface:
+For contexts where async is not available or desired, users can wrap async calls:
 
 ```python
-# src/eventsource/stores/interface.py (lines 618-696)
-class SyncEventStore(ABC):
-    @abstractmethod
-    def append_events(
-        self,
-        aggregate_id: UUID,
-        aggregate_type: str,
-        events: list[DomainEvent],
-        expected_version: int,
-    ) -> AppendResult:
-        """Append events (synchronous)."""
-        pass
+import asyncio
+from eventsource import InMemoryEventStore
 
-    @abstractmethod
-    def get_events(
-        self,
-        aggregate_id: UUID,
-        aggregate_type: str | None = None,
-        from_version: int = 0,
-    ) -> EventStream:
-        """Get events (synchronous)."""
-        pass
+store = InMemoryEventStore()
+
+# Synchronous usage via asyncio.run()
+result = asyncio.run(store.append_events(
+    aggregate_id=order_id,
+    aggregate_type="Order",
+    events=[order_created],
+    expected_version=0,
+))
+
+stream = asyncio.run(store.get_events(order_id, "Order"))
 ```
 
+This approach was chosen over a separate `SyncEventStore` ABC because:
+- No concrete implementations existed for the sync interface
+- Modern Python I/O libraries are async-first
+- `asyncio.run()` provides a simple escape hatch when needed
+- Maintaining both interfaces adds maintenance burden without clear benefit
+
 #### Repository Pattern
 
 The `AggregateRepository` follows the async-first pattern:
@@ -189,14 +187,14 @@ class EventBus(ABC):
         pass
 ```
 
-### When to Use Sync vs Async APIs
+### When to Use Async vs asyncio.run()
 
-| Use Case | Recommended API |
-|----------|-----------------|
+| Use Case | Recommended Approach |
+|----------|---------------------|
 | Web applications (FastAPI, Starlette) | Async `EventStore` |
 | Background workers | Async `EventStore` |
-| CLI tools | Either (sync simpler for simple tools) |
-| Django (without async views) | `SyncEventStore` wrapper |
+| CLI tools | `asyncio.run()` wrapper for simplicity |
+| Django (without async views) | `asyncio.run()` wrapper |
 | Testing | Async (with pytest-asyncio) |
 | Jupyter notebooks | Async with `await` |
 
@@ -221,15 +219,14 @@ class EventBus(ABC):
 
 ### Neutral
 
-- **Need to maintain both async and sync interfaces**: The `SyncEventStore` ABC provides an escape hatch but adds maintenance overhead
-- **Framework integration varies**: FastAPI and Starlette are async-native; Flask and Django require adaptation
+- **Framework integration varies**: FastAPI and Starlette are async-native; Flask and Django require `asyncio.run()` wrappers
 - **Ecosystem dependency on async-capable drivers**: Must use asyncpg (not psycopg2) for PostgreSQL
 
 ## References
 
 ### Code References
 
-- `src/eventsource/stores/interface.py` - EventStore and SyncEventStore ABCs
+- `src/eventsource/stores/interface.py` - EventStore ABC
 - `src/eventsource/stores/postgresql.py` - Async PostgreSQL implementation
 - `src/eventsource/stores/in_memory.py` - Async in-memory implementation
 - `src/eventsource/aggregates/repository.py` - Async repository pattern