FastAPI application entrypoint is available.
Token-based authentication and role checks are implemented.
Portfolio and user management API contracts are implemented.
Core portfolio domain services are ported from jsbot-kis.
Postgres-backed portfolio and user persistence 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)
Initial user bootstrap: PORTFOLIOHUB_BOOTSTRAP_USERNAME, PORTFOLIOHUB_BOOTSTRAP_EMAIL
Initial user password: PORTFOLIOHUB_BOOTSTRAP_PASSWORD
Session/token TTL: PORTFOLIOHUB_SESSION_TOKEN_TTL_HOURS, PORTFOLIOHUB_CLIENT_TOKEN_DEFAULT_TTL_DAYS, PORTFOLIOHUB_BOT_TOKEN_DEFAULT_TTL_DAYS
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

Production Deployment (HTTPS with Caddy)

For production, it is recommended to run PortfolioHub behind Caddy, which handles TLS certificate provisioning automatically.

A minimal Caddyfile:

your-domain.com {
    reverse_proxy localhost:8000
}

See docs/deployment.md for a full guide covering:

Caddy installation on Linux/Ubuntu
CORS configuration (PORTFOLIOHUB_ALLOWED_ORIGINS)
Running uvicorn as a systemd service
Docker Compose setup with a Caddy sidecar container
Firewall port configuration (80, 443)

CLI

The repository now includes a portfoliohub CLI that mirrors the main portfolio flows from jsbot-kis.

portfoliohub --help
portfoliohub user list
portfoliohub user create --username alice --password password123 --email alice@example.com --force
portfoliohub user get <user-id>
portfoliohub user update <user-id> --username alice-updated --force
portfoliohub user delete <user-id> --force
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
user list
user get
user create
user update
user delete
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, user management, and future operational actions

User management

User management is exposed through both HTTP API and CLI.

API base route: /users
Permission: admin only
Supported operations: list, get, create, update, delete

Frontend and app authentication is exposed through /auth.

POST /auth/login: username/password login, returns bearer session token
GET /auth/tokens: list current user's issued tokens
POST /auth/tokens: issue a client token for app/script usage
DELETE /auth/tokens/{token_id}: revoke a previously issued token
POST /auth/bots: create external bot principal (admin only)
GET /auth/bots: list bot principals (admin only)
POST /auth/bots/{bot_id}/tokens: issue bot API key with expiration (admin only)
GET /auth/bots/{bot_id}/tokens: list bot keys (admin only)
DELETE /auth/bots/{bot_id}/tokens/{token_id}: revoke bot key (admin only)
DELETE /auth/bots/{bot_id}: deactivate bot and revoke linked keys (admin only)

Example API calls:

curl -X GET "http://localhost:8000/users" \
	-H "Authorization: Bearer <ADMIN_TOKEN>"

curl -X POST "http://localhost:8000/users" \
	-H "Authorization: Bearer <ADMIN_TOKEN>" \
	-H "Content-Type: application/json" \
	-d '{"username": "alice", "email": "alice@example.com"}'

The default .env.example includes example tokens for development.

When PORTFOLIOHUB_DB_ENABLED=true and both PORTFOLIOHUB_BOOTSTRAP_USERNAME and PORTFOLIOHUB_BOOTSTRAP_PASSWORD are set, the app creates that admin user automatically on startup only if the users table is empty. This is intended for first-run bootstrap, not recurring synchronization.

Planned next steps

Apply and verify Alembic migrations against a real PostgreSQL/Timescale instance.
Add integration tests for DB-backed portfolio and user flows.
Design token-to-user mapping if ownership or user-scoped authorization is needed later.