Improved Documentation

README.md

@@ -1,27 +1,86 @@
 ![Streak](docs/images/logo.png)
 
--------------------------------
+# Streak PHP - Event Sourcing Framework
 
 [![CI](https://github.com/streakphp/streak/actions/workflows/ci.yaml/badge.svg)](https://github.com/streakphp/streak/actions/workflows/ci.yaml)
 [![codecov](https://codecov.io/gh/streakphp/streak/branch/master/graph/badge.svg)](https://codecov.io/gh/streakphp/streak)
 
-For more information and usage instructions, please refer to the [**Documentation**](docs/index.md).
+Streak is a PHP framework designed for building applications using the Event Sourcing pattern. It provides a robust foundation for creating event-sourced, domain-driven applications with a focus on flexibility and testability.
 
-Running checks & tests locally
-------------------------------
+## Features
 
-`docker-compose up --detach --build`
+- **Event Sourcing** - Persistent event store with support for various storage backends
+- **Command Handling** - Type-safe command processing with built-in validation
+- **Subscriptions** - Reliable event delivery system with support for resuming, restarting, and pausing
+- **Projections** - Tools for building read models optimized for querying
+- **Saga & Process Management** - Support for long-running business processes across multiple aggregates
 
-`docker-compose exec -T php composer validate --strict --no-interaction --ansi`
+## Installation
 
-`docker-compose exec -T php composer install --no-scripts --no-interaction --ansi`
+Install via Composer:
 
-`docker-compose exec -T php xphp -dxdebug.mode=coverage bin/phpunit --color=always --configuration=phpunit.xml.dist`
+```bash
+composer require streak/streak
+```
 
-`docker-compose run  -T php bin/phpunit`
+For Symfony integration, install the Streak Bundle:
 
-`docker-compose exec -T php bin/rector --dry-run --ansi`
+```bash
+composer require streak/streak-bundle
+```
 
-`docker-compose exec -T php bin/deptrac --no-interaction --cache-file=./build/.deptrac/.deptrac.cache --ansi`
+## Documentation
 
-`docker-compose exec -T php bin/php-cs-fixer fix --diff --dry-run --ansi --config=.php-cs-fixer.dist.php`
+Comprehensive documentation is available in the [docs](docs/index.md) directory:
+
+- [Core Concepts](docs/index.md#core-concepts)
+- [Getting Started](docs/index.md#getting-started)
+- [Tutorials](docs/index.md#getting-started)
+- [Symfony Integration](docs/symfony-bundle/installation.md)
+
+## Development
+
+### Requirements
+
+- PHP 8.0+
+- Docker and Docker Compose
+
+### Running locally
+
+Clone the repository:
+
+```bash
+git clone https://github.com/streakphp/streak.git
+cd streak
+```
+
+Start the development environment:
+
+```bash
+docker-compose up --detach --build
+```
+
+### Running tests and checks
+
+```bash
+# Validate composer.json
+docker-compose exec -T php composer validate --strict --no-interaction --ansi
+
+# Install dependencies
+docker-compose exec -T php composer install --no-scripts --no-interaction --ansi
+
+# Run tests with coverage
+docker-compose exec -T php xphp -dxdebug.mode=coverage bin/phpunit --color=always --configuration=phpunit.xml.dist
+
+# Run tests without coverage
+docker-compose run -T php bin/phpunit
+
+# Check code quality
+docker-compose exec -T php bin/rector --dry-run --ansi
+docker-compose exec -T php bin/deptrac --no-interaction --cache-file=./build/.deptrac/.deptrac.cache --ansi
+docker-compose exec -T php bin/php-cs-fixer fix --diff --dry-run --ansi --config=.php-cs-fixer.dist.php
+```
+
+## License
+
+Streak is open-sourced software licensed under the [MIT license](LICENSE).

docs/core-concepts/listeners.md

@@ -165,7 +165,7 @@ interface Subscription
 }
 ```
 
-### Lifecycle States
+### Subscription Lifecycle
 
 Subscriptions have several states they can be in:
 

docs/index.md

@@ -20,8 +20,8 @@ Streak is built around several key concepts central to Event Sourcing and DDD:
 *   **Events:** Represent facts about things that have happened in the past.
 *   **Event Store:** Responsible for persisting and retrieving streams of events.
 *   **Event Bus:** Allows decoupled components to react to published events.
-*   **Listeners:** Components that react to events.
-*   **Subscriptions:** Managed runtime that provides reliability and persistence.
+*   **Listeners:** Components that react to events and trigger side effects.
+*   **Subscriptions:** Persistent, reliable mechanism for delivering events to listeners, with support for tracking, restarting, and pausing event processing.
 
 ## Getting Started
 
@@ -32,10 +32,13 @@ Streak is built around several key concepts central to Event Sourcing and DDD:
     *   [Event Store](./core-concepts/event-store.md)
     *   [Event Bus](./core-concepts/event-bus.md)
     *   [Event Listeners](./core-concepts/listeners.md)
-    *   [Subscriptions](./core-concepts/listeners.md#subscriptions)
+    *   [Subscription System](./core-concepts/listeners.md#subscriptions)
     *   [Testing](./core-concepts/testing.md)
 2.  **Symfony Integration (Optional):** If you are using Symfony, learn how the `StreakBundle` simplifies integration.
     *   [StreakBundle Installation](./symfony-bundle/installation.md)
+    *   [Bundle Configuration](./symfony-bundle/configuration.md)
+    *   [Service Registration](./symfony-bundle/service-registration.md)
+    *   [Console Commands](./symfony-bundle/console-commands.md)
 3.  **Tutorials:** Follow step-by-step guides to build key components of an event-sourced application.
     *   [Building an Aggregate](./tutorials/building-an-aggregate.md) - Create the core domain model with commands and events
     *   [Building a Saga](./tutorials/building-a-saga.md) - Handle cross-aggregate coordination with external systems
@@ -49,11 +52,23 @@ Installation typically involves using Composer.
 ```bash
 composer require streak/streak
 ```
-
 For integration with Symfony, you will also need the bundle:
 
 ```bash
 composer require streak/streak-bundle
 ```
 
-Refer to the specific installation guides for more details. 
+Refer to the specific [StreakBundle Installation](./symfony-bundle/installation.md) guide for more details.
+
+## Advanced Topics
+
+After completing the basic tutorials, you might want to explore:
+
+* **Event Sourced Subscriptions** - [Subscription State Persistence](./core-concepts/listeners.md#subscription-state-persistence)
+* **Custom Event Store Implementations** - Adapting to different storage backends
+* **Projection Performance Optimization** - For high-volume event streams
+
+## Contributing
+
+Contributions to Streak are welcome! Please follow the [Documentation Style Guide](./STYLE_GUIDE.md) when adding or updating documentation. 
+