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:

cp .env.example .env

The application loads configuration in this order (higher priority first):

Environment variables
Variables from .env file
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

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.

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:

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.

Docs Sync Guardrail

To keep implementation and specification documents in sync, this repository provides an automated check.

Rules enforced:

If files under app/ change, docs/portfoliohub-spec.md must be updated in the same commit/PR.
If files under app/api/ or app/schemas/ change, docs/api-examples.md must be updated in the same commit/PR.
If files under migrations/versions/ change, docs/db-schema-spec.md must be updated in the same commit/PR.
Changed migration revision IDs must appear in docs/db-schema-spec.md.

Enable local pre-commit check:

pip install -e .[dev]
pre-commit install

Run manually:

python3 scripts/check_docs_sync.py --staged

CI check:

GitHub Actions workflow: .github/workflows/docs-sync-check.yml
Runs automatically on pull requests.

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

Implement Postgres/Timescale repository.
Port domain logic from jsbot-kis services.
Add integration tests for full portfolio flows.