Update CI configuration for Gitea registry credentials and README for project setup

README.md

@@ -1,23 +1,284 @@
-# Arbitrage Trading Bot
+# Arbitrade
 
-## Objective
+Low-latency cryptocurrency arbitrage bot scaffold for Kraken.
 
-- Develop an arbitrage trading bot that can identify and exploit price discrepancies across different currency pairs to generate profits.
-- Ensure the bot operates efficiently, securely, and can adapt to changing market conditions.
-- Implement risk management strategies to minimize potential losses.
-- Continuously monitor and optimize the bot's performance.
-- Provide a user-friendly interface for monitoring and controlling the bot's operations.
-- Integrate with kraken exchange for executing trades and accessing market data.
-- Implement a robust logging and alerting system to track the bot's activities and notify the user of important events or issues.
+Current stack:
 
-## Key Features
+- Python 3.12+
+- FastAPI + HTMX/Jinja2
+- DuckDB for dev/test/prod
+- Native Kraken WebSocket planned for market-data hot path
+- Gitea Actions + Gitea container registry
 
-1. **Market Data Collection**: The bot will collect real-time market data, including price, volume, and order book information.
-2. **Price Discrepancy Detection**: The bot will analyze the collected data to identify price discrepancies between currency pairs across different cryptocurrencies and fiat currencies.
-3. **Trade Execution**: The bot will execute trades automatically when a profitable arbitrage opportunity is detected, ensuring that it can capitalize on the price differences before they disappear.
-4. **Risk Management**: The bot will implement risk management strategies, such as setting stop-loss orders and limiting the amount of capital allocated to each trade, to minimize potential losses.
-5. **Performance Monitoring**: The bot will continuously monitor its performance, tracking metrics such as profit and loss, win rate, and average trade duration, to identify areas for improvement.
-6. **User Interface**: The bot will provide a user-friendly interface that allows users to monitor the bot's activities, view performance metrics, and control its operations.
-7. **Integration with Kraken Exchange**: The bot will integrate with the Kraken exchange to access market data and execute trades, ensuring that it can operate effectively in the cryptocurrency market.
-8. **Logging and Alerting System**: The bot will implement a robust logging system to track all activities and transactions, and an alerting system to notify the user of important events, such as successful trades, errors, or significant market changes.
-9. **Security Measures**: The bot will implement security measures to protect user data and prevent unauthorized access, including encryption of sensitive information and secure authentication methods.
+Project plan lives in [PLAN.md](PLAN.md).
+Task checklist lives in [.github/instructions/TODO.md](.github/instructions/TODO.md).
+
+## Current Status
+
+Bootstrap complete for foundation layer:
+
+- repo initialized
+- typed settings and env loading
+- structured logging
+- encrypted secret helpers
+- DuckDB connection + base schema
+- FastAPI app with health endpoint
+- Gitea Actions CI scaffold
+- Docker / docker-compose scaffold
+
+Not implemented yet:
+
+- Kraken REST client
+- Kraken native WebSocket client
+- arbitrage detection engine
+- trade execution
+- dashboard beyond health/bootstrap page
+
+## Prerequisites
+
+- Python 3.12+
+- `uv` for env/package management
+- Git
+- Docker Desktop or Docker Engine
+- Gitea account on `git.allucanget.biz` for push/CI/registry access
+
+Optional:
+
+- PowerShell 7 on Windows
+
+## Repository Setup
+
+Clone repo:
+
+```powershell
+git clone https://git.allucanget.biz/allucanget/arbitrade.git
+Set-Location arbitrade
+```
+
+If repo already exists locally, confirm remote:
+
+```powershell
+git remote -v
+```
+
+Expected origin:
+
+```text
+https://git.allucanget.biz/allucanget/arbitrade.git
+```
+
+## Local Development Setup
+
+Create virtualenv with `uv`:
+
+```powershell
+uv venv
+```
+
+Activate env on Windows:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+Install app + dev dependencies:
+
+```powershell
+uv pip install -e .[dev]
+```
+
+Create local env file:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+Minimum `.env` values:
+
+```env
+APP_ENV=dev
+APP_HOST=0.0.0.0
+APP_PORT=8000
+LOG_LEVEL=INFO
+LOG_JSON=true
+DUCKDB_PATH=./data/arbitrade.duckdb
+FERNET_KEY=
+KRAKEN_API_KEY=
+KRAKEN_API_SECRET=
+```
+
+Notes:
+
+- Leave Kraken creds empty until Kraken integration lands.
+- `FERNET_KEY` optional. If empty, keyring-backed key generation used by secret helper.
+- On Windows, app falls back to default `asyncio` loop. On non-Windows, `uvloop` installs automatically.
+
+## Run App
+
+Start app:
+
+```powershell
+python -m arbitrade.main
+```
+
+Health endpoints:
+
+- HTML: `http://localhost:8000/`
+- JSON: `http://localhost:8000/health`
+
+## Database
+
+DuckDB used everywhere: local dev, tests, production.
+
+Default database file:
+
+```text
+./data/arbitrade.duckdb
+```
+
+Schema bootstrap runs automatically on app startup.
+
+Current tables:
+
+- `schema_migrations`
+- `opportunities`
+- `trades`
+- `portfolio_snapshots`
+
+## Quality Checks
+
+Run tests:
+
+```powershell
+pytest -q
+```
+
+Run Ruff:
+
+```powershell
+ruff check .
+```
+
+Run Black check:
+
+```powershell
+black --check .
+```
+
+Run mypy:
+
+```powershell
+mypy src
+```
+
+Install pre-commit hooks:
+
+```powershell
+pre-commit install
+```
+
+Run hooks manually:
+
+```powershell
+pre-commit run --all-files
+```
+
+## Docker
+
+Build locally:
+
+```powershell
+docker build -t arbitrade:local .
+```
+
+Run with compose:
+
+```powershell
+docker compose up --build
+```
+
+Compose mounts local `data/` folder into container at `/app/data`.
+
+Important:
+
+- [docker-compose.yml](docker-compose.yml) still uses registry image placeholder format.
+- Replace `git.allucanget.biz/OWNER/arbitrade:latest` with actual namespace image, likely `git.allucanget.biz/allucanget/arbitrade:latest`.
+
+## Gitea CI / Registry Setup
+
+CI file:
+
+- [.gitea/workflows/ci.yml](.gitea/workflows/ci.yml)
+
+Required Gitea Actions secrets:
+
+- `REGISTRY_USERNAME`
+- `REGISTRY_TOKEN`
+- `REGISTRY_NAMESPACE`
+
+Expected namespace now likely:
+
+```text
+allucanget
+```
+
+Example registry login:
+
+```powershell
+docker login git.allucanget.biz
+```
+
+Example pushed image tag shape:
+
+```text
+git.allucanget.biz/allucanget/arbitrade:<tag>
+```
+
+## Project Layout
+
+```text
+arbitrade/
+├── .gitea/workflows/ci.yml
+├── .github/instructions/TODO.md
+├── PLAN.md
+├── pyproject.toml
+├── src/arbitrade/
+│   ├── api/
+│   ├── config/
+│   ├── storage/
+│   ├── logging_setup.py
+│   └── main.py
+├── tests/
+└── web/templates/
+```
+
+## Next Work
+
+Next planned implementation slice:
+
+- Kraken REST client skeleton
+- native Kraken WebSocket client
+- in-memory order book cache
+- latency instrumentation
+
+## Troubleshooting
+
+PowerShell blocks activation script:
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
+```
+
+Then activate again:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+If app import fails, confirm editable install ran:
+
+```powershell
+uv pip install -e .[dev]
+```
+
+If DuckDB file missing, start app once or create `data/` directory manually.