docs: introduction pages and homepage

Author: williarin

.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+
+.vitepress/dist/
+.vitepress/cache/
+
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

.nvmrc

@@ -0,0 +1 @@
+24

.vitepress/config.mts

@@ -0,0 +1,35 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Stochastix",
+  description: "High-Performance Quantitative Backtesting Engine",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/getting-started' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Getting Started', link: '/getting-started' },
+          { text: "What's Stochastix?", link: '/introduction' },
+          { text: 'Docker Tooling', link: '/docker-tooling' },
+          { text: 'Project Structure', link: '/project-structure' },
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/phpquant/stochastix-core' }
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2025-present William Arin'
+    }
+  }
+})

.vitepress/theme/custom.css

@@ -0,0 +1,11 @@
+:root {
+  --vp-c-brand-1: #0a347e;
+  --vp-c-brand-2: #0cac32;
+  --vp-c-brand-3: #0a347e;
+}
+
+.dark {
+  --vp-c-brand-1: #0cac32;
+  --vp-c-brand-2: #0a347e;
+  --vp-c-brand-3: #0cac32;
+}

.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme';
+import './custom.css';
+
+export default DefaultTheme;

docker-tooling.md

@@ -0,0 +1,103 @@
+# Docker Tooling with Makefile
+
+To simplify interaction with the Docker environment, Stochastix comes with a pre-configured `Makefile` in the root of your project. It contains convenient shortcuts for most common operations, from managing containers to running Composer and Symfony commands.
+
+::: info
+All `make` commands should be run from the root directory of your project (the same directory where the `Makefile` is located).
+:::
+
+## General
+
+### Displaying Help
+
+This is the most useful command to start with. It lists all available commands directly from the `Makefile` along with their descriptions.
+
+```bash
+make help
+```
+
+## Docker Container Management
+
+These commands are wrappers around `docker compose` to manage the lifecycle of your development environment.
+
+* **`make start`**
+    Builds the Docker images if they don't exist and starts all containers in detached mode. This is the typical command to start your work session.
+
+* **`make up`**
+    Starts the containers without rebuilding them. Useful if you've previously run `make down`.
+
+* **`make down`**
+    Stops and removes all running containers for this project.
+
+* **`make build`**
+    Forces a rebuild of the Docker images, pulling the latest base images and ignoring any cache. Use this if you've changed the `Dockerfile` or need to ensure you have the latest updates.
+
+* **`make logs`**
+    Attaches to the logs of all running containers so you can see their output in real-time. Press `Ctrl+C` to detach.
+
+* **`make sh` or `make bash`**
+    Opens an interactive shell session inside the main `php` container. This is the primary way to run commands within the Dockerized environment. `make bash` is often preferred as it provides better support for command history (using arrow keys).
+
+* **`make spawn c="..."`**
+    Spawns a new, temporary container to run a single command and then exits. This is useful for one-off tasks without attaching to a long-running container.
+
+    ```bash
+    # Example: Check the installed PHP modules
+    make spawn c="php -m"
+    ```
+
+* **`make test c="..."`**
+    Runs the PHPUnit test suite inside a dedicated test environment. You can pass additional arguments to `phpunit` using the `c=` parameter.
+
+    ```bash
+    # Run all tests
+    make test
+    
+    # Run a specific group of tests and stop on the first failure
+    make test c="--group e2e --stop-on-failure"
+    ```
+
+## Application & Dependencies
+
+These commands help you manage your project's dependencies and application state without needing to type long `docker compose exec` commands.
+
+### Composer
+
+* **`make install`**
+    Installs all PHP dependencies based on your `composer.lock` file.
+
+* **`make update`**
+    Updates your PHP dependencies to their latest allowed versions according to `composer.json`.
+
+* **`make composer c="..."`**
+    Runs any arbitrary Composer command.
+
+    ```bash
+    # Require a new package
+    make composer c="require symfony/orm-pack"
+    
+    # Show information about a package
+    make composer c="show symfony/console"
+    ```
+
+### Symfony Console
+
+* **`make sf c="..."`**
+    The main shortcut for executing Symfony commands via `bin/console`.
+
+    ::: details Example: Running Stochastix Commands
+    This is the recommended way to run all `stochastix:*` commands documented throughout this site.
+    ```bash
+    # Download market data
+    make sf c="stochastix:data:download binance BTC/USDT 1d --start-date=2023-01-01"
+    
+    # Run a backtest
+    make sf c="stochastix:backtesting ema_cross"
+    ```
+    :::
+
+* **`make cc`**
+    A quick shortcut for clearing the Symfony cache (`make sf c=cache:clear`).
+
+* **`make xsf c="..."`**
+    Runs a Symfony command with Xdebug enabled, allowing you to connect a debugger for step-by-step analysis.

getting-started.md

@@ -0,0 +1,90 @@
+# Getting Started
+
+Welcome to Stochastix\! This guide will walk you through setting up the framework so you can start backtesting your first trading strategy. We offer two installation paths: a one-command Docker setup (recommended for new projects) and a manual setup for integrating Stochastix into existing Symfony applications.
+
+## Docker Installation <Badge type="tip" text="Recommended" />
+
+::: tip The Easy Way
+This is the fastest and easiest way to get started with a fresh Stochastix project. The installer handles the creation of a new Symfony application, installation of the Stochastix bundle, and Docker configuration in a single command.
+:::
+
+Open your terminal and run the following command. Replace `your-project-name` with the desired directory name for your new project.
+
+```bash
+docker run --rm -it --pull=always -e HOST_PWD="$PWD" \
+  -v "$PWD":/app -v /var/run/docker.sock:/var/run/docker.sock \
+  ghcr.io/phpquant/stochastix-installer your-project-name
+```
+
+The installer will:
+
+1.  Create a new directory named `your-project-name`.
+2.  Set up a new Symfony project inside it.
+3.  Install the `stochastix/core` bundle and its dependencies.
+4.  Create `compose.yaml` file for a ready-to-use development environment.
+
+Once the process is complete, your Stochastix environment is now running and ready for use.
+
+You can access https://localhost in your web browser to access the user interface.
+
+Next step: visit the [Docker tooling](/docker-tooling.md) page to understand how to manage your Docker environment, including starting and stopping the containers, and launching commands inside the container.
+
+## Manual Installation
+
+Use this method if you want to integrate Stochastix into an existing Symfony project or prefer to manage your environment manually.
+
+### Requirements
+
+Before you begin, ensure your environment meets the following criteria:
+
+  * **PHP 8.4** or newer.
+  * The following PHP extensions must be enabled:
+      * `bcmath` (for high-precision financial calculations)
+      * `trader` (for technical analysis indicators)
+      * `ds` (for high-performance data structures)
+      * `pdo_sqlite` (for SQLite database support)
+      * `gmp` (for arbitrary precision arithmetic)
+  * **Composer** installed globally.
+
+### Step 1. Install the Bundle
+
+Navigate to your Symfony project's root directory and run the following command to add Stochastix as a dependency:
+
+```bash
+composer require stochastix/core
+```
+
+This bundle requires `williarin/cook` Composer plugin to run in order to install the package's necessary files to your project. At installation, it will automatically prompt you to allow the plugin to run.
+
+### Step 2. Download the UI assets
+
+To use the Stochastix web interface, you need to download the UI assets. Visit the Stochastix UI repository and download the latest release: https://github.com/phpquant/stochastix-ui/releases
+
+Extract the contents of the downloaded archive into the `.ui/` directory of your Symfony project.
+
+### Step 3. Configure your web server
+
+Ideally you should use FrankenPHP for easy installation. You can copy the configuration files from the Stochastix Docker installer into your project: https://github.com/phpquant/stochastix/tree/master/templates/frankenphp
+
+### Step 4. Run the Symfony Messenger worker
+
+All backtesting and data processing tasks are handled by Symfony Messenger. To start the worker, run the following command in your project root:
+
+```bash
+bin/console messenger:consume stochastix --time-limit=3600 --memory-limit=512M -vv
+```
+
+### Verifying the Installation
+
+You can verify that the framework is correctly installed by listing the available commands. From your project root, run:
+
+```bash
+bin/console list stochastix
+```
+
+You should see a list of all the `stochastix:*` commands, such as `stochastix:backtesting` and `stochastix:data:download`.
+
+## Headless & CLI-Driven
+While the web interface provides a powerful and user-friendly way to launch backtests and visualize results, it is entirely optional.
+
+The Stochastix engine is designed to be fully operational from the command line. Every feature, from downloading data to running complex backtests can be executed in a terminal.

index.md

@@ -0,0 +1,28 @@
+---
+layout: home
+
+hero:
+  name: "Stochastix"
+  text: "High-Performance Quantitative Backtesting Engine"
+  tagline: "From hypothesis to statistical proof. A professional-grade PHP framework to build, test, and analyze your crypto-currencies trading strategies."
+  image:
+    src: /logo.svg
+    alt: Stochastix
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/phpquant/stochastix-core
+
+features:
+  - title: "Realistic Simulation Engine"
+    details: "Process data bar-by-bar with a sophisticated order management system supporting Market, Limit, and Stop orders with automated Stop-Loss/Take-Profit handling."
+  - title: "Institutional-Grade Metrics"
+    details: "Go beyond P/L. Automatically calculate dozens of metrics like Sharpe & Sortino Ratios, Alpha, Beta, CAGR, and Max Drawdown to truly understand your strategy's risk and reward."
+  - title: "Optimized for Performance"
+    details: "Leverages custom binary formats for market and results data, combined with high-performance PHP extensions (ds, bcmath) to process massive datasets with maximum speed and precision."
+  - title: "Modern Developer Experience"
+    details: "Built on the robust Symfony framework. Define strategies and their inputs with simple, clean PHP attributes for a seamless and intuitive development workflow."
+---

introduction.md

@@ -0,0 +1,66 @@
+# What's Stochastix?
+
+Stochastix is a high-performance, open-source quantitative **backtesting framework** dedicated exclusively to **crypto-currencies trading**. Engineered in PHP and Symfony, it is designed to provide developers and quantitative analysts with a robust, precise, and extensible environment to build, test, and analyze algorithmic trading strategies.
+
+The framework's primary mission is to enable rigorous, data-driven research by providing tools that ensure simulation realism, computational precision, and deep performance insight.
+
+## The Core Principles
+
+Trading strategy development requires rigorous analysis. Stochastix is founded on three fundamental principles that make this possible:
+
+1.  **Realism:** A backtest is only as good as its simulation. Stochastix favors a realistic, event-driven approach that processes data bar-by-bar, handles complex order types natively, and manages portfolio state with precision.
+2.  **Performance:** Quantitative analysis involves massive datasets. The framework is architected for speed and memory efficiency, from its custom binary data formats to its use of high-performance PHP extensions, ensuring that your research is not bottlenecked by I/O or processing time.
+3.  **Developer experience:** A powerful tool should not be difficult to use. Built on modern PHP and the Symfony framework, Stochastix provides an intuitive, attribute-based system for strategy creation, clear separation of concerns, and a fully automatable command-line interface.
+
+## Key Features at a Glance
+
+  * **Event-driven backtesting engine:** Simulates trading on a bar-by-bar basis, providing a realistic environment for strategies that react to market changes as they happen.
+  * **Advanced order management:** Native support for `Market`, `Limit`, and `Stop` orders, including automated intra-bar execution of Stop-Loss and Take-Profit levels, partial exits, and programmatic order cancellation.
+  * **Multi-timeframe analysis:** Natively request and access secondary timeframes (e.g., 4-hour data within a 1-hour strategy). Data is automatically resampled and aligned with the primary series.
+  * **Comprehensive performance analytics:** Go far beyond simple Profit/Loss. The framework automatically generates dozens of institutional-grade summary and time-series metrics, including Sharpe Ratio, Sortino Ratio, Calmar Ratio, CAGR, Max Drawdown, Alpha, and Beta.
+  * **High-performance data formats:** Custom binary file formats (`.stchx`, `.stchxi`, `.stchxm`) for storing market data, indicators, and metrics, ensuring minimal storage footprint and maximum read performance.
+  * **Integrated data downloader:** A built-in CLI command to fetch high-quality historical OHLCV data from major exchanges via the CCXT library.
+  * **Asynchronous & real-time:** Leverages Symfony Messenger and Mercure to run backtests asynchronously while pushing live progress updates to the UI.
+
+## Engineered for Performance
+
+Stochastix is meticulously optimized to handle the demands of quantitative research.
+
+### Optimized Data Storage: The Binary Formats
+
+Text-based data formats like CSV are inefficient for backtesting. They are slow to parse and consume significant disk space. Stochastix solves this with its own family of binary formats:
+
+  * **`.stchx`**: For OHLCV market data.
+  * **`.stchxi`**: For indicator time-series data.
+  * **`.stchxm`**: For performance metric time-series data (e.g., equity curve).
+
+These formats provide several key advantages:
+
+  * **Compact:** They use a fraction of the disk space of a comparable CSV file.
+  * **Fast:** Data can be read directly into memory without any parsing overhead.
+  * **Efficient:** The fixed-size record structure allows for extremely fast time-range lookups using binary search, meaning the engine only reads the data it needs.
+
+### Efficient In-Memory Operations: The `ds` Extension
+
+For operations that occur in memory, such as handling time-series data during a backtest, Stochastix uses the `ext-ds` PHP extension. The `Ds\Vector` object provides a more memory-efficient and performant alternative to standard PHP arrays for large, contiguous lists of numerical data, which is precisely what a time-series is.
+
+## Designed for Developers
+
+Power and performance are meaningless without a great developer experience (DX).
+
+### Intuitive Strategy Creation
+
+Creating a strategy is simple and clean. By extending `AbstractStrategy`, you gain access to a rich set of helper methods. Strategy metadata and configurable parameters are defined with simple PHP attributes, reducing boilerplate and keeping your code declarative and easy to read.
+
+```php
+#[AsStrategy(alias: 'my_strategy', name: 'My Awesome Strategy')]
+class MyStrategy extends AbstractStrategy
+{
+    #[Input(description: 'The period for my indicator.')]
+    private int $myPeriod = 20;
+
+    public function onBar(OhlcvSeries $bars): void
+    {
+        // ... your logic here
+    }
+}