chore: initial project scaffold and gitignore

2026-04-03 07:33:32 +00:00
commit 3e3acbd13d
41 changed files with 3658 additions and 0 deletions
@@ -0,0 +1,130 @@
+# PortfolioHub
+
+PortfolioHub is a FastAPI service that extracts portfolio management from `jsbot-kis` and exposes it through an authenticated HTTP API.
+
+## Current status
+
+This repository is in bootstrap phase.
+
+- FastAPI application entrypoint is available.
+- Token-based authentication and role checks are implemented.
+- Portfolio API contracts are defined.
+- Core portfolio domain services are ported from `jsbot-kis`.
+- Postgres repository scaffolding is implemented and gated behind `PORTFOLIOHUB_DB_ENABLED=true`.
+
+## Configuration
+
+Copy `.env.example` to `.env` and edit values as needed:
+
+```bash
+cp .env.example .env
+```
+
+The application loads configuration in this order (higher priority first):
+1. Environment variables
+2. Variables from `.env` file
+3. Default values in code
+
+When deploying to production, set environment variables directly instead of using `.env`.
+
+### Key configuration options
+
+- **DB repository switch**: `PORTFOLIOHUB_DB_ENABLED` (enables DB-backed persistence)
+- **TimescaleDB / PostgreSQL**: `TIMESCALEDB_*` (single source of DB connection settings)
+- **Redis**: `REDIS_*` (for caching and sessions)
+- **Loki**: `LOKI_*` (for centralized logging)
+- **Authentication**: `PORTFOLIOHUB_*_TOKENS` (bearer tokens with role-based access)
+
+For complete configuration options, see `.env.example`.
+
+## Run locally
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+
+# Configure .env
+cp .env.example .env
+
+# Start server
+uvicorn app.main:app --reload
+
+# In another terminal, run tests
+pytest
+```
+
+## CLI
+
+The repository now includes a `portfoliohub` CLI that mirrors the main portfolio flows from `jsbot-kis`.
+
+```bash
+portfoliohub --help
+portfoliohub portfolio list
+portfoliohub portfolio status 005930:tv --recent 10
+portfoliohub portfolio create 005930:tv --symbol 005930 --cash-balance 10000000 --force
+portfoliohub portfolio buy 005930:tv --quantity 10 --price 71000 --fee 5000 --force
+portfoliohub portfolio sell 005930:tv --quantity 5 --price 72000 --tax 3000 --force
+portfoliohub portfolio invest 005930:tv --type deposit --amount 50000 --force
+portfoliohub portfolio transfer 005930:tv --direction to-buffer --amount 100000 --force
+portfoliohub portfolio reset 005930:tv --force
+portfoliohub portfolio delete 005930:tv --keep-ledger --force
+```
+
+Supported commands:
+
+- `init-db`
+- `migrate-db`
+- `portfolio list`
+- `portfolio status`
+- `portfolio create`
+- `portfolio update`
+- `portfolio buy`
+- `portfolio sell`
+- `portfolio invest`
+- `portfolio transfer`
+- `portfolio reset`
+- `portfolio delete`
+- `health-check`
+
+Write commands ask for confirmation by default. Use `--force` to skip the prompt for scripts and automation.
+
+The CLI uses the same repository and settings layer as the HTTP API. To target the external TimescaleDB, set `PORTFOLIOHUB_DB_ENABLED=true` and provide `TIMESCALEDB_*` values in the environment or `.env`.
+
+Initialize a new database explicitly before the first use:
+
+```bash
+PORTFOLIOHUB_DB_ENABLED=true portfoliohub init-db
+PORTFOLIOHUB_DB_ENABLED=true portfoliohub health-check
+PORTFOLIOHUB_DB_ENABLED=true portfoliohub portfolio list
+```
+
+`init-db` will:
+
+- connect to the maintenance database, defaulting to `postgres`
+- create the target database if it does not exist
+- run Alembic `upgrade head`
+
+`migrate-db` will:
+
+- connect to the target database
+- run Alembic `upgrade head`
+- apply any future schema revisions in order
+
+This repository now uses Alembic for versioned schema migrations. Future schema changes should be added under `migrations/versions`.
+
+## Authentication model
+
+PortfolioHub currently supports bearer tokens with three permission levels.
+
+- `read`: list and status endpoints
+- `trade-write`: mutation endpoints such as buy, sell, invest, transfer, reset
+- `admin`: delete and future operational actions
+
+The default `.env.example` includes example tokens for development.
+
+## Planned next steps
+
+1. Implement Postgres/Timescale repository.
+2. Port domain logic from `jsbot-kis` services.
+3. Add integration tests for full portfolio flows.