docs: add README, CONTRIBUTING, LICENSE

williarin · williarin · commit 1da83bf0c569 · 2025-06-15T14:46:39.000+08:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,29 @@
+# Contributing to Stochastix
+
+First off, thank you for considering contributing to Stochastix! It's people like you that make open source such a great community.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+If you find a bug, please ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/phpquant/stochastix-ui/issues).
+
+If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/phpquant/stochastix-ui/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample or an executable test case** demonstrating the expected behavior that is not occurring.
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as [GitHub issues](https://github.com/phpquant/stochastix-ui/issues). Create an issue on that repository and describe the enhancement you would like to see, why it would be useful, and any implementation ideas you may have.
+
+### Pull Request Process
+
+1.  Fork the repository and create your branch from `master`.
+2.  If you've added code that should be tested, add new tests.
+3.  Issue that pull request!
+
+## Coding Standards
+
+This project doesn't enforce coding standards yet. However, here are some general guidelines to follow:
+- use only the composition API syntax in components or pinia stores
+- use `script setup` syntax in components
+- the template tag should be the first tag in a component, followed by the script tag
+- use PascalCase for component names and filenames
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Arin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,75 +1,94 @@
-# Nuxt Minimal Starter
+# Stochastix UI
 
-Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
+**Stochastix UI** is the official frontend for the [Stochastix](https://github.com/phpquant/stochastix-core) quantitative trading backtesting framework. It is a modern, fully-featured Single Page Application (SPA) built with Nuxt 3, providing a rich, interactive graphical user interface to configure, launch, and analyze backtesting results generated by the core engine.
 
-## Setup
+This application is designed to run locally, communicating with a running instance of the `stochastix-core` backend via its REST API.
 
-Make sure to install dependencies:
+## Features
 
-```bash
-# npm
-npm install
-
-# pnpm
-pnpm install
+- **Dynamic Backtest Configuration**: Launch new backtests by selecting from available strategies and configuring their unique parameters through a dynamically generated form.
+- **Comprehensive Results Visualization**: Dive deep into backtest performance with detailed reports and visualizations.
+    - **Performance Summaries**: At-a-glance overview of key metrics like PnL, win rate, and total trades.
+    - **Detailed Statistics**: In-depth tables for pair-by-pair performance, entry/exit tag analysis, and a full breakdown of over 20 summary metrics (Sharpe, Sortino, Drawdown, etc.).
+    - **Visual Analysis Plots**: Interactive charts for Equity/Drawdown curves, and rolling Alpha/Beta plots against the benchmark.
+    - **Interactive Candlestick Charts**: Visualize trades and open positions directly on the price chart, complete with overlay and pane-based indicators.
+    - **Full Trade History**: A complete log of all closed and open positions for granular review.
+- **Real-Time Progress**: Monitor backtest and data download progress in real-time with progress bars connected to the backend via Mercure streams.
+- **Data Management**:
+    - **Local Data Overview**: View all locally available market data, sorted by symbol and timeframe.
+    - **Data Downloader**: An interface to queue new market data downloads from supported exchanges, with sequential processing to respect rate limits.
+    - **Dataset Inspector**: Validate data integrity by inspecting files for gaps, duplicates, or out-of-order records, and view file metadata and data samples.
+- **Responsive Design**: A clean, modern UI that works seamlessly on both desktop and mobile devices.
 
-# yarn
-yarn install
+## Documentation
 
-# bun
-bun install
-```
+For the latest official documentation, visit the [Stochastix Documentation](https://phpquant.github.io/stochastix-docs).
 
-## Development Server
+## Tech Stack
 
-Start the development server on `http://localhost:3000`:
+- **Framework**: [Nuxt 3](https://nuxt.com/)
+- **Language**: [TypeScript](https://www.typescriptlang.org/)
+- **UI Library**: [Nuxt UI](https://ui.nuxt.com/)
+- **State Management**: [Pinia](https://pinia.vuejs.org/)
+- **Charting**: [TradingView Lightweight Charts](https://www.tradingview.com/lightweight-charts/)
+- **Validation**: [Zod](https://zod.dev/)
+- **Internationalization**: [@nuxtjs/i18n](https://i18n.nuxtjs.org/)
+- **Icons**: [@nuxt/icon](https://icon.nuxt.com/)
 
-```bash
-# npm
-npm run dev
+## Prerequisites
 
-# pnpm
-pnpm dev
+1.  **Node.js**: Version 24 or higher.
+2.  **Stochastix Core Backend**: A running instance of the `stochastix-core` application is required for the UI to function.
+## Installation
 
-# yarn
-yarn dev
+1.  Clone the repository:
 
-# bun
-bun run dev
-```
+    ```bash
+    git clone https://github.com/phpquant/stochastix-ui.git
+    cd stochastix-ui
+    ```
 
-## Production
+2.  Install the dependencies:
 
-Build the application for production:
+    ```bash
+    npm install
+    ```
 
-```bash
-# npm
-npm run build
+## Configuration
 
-# pnpm
-pnpm build
+The Nuxt UI needs to know the location of the `stochastix-core` API. This is configured via an environment variable.
 
-# yarn
-yarn build
+Create a `.env` file in the root of the project:
 
-# bun
-bun run build
+```env
+# Example: If your backend is running on http://localhost:8000
+NUXT_API_BASE_SERVER=http://localhost:8000
 ```
 
-Locally preview production build:
+When using the provided Docker setup, this variable is automatically set in the `compose.yaml` file to point to the `php` service container.
+
+## Development
+
+To start the development server with hot-reloading on `http://localhost:3000`:
 
 ```bash
-# npm
-npm run preview
+npm run dev
+```
 
-# pnpm
-pnpm preview
+The application will proxy API requests from `/api` to the backend URL specified in `NUXT_API_BASE_SERVER`.
 
-# yarn
-yarn preview
+## Production
 
-# bun
-bun run preview
+To build the application for production:
+
+```bash
+npm run generate
+```
+
+To preview the production build locally:
+
+```bash
+npx serve ./output/public
 ```
 
-Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+For more information, see the [Nuxt Deployment Documentation](https://nuxt.com/docs/getting-started/deployment).
