Chapter 8 of the dmz-web documentation · headings are numbered like the cheat sheets · index: Wiki

• Table of contents
• 8.1 Install — pf-install.sh (websvcmaster)
• 8.2 Application code and images
• 8.3 Operations
  • 8.3.1 New application version
  • 8.3.2 Logs and shell
  • 8.3.3 Backup and restore — TimescaleDB is not plain PostgreSQL
  • 8.3.4 Password rotation
  • 8.3.5 Upgrading the database image
• 8.4 Troubleshooting
• 8.5 Using the application
  • 8.5.1 Web GUI, roles and first run
  • 8.5.2 Pages (user)
  • 8.5.3 Dividend reinvestment (DRIP)
  • 8.5.4 Deposits and interest
  • 8.5.5 Splits and bonus issues
  • 8.5.6 Ideal basket and the market-suggested basket
  • 8.5.8 Currencies, costs and bonuses (1.1.13)
  • 8.5.7 Endpoints (/api/v1, bearer token except login)
• Document history

Version 1.18 — 2026-11-03 · companion of the host cheat sheet (conventions: Conventions, NPM, Operations, Git_Workflow)

Host dmz-web (Rocky Linux 10.2). Everything runs rootless under websvcmaster (no sudo) as Quadlet units. Design rule: shared-nothing — own networks, database, app container and volumes; the only shared piece is Nginx Proxy Manager (NPM), which joins the front network.

Item	Value
Public name	pf.sibernet.com.tr (DNS A record → FortiGate WAN IP; Let's Encrypt HTTP-01)
App	site-pf — FastAPI/uvicorn on :8000 (one worker), image localhost/site-pf:<tag> built locally from ~/apps/pf; web GUI and API with own login (password + TOTP/QR, roles User and Admin), no public registration; app version 1.1.14
Database	db-pf — TimescaleDB on PostgreSQL 16, docker.io/timescale/timescaledb:2.31.0-pg16
Networks	net-pf (NPM + app, outbound allowed — the app fetches market data) and net-pf-db (app + db only, Internal=true: the database has no route to the internet and NPM cannot reach it)
Volume	db-pf-data (PostgreSQL data)
Secrets	pf-db-password, pf-app-secret (both openssl rand -hex 32, created without a trailing newline)
Installer	pf-install.sh in ~/deploy (this file's procedures are what it does)
Source	pf-app-<ver>.tar.gz (delivered with the release, not part of dmz-web-deploy); lives afterwards in its own repo

Naming follows the host rule: containers db-pf / site-pf, secrets pf-…. The unit description Description=Portfolio -- <domain> is what check-sites.sh reads, so ./check-sites.sh | grep pf works.

---

8.1 Install — pf-install.sh (websvcmaster)¶

First time, from ~/deploy (shell setup: host cheat sheet §0), with the source tarball next to the script:

./pf-install.sh --app-src=pf-app-1.1.10.tar.gz --build --access-list=admin-segments

• --app-src=FILE unpacks the application (Containerfile, pinned requirements.txt, app/, tests/) into ~/apps/pf; existing files are never overwritten, and an archive with absolute or ../ paths is refused. It is for the first install — later code comes from the app's own repo (§2).
• --build runs podman build -t localhost/site-pf:1.1.10 ~/apps/pf (the default tag; --app-image=localhost/site-pf:<tag> for another).
• --access-list=NAME puts that NPM Access List on the new Proxy Host. The app has its own GUI login (§8.5.1), so this is a second layer, not the only one — still recommended while the host is new.
• Other options: --db-image, --app-dir, --timezone, --skip-npm-api, --force; ./pf-install.sh -h.

What it does, in order: generates the Quadlet files into ~/deploy/quadlet/ (net-pf.network, net-pf-db.network, db-pf.volume, db-pf.container, site-pf.container), creates the two secrets, adds net-pf to nginx-proxy-manager.container, installs the units, starts nets → db (waits until healthy) → app (waits for /health), restarts NPM (every site is down ~10–20 s — run it off-hours) and creates the Let's Encrypt certificate and Proxy Host through NPM's API.

Before it changes anything it compares the Network= lines of the live nginx-proxy-manager.container with the repo copy and stops if the live file knows a network the repo copy lacks (copying it over would cut that site off — the 2026-10-25 outage). If it stops: add the missing lines to the repo copy, commit, run again.

Prerequisite: the DNS name must already resolve to the FortiGate WAN IP, otherwise the certificate request fails (the rest still works; add cert and host in the NPM UI later: Forward Hostname site-pf, Forward Port 8000, Force SSL, HTTP/2, Websockets, Block Common Exploits).

Then commit the generated units (root): deploy-commit.sh -m "pf: portfolio stack on pf.sibernet.com.tr".

Open the site and create the administrator on the first-run page — §8.5.1. Verify:

curl -sI --resolve pf.sibernet.com.tr:444:127.0.0.1 https://pf.sibernet.com.tr:444 | head -1     # HTTP/2 200
curl -s  --resolve pf.sibernet.com.tr:444:127.0.0.1 https://pf.sibernet.com.tr:444/health        # {"status":"healthy"}
podman exec site-pf curl -s http://127.0.0.1:8000/health/db                                       # {"status":"db ok"}
./check-sites.sh | grep pf
podman network inspect net-pf net-pf-db | jq '.[].containers | keys'   # net-pf: site, nginx-proxy-manager · net-pf-db: db, site

---

8.2 Application code and images¶

The no-host-packages rule holds: no Python, pip or libraries on Rocky; everything lives in the image. The Containerfile is python:3.12-slim-bookworm + curl (for the healthcheck) + pip install --only-binary=:all: from a fully pinned requirements.txt (66 wheels) — no compiler in the image, and a dependency without a wheel fails the build loudly instead of compiling something unreviewed.

Source layout (~/apps/pf):

File	Job
app/config.py	PF_* settings; DB URL built with quote_plus, so a password with / + = @ : cannot break it
app/database.py, app/models.py	SQLAlchemy 2 (async, asyncpg); tables are created at start; price_history becomes a TimescaleDB hypertable when the extension is there
app/auth.py	bcrypt (SHA-256 pre-hash), TOTP with replay protection, JWT, per-IP rate limit, per-account lockout
app/services/market_data.py	Yahoo Finance (stocks, crypto, FX, dividends) and TEFAS (funds); raw, not dividend-adjusted prices
app/services/drip.py	dividend reinvestment (§8.5.3)
app/services/portfolio.py, indicators.py	positions, allocation, ideal basket and rebalancing hints (four classes), risk; RSI/MACD/SMA/EMA/Bollinger/ATR (pandas-ta)
app/services/suggest.py	market-suggested basket: benchmark trend rules, tilt capped by PF_SUGGEST_MAX_TILT (§8.5.6)
app/services/mailer.py	optional SMTP sender (notices, recovery links); silent when PF_SMTP_HOST is empty
app/main.py, app/schemas.py, app/cli.py	API, validation, admin commands
app/static/	the web GUI: index.html, style.css, app.js (no inline script or style, so the CSP stays strict; charts are drawn as SVG without libraries) and fonts/ (Inter, SIL OFL, served from the app itself: the CSP allows font-src 'self' only, nothing is loaded from Google)
tests/	54 tests (pytest), see "Tests" below

• Pinning: >= ranges drift (on 2026-10-29 an unpinned install resolves to pandas 3.x and a beta of pandas-ta). The list was resolved for Python 3.12 and import-tested; it includes greenlet, which SQLAlchemy's async layer needs and which is easy to miss. Change versions on purpose, build a new tag, test, then switch the unit. Not used on purpose: python-jose and passlib (unmaintained; passlib breaks with current bcrypt) — the app uses PyJWT and bcrypt directly.
• Image tags: one tag per release (site-pf:1.1.0, 1.1.1, …), never latest — the previous tag is the rollback.
• Config (PF_*, set in site-pf.container): PF_BASE_CURRENCY (default TRY; the default display currency of new users), PF_CURRENCIES (default TRY,USD,EUR,GBP,QAR: only the starting list; afterwards the administrator edits it in the browser under Currencies, and that list is kept in the database; rates for the pairs come from Yahoo, with the inverse, the dollar route and the official peg as fallbacks, so QAR works), PF_DIVIDEND_WITHHOLDING (fraction taken at source, default 0 — set it to what your broker really withholds, e.g. 0.10), PF_DRIP_DEFAULT (default true), PF_DIVIDEND_PAY_LAG_DAYS (default 0), PF_SYNC_ENABLED / PF_SYNC_INTERVAL_HOURS (daily), PF_REQUIRE_2FA (default true: end users must enrol 2FA, administrators may; false: optional for everybody — an administrator can still require it per account), PF_SUGGEST_MAX_TILT (default 10, hard cap 20: the most percentage points the market-suggested basket may move one asset class away from the user's own basket; a server setting on purpose, not a per-user one), PF_PW_LOCK_HOURS (24), PF_RECOVERY_TOKEN_MINUTES (30), PF_SMTP_HOST / PORT (587) / USER / PASSWORD / FROM / STARTTLS, PF_PUBLIC_URL (links in e-mails; default https://<PF_DOMAIN>), PF_LOGIN_RATE_LIMIT (default 5/minute), PF_ACCESS_TOKEN_MINUTES (30), PF_ENABLE_DOCS (0: hides /docs, /redoc, /openapi.json; 1 only while developing, never behind the public Proxy Host). The app refuses to start when PF_SECRET_KEY (secret pf-app-secret) is shorter than 32 characters.
• Source code is not in dmz-web-deploy. Keep ~/apps/pf in its own repository (e.g. a bare repo /srv/git/pf-app.git, same procedure as host cheat sheet §3.1.2 to §3.1.6) and tag it with the same number as the image.
• Tables: create_all at start creates what is missing. Later columns are added by a short list of idempotent ALTER TABLE … ADD COLUMN IF NOT EXISTS statements in app/database.py that runs at every start (release 1.1.1 adds seven columns to users: must_change_password, require_2fa, display_currency, is_owner, email, self_service_recovery, pw_locked_until, and makes the oldest administrator the Owner). Release 1.1.2 adds users.ideal_basket; transactions.rate_monthly, withholding_pct, term_months, maturity_date, parent_id (deposits and interest); the enum values asset_type = deposit and etf and tx_source = interest (ALTER TYPE … ADD VALUE IF NOT EXISTS); the share columns transactions.quantity, dividends.shares and dividends.reinvest_quantity are widened to NUMERIC(27,9); and the new table app_settings (the administrator's currency list). Release 1.1.3 changes no schema. Release 1.1.4 adds the table asset_splits (created by create_all: one row per split or bonus issue of an instrument) and the column users.ideal_basket_base (ADD COLUMN IF NOT EXISTS; set only while a user runs the market-suggested basket). Nothing is dropped or rewritten; take a pg_dump (§8.3.3) before the first start of a new version anyway.
• Tests: they need a throw-away PostgreSQL, never the production database (PF_ENV=test PF_TIMESCALE=off PF_SECRET_KEY=<32+ chars> PF_DATABASE_URL_OVERRIDE=postgresql+asyncpg://user:pw@host/pf_test pytest, with requirements-dev.txt installed in a venv away from the host's Python — e.g. on a workstation). Market data is faked in the tests: they prove the logic, not Yahoo/TEFAS behaviour.

---

8.3 Operations¶

8.3.1 New application version¶

Short way: a release that carries an application version upgrades it at the end of deploy-publish.sh (the plan shows the dry run of pf-upgrade.sh; one question for everything). On its own, as root, pf-upgrade.sh <version> does the steps below, asks before each one and keeps you in the root shell (§5.7). Since 1.1 it takes the tarball's sha256 from releases/CHECKSUMS.txt in the repo (or -s <sha256>), names the known TimescaleDB pg_dump notice as harmless, and moves superseded tarballs from /root to /root/deploy-done/<stamp>-pf-app/ (the replaced version stays for a rollback). The manual steps stay valid.

The source is delivered as pf-app-<ver>.tar.gz. The old source stays aside as the rollback:

# 0. backup first: §8.3.3 (pg_dump -Fc), copy it off the host
# (root) the tarball goes to ~websvcmaster/deploy first:  cp pf-app-1.1.10.tar.gz /home/websvcmaster/deploy/ && chown websvcmaster: /home/websvcmaster/deploy/pf-app-1.1.10.tar.gz
cd ~ && mv apps/pf apps/pf-1.1.5                        # keep the old tree
mkdir apps/pf && tar -xzf ~/deploy/pf-app-1.1.10.tar.gz -C apps/pf --no-same-owner --no-same-permissions
podman build -t localhost/site-pf:1.1.10 ~/apps/pf
# repo copy (websvcmaster): change the Image= line, keep HealthStartPeriod=90s
sed -i 's#^Image=localhost/site-pf:.*#Image=localhost/site-pf:1.1.10#' ~/deploy/quadlet/site-pf.container
# root (not websvcmaster: the script is root-only):  deploy-commit.sh -m "pf: app 1.1.10"
cp ~/deploy/quadlet/site-pf.container ~/.config/containers/systemd/
systemctl --user daemon-reload && systemctl --user restart site-pf.service     # only site-pf, not db-pf and not NPM
for i in $(seq 1 12); do s=$(podman inspect site-pf --format '{{.State.Health.Status}}'); echo "$i: $s"; [ "$s" = healthy ] && break; sleep 10; done
podman logs site-pf | tail -20
~/deploy/check-sites.sh | grep pf

Check the result (websvcmaster):

~/deploy/check-sites.sh | grep pf                                    # HTTP 200 / healthy
podman exec db-pf psql -U pf_user -d pf_db -c "\d users" | grep ideal_basket
podman exec db-pf psql -U pf_user -d pf_db -c "\d transactions" | grep -E "rate_monthly|withholding_pct|term_months|maturity_date|parent_id"
podman exec db-pf psql -U pf_user -d pf_db -c "select enum_range(null::asset_type), enum_range(null::tx_source)"   # deposit, etf and interest are in the lists
podman exec db-pf psql -U pf_user -d pf_db -c "\d transactions" | grep quantity                                   # numeric(27,9)
podman exec db-pf psql -U pf_user -d pf_db -c "\dt" | grep app_settings
podman exec db-pf psql -U pf_user -d pf_db -c "select hypertable_name from timescaledb_information.hypertables"    # price_history

In the browser press Ctrl+F5 once (new app.js, style.css and the Inter font files). The first dividend sync runs about 60 seconds after the start; fractional shares are now kept to 9 decimals (as Midas; the three share columns are widened by an idempotent migration), so existing dividend purchases (rounded to 6) change only after apply to past on a holding (Dividends page).

Rollback: put the previous tag back in the unit (same four lines). From 1.1.14 back to 1.1.13 is always safe (no schema change; deposit renewals count as new money in again and the risk / analysis error with funds priced 0 comes back). From 1.1.13 back to 1.1.12: the table ui_labels and the columns users.language, transactions.paid_currency, transactions.paid_amount are ignored by the old code (it shows English and costs at today's rate again), but once a bonus was entered the old code cannot read that row (the source value bonus is unknown to it): after bonuses, roll back by restoring the dump of the upgrade, not by the tag alone. An instrument whose currency was corrected stays correct for the old code. From 1.1.12 back to 1.1.11 is safe: the new table auth_refresh and the column users.sessions_valid_after are ignored by the old code; everybody logs in again once and the old version's in-memory login comes back. From 1.1.11 back to 1.1.10 is always safe (no schema change). From 1.1.10 back to 1.1.9 is always safe (no schema change). From 1.1.9 back to 1.1.8 is always safe (no schema change). From 1.1.8 back to 1.1.7: the two new columns of transactions (period_from, avg_balance) are harmless to the old code; interest lines made from statements stay and show as ordinary interest. Without the statement import and the price-currency choice, nothing else is lost. From 1.1.7 back to 1.1.6: the three new columns of transactions (rate_annual, term_days, at_maturity) are harmless to the old code, but automatic deposit rows (note auto: ...) that were already booked stay and the old version will not create any more; if that matters, restore the dump from step 0. From 1.1.6 back to 1.1.4 is always safe (no schema change since 1.1.4). From 1.1.4 back to 1.1.3 the added table and column are harmless to the old code, but once a split is stored the old version no longer counts old trades in the new share unit and its dividends no longer match: after splits were synced, roll back by restoring the dump from step 0, not by changing the tag alone. From 1.1.3 back to 1.1.2 is always safe (no schema change); the caveat below concerns going back past 1.1.2. The added columns are harmless to the old version, but only as long as no deposit or interest line exists: the old code does not know the enum values deposit / interest and fails on those rows. After deposits were entered, roll back by restoring the dump from step 0, not by changing the tag alone.

8.3.2 Logs and shell¶

journalctl --user -u site-pf.service -f
podman logs -f site-pf          podman logs -f db-pf
podman exec -it db-pf psql -U pf_user -d pf_db

8.3.3 Backup and restore — TimescaleDB is not plain PostgreSQL¶

A plain dump restored the plain way breaks hypertables. Use the custom format and restore with the Timescale pre/post calls:

# backup (websvcmaster) — then copy the file OFF the host; a dump next to the database is not a backup
podman exec db-pf pg_dump -U pf_user -Fc pf_db > ~/tmp/pf_db-$(date +%F).dump

# restore into an EMPTY database (same TimescaleDB version or newer)
podman exec db-pf psql -U pf_user -d postgres -c "create database pf_restore"
podman exec db-pf psql -U pf_user -d pf_restore -c "create extension if not exists timescaledb"
podman exec db-pf psql -U pf_user -d pf_restore -c "select timescaledb_pre_restore()"
podman exec -i db-pf pg_restore -U pf_user -d pf_restore --no-owner < ~/tmp/pf_db-2026-10-29.dump
podman exec db-pf psql -U pf_user -d pf_restore -c "select timescaledb_post_restore()"

pg_dump always prints a warning about circular foreign keys on continuous_agg (TimescaleDB's own catalog). It concerns --data-only dumps; this full dump restores with the pre/post calls above. To replace pf_db itself (a rollback that needs the old data): stop site-pf.service, drop database pf_db / create database pf_db (from database postgres), then the same four lines with -d pf_db, start site-pf.service. pf-upgrade.sh prints these lines with the right file name at its end.

Do one restore test before trusting the backups, and again after each TimescaleDB upgrade. The application volume has nothing to back up (no uploads); the secrets are not needed for a restore (set a new password in the new environment).

8.3.4 Password rotation¶

POSTGRES_PASSWORD is read only when the data directory is first created. To rotate: podman exec db-pf psql -U pf_user -d pf_db -c "alter user pf_user password '<new>'", then podman secret rm pf-db-password, create it again with the new value (printf '%s' '<new>' | podman secret create pf-db-password -), restart db-pf.service and site-pf.service.

8.3.5 Upgrading the database image¶

Dump first (C). Patch/minor (2.31.0-pg16 → 2.31.1-pg16): change the tag in the unit, cp, daemon-reload, restart db-pf.service, then ALTER EXTENSION timescaledb UPDATE; in pf_db (the first command in a fresh session). A PostgreSQL major jump (pg16 → pg17) is a dump-and-restore into a new volume, not a tag change.

---

8.4 Troubleshooting¶

• App restarts in a loop right after boot → it came up before the database accepted connections. The units wait for db-pf (Podman 5: Notify=healthy); check podman healthcheck run db-pf and podman logs db-pf.
• /health is 200 but /health/db is 503 → the password in the secret is not the password the database was initialised with (secret recreated after first start): rotate as in §8.3.4, or drop the volume if the database is still empty.
• NPM 502 for the pf host → NPM is not on net-pf (podman network inspect net-pf | jq '.[0].containers | keys'); check the Network=net-pf.network line in the live nginx-proxy-manager.container and that NPM was restarted afterwards. Other sites also 502 → host cheat sheet §7 "NPM says 502".
• Certificate request fails → the DNS name does not point to the FortiGate WAN IP yet, or TCP 80 does not reach NPM; fix DNS, then request the certificate in the NPM UI.
• App container exits at once, log says PF_SECRET_KEY ... shorter than 32 characters → the pf-app-secret secret is missing or empty; recreate it (openssl rand -hex 32 | tr -d '\n' | podman secret create pf-app-secret - after podman secret rm pf-app-secret) and restart site-pf.service. Existing login tokens become invalid (30 minutes anyway).
• The first-run page does not appear → an administrator already exists (podman exec -it site-pf python -m app.cli list-users). To get the first-run page again on a system that has a user created by the CLI: python -m app.cli set-role NAME user for every administrator — the page appears when no administrator exists; the setup code is in podman logs site-pf | grep FIRST-RUN (printed at start while no administrator exists, and again when the first-run page is opened without one — grep again after opening the page; valid until used or until the next start).
• The chart for 1D / 3D shows few points → prices are daily closes; there is no intraday data. 1W and longer are the meaningful periods.
• Login answers 429 → either the per-IP limit (5 attempts per minute, the answer comes back after a minute) or the account lock (5 wrong passwords or codes lock the account for 15 minutes): podman exec -it site-pf python -m app.cli unlock NAME.
• Rate limit hits everybody at once → every request seems to come from one address (the proxy). Check that NPM passes X-Forwarded-For (it does by default) and that the app runs with --proxy-headers (it does in the Containerfile).
• Authenticator code is always refused → phone clock drift (turn automatic time on), or the code was already used (each 30-second code works once). Lost phone: an administrator uses Reset 2FA (or Set temporary password with "also remove the old 2FA") in the GUI, or on the host python -m app.cli reset-2fa NAME; then the person enrols again.
• A dividend is stuck in pending_price → no price for its pay date yet (pay date in the future, or the data source was down); the daily sync completes it. Force it: POST /api/v1/dividends/sync.
• pg_dump prints a warning about circular foreign-key constraints → a notice, not an error: the dump still completes. Prove it with the restore test in §8.3.3 (pg_restore -l lists the tables, the row counts match).
• podman build prints "Running pip as the 'root' user …" → harmless; it happens inside the image build, not on the host.
• A hand-entered dividend appears next to the one from the market feed → the feed row is keyed by ex-date, a hand-entered one under another date (typically the pay date) is a second row. The Dividends page compares them (chart "Dividends you entered vs. market data" and a differs tag); Use market data replaces the hand-entered row, Delete removes it together with its purchase. Feed rows cannot be deleted — the next sync would add them back; switch reinvestment off for the holding instead.
• "Market-suggested basket" says "not available right now" → Yahoo could not be reached from the app container (or the benchmark has too little history); podman logs site-pf | grep benchmark. The rest of the page is unaffected.
• Build fails on a dependency → no wheel for Python 3.12 (the --only-binary guard); pick a version with a wheel, do not install a compiler into the image.

---

8.5 Using the application¶

8.5.1 Web GUI, roles and first run¶

Open https://pf.sibernet.com.tr. Everything the API can do is in the GUI (the API stays for a later mobile app).

First run. While no administrator exists the page asks for the administrator password. It also needs the setup code that the app prints to its log at start (so only someone with host access can claim the system):

podman logs site-pf | grep FIRST-RUN        # printed at start while no administrator exists, and when the first-run page is opened without one; valid until used or the next start

The administrator created there is the Owner (user name admin unless typed otherwise).

Roles.

	User	Administrator	Owner
Portfolio, trades, dividends, charts, analysis	yes	no (403 on every data endpoint)	no
Create / deactivate accounts, set temporary passwords, reset 2FA, require 2FA, set e-mail / recovery, unlock	no	yes, for users	yes, also for administrators
Create other administrators	no	no	yes
2FA	mandatory (PF_REQUIRE_2FA=true); QR code at the first login	optional (can be added later in My account; an enforcement per account is possible)	like an administrator

Several users and several administrators are possible. The Owner cannot be deactivated. New accounts get a temporary password (the GUI can generate one and shows it once); the person must choose their own at the first login. Password rules: at least 12 characters, upper and lower case, a digit.

Language (1.1.13). Every text of the screens comes from strings.csv (in the app: one row per key, one column per language, header key,en,tr). Settings (My account for administrators) → Language: As the browser or a language; the page reloads in it and numbers follow it (1.234,56 in Turkish). An empty cell shows the English text. Messages written by the server (errors, the analysis reasons, e-mails) are still English; they follow in a later version.

Labels (administrators, 1.1.13). Labels page: download the CSV (comma, or semicolon for Excel with Turkish settings; UTF-8 with BOM), change any text in Excel or LibreOffice, check the file, upload and apply — at once, without a release; Back to the built-in texts undoes it. Only the cells that differ from the built-in file are kept (table ui_labels), so a later version still brings its own new and corrected texts and your changes stay on top. A new column with a language code (de, fr, ar …) plus its name in the row lang.name adds a language. A file with a {placeholder} missing or unknown, a key twice, or not in UTF-8 is refused whole and nothing changes. The texts reach the page as /i18n.js (public: the login page needs them; nothing in it is secret). Right-to-left languages would also need layout work.

Staying logged in (1.1.12). A full login (password and, where needed, the 2FA code) sets an HttpOnly cookie pf_rt (Secure, SameSite=Strict, path /api/v1/auth) that the page itself cannot read. The page keeps only a short access token (15 min, PF_ACCESS_TOKEN_MINUTES) in memory and renews it from the cookie: at load (so F5, Back and a new tab stay logged in) and when a request comes back 401. The cookie is replaced at every use (rotation); only its sha256 is stored (table auth_refresh). A login ends after 12 hours unused (PF_REFRESH_IDLE_HOURS) or 7 days after the password was typed (PF_REFRESH_MAX_DAYS). If an already replaced cookie comes back later than 30 s (a copied cookie), that whole login is ended. Every login of the account ends — refresh cookies revoked and access tokens refused at once (users.sessions_valid_after) — on Log out, a password change or reset, a 2FA change and deactivation; the browser that changed its own password or 2FA goes on with a new cookie. Logging in with a temporary password or for 2FA enrolment does not set the cookie.

2FA login. At the first login a user who needs 2FA gets a restricted session that can only enrol: the page shows a QR code (and the secret for manual entry); after the 6-digit code is confirmed the session continues. Later logins ask for the code (each code works once; ±30 s clock tolerance).

Lost password / lost authenticator.

Case	What happens
Lost password	Administrator: Users → Reset a password (temporary password, forced change at the next login).
Lost authenticator (password known)	Administrator: Reset 2FA; the person enrols again at the next login. If the account has an e-mail address, a notice is sent and the password cannot be changed by the person for 24 hours (PF_PW_LOCK_HOURS).
Lost both	Administrator: Reset a password with "also remove the old 2FA" — one step; the forced password change at the next login stays allowed, enrolment is repeated.
Self-service	Only if an administrator gave the account an e-mail address and ticked allow e-mail recovery (Users → E-mail / recovery…), and SMTP is configured. Login page: Forgot password / Lost authenticator → an e-mail with a single-use link (30 min; it dies with any later password or 2FA change; the link travels in the URL fragment, not in server logs). Lost authenticator also asks for the current password, then removes 2FA, sends a notice and starts the 24 h password lock; Forgot password is refused while that lock is on. The reply to a request is the same for every account, so nobody can probe which users exist.
Nothing configured	Without PF_SMTP_HOST no mail is sent and the administrator path above is the only one. The login page always shows Forgot password and Lost authenticator; without a mail server the page tells the person to ask the administrator.

On the host (break-glass, no GUI): podman exec -it site-pf python -m app.cli list-users | set-password NAME | unlock NAME | reset-2fa NAME | set-role NAME user|admin | create-user NAME [--admin]. The password is typed at a hidden prompt, never given as an argument.

Data isolation. Every query filters on the logged-in user's id; another user's transactions, dividends and settings answer 404, not 403. Instruments (/assets) are a shared catalogue; ownership exists only through transactions.

8.5.2 Pages (user)¶

• Portfolio — Total wealth (large figure, decimals small) in the display currency chosen at the top right of the card (TRY, USD, EUR, GBP, or any code with a Yahoo rate; saved per user), the change over the chosen period as a green or red pill, and a chart: 1D, 3D, 1W, 1M, 3M, 6M, YTD, 1Y, All. The line is green when the portfolio gained over the period and red when it lost; "gain" excludes money you paid in or took out during the period (a deposit of money is not a win). The soft fill, the dashed level and the dot at the end are drawn the same way on every chart. Prices are daily closes, so 1D and 3D have few points. Below: totals (with Interest received once a deposit has interest), positions, Holdings: market analysis and suggestion, Ideal basket vs. your portfolio, weight by holding, risk. Every symbol in these lists opens that holding's own page. The Positions and Holdings analysis tables open grouped, with a separator row per group — US Stocks, ETFs, BIST (symbols ending .IS), Turkish Funds, Interest, Crypto — and A to Z inside each group; a click on any other column header sorts one flat list by it (the separators disappear), a second click reverses, and a click on Asset brings the groups back. Gain by group (1.1.14) sits under the chart and follows the same period buttons: one bar per group (US Stocks, ETFs, BIST, Turkish Funds, Interest, Crypto) from a middle line — gains to the right, losses to the left — with the group's share of today's wealth next to its name. The bar is what the prices earned, without the currency; where the currency moved it, a dot on the bar and the ● figure under the amount give the group's gain with the currency. The currency's part is in the last bars, one per currency the instruments are quoted in (Currency effect TRY, later EUR …; none for instruments already in the display currency), so the bars add up to the period's gain above (same measure: change in value minus money paid in or taken out). A click on a group lists its instruments with their share and gain. The total wealth chart, the holding chart and the Market chart show the date and value under the pointer (mouse hover, or a tap or click on a touch screen).
• Holding (menu item, or click any symbol) — one holding on one page: first the My position card — quantity, total value, average cost, share of the portfolio, Today (move of the last session × your quantity) and Total return (amount and %) — then the details (last price, unrealized and realized P/L, dividends, DRIP units; unrealized = today's value of what you still hold minus its cost, realized = profit locked in by selling). Amounts on this page are in the asset's own currency (TRY for a BIST stock), not the display currency; a price chart with the same period buttons and green/red line, with markers for your operations (buy ▲, sell ▼, dividend ◆, interest ●; hover for date, quantity, price) and, under it, every buy, sell, dividend, reinvestment and interest line of that asset with the quantity held after each. A deposit shows its balance instead of a price. Edit (own buys and sells only) turns the row into a small form: instrument, buy/sell, date, quantity, price, fee — so a wrongly typed ticker is corrected in place; both instruments are re-checked and their dividends recomputed. A Splits and bonus issues box appears when the instrument had one.
• Holdings analysis — one row per holding with weight, unrealized P/L, RSI, trend and a suggestion — BUY, ACCUMULATE, HOLD, REDUCE, SELL — and the reasons. It is a score from six rules (RSI over 70 / under 30, MACD against its signal line, price against the 50-day average, 50-day against 200-day average, Bollinger bands): +3 or more BUY, +2 ACCUMULATE, −2 REDUCE, −3 or less SELL, otherwise HOLD. Technical signals only — they know nothing about fundamentals, taxes, your goals or your other assets. Deposits are not analysed. Information, not investment advice.
• Ideal basket vs. your portfolio — four boxes at the top say what to add or remove per class (Deposits, Funds, Stocks, Crypto) to reach your ideal basket; below, the ideal and the real mix as bars and a table. A class within 5 points counts as on target. The Market-suggested basket box (§8.5.6) sits inside this card.
• Trades — (instrument list: choose an existing instrument and a type selector and Remove this instrument appear; both work only while no trade or dividend uses the instrument, e.g. after all its trades were deleted) new trade; for a deposit the form asks for the amount, the yearly rate and the term in days (or monthly, or no term), the tax withheld and what happens at maturity (§8.5.4); Deposits and maturities (the choice can be changed there); Update balance; Interest received; one history of trades, dividends (with per-share), dividend reinvestments and interest, grouped by year with every year closed until you open it (filters for instrument, type, year and a date range open the matching years; Rows per year: 50 / 100 / 200 / all, then Show more), each line with a Delete where it is allowed. The same Delete is on every holding's own page, which is the easiest way to remove an entry made under the wrong instrument. One currency on the form (1.1.13): Currency next to Price is the currency of this trade (what you paid in: a coin bought in TRY on one broker and in USD on another). It starts as the currency the price source quotes the instrument in (US stocks and coins USD, Borsa Istanbul and TEFAS TRY). The instrument's own currency is no longer chosen: PF takes it from the source (BTC-USD is USD whatever the form says); only a deposit asks for its account currency. Get market price gives the close in the chosen currency (converted at that day's rate when needed); changing the currency or the date fetches a market price again, and numbers typed by hand (price, total, fee) are converted at that day's rate, so Price and Total always read in the currency next to them. The same conversion is on the Edit row of a holding page. Prices and fees keep 8 decimals (a longer converted figure is rounded, not refused). Bonus (received free) next to Side (only with Buy / Pay in): a broker's gift or a bank's campaign — no fee, the price is the day's close, it counts as income (Gifts and bonuses) and not as money paid in (§8.5.8). Next to the instrument list a currency selector corrects an instrument saved in the wrong currency (§8.5.8). The form takes any two of Quantity, Price and Total (before fee); a broker shows the price rounded, so enter the share count and the amount and leave Price empty. The fee is separate and counts as part of what you paid; the form shows the total with the fee (a buy: total + fee, a sell: total − fee) next to the button. The Instrument box starts empty ("Choose an instrument…") so a trade cannot go to the wrong instrument by default. A price can be typed in another currency than the instrument's (Price currency next to the price: a coin kept in USD that you bought in TRY): PF converts price and fee at that day's market rate and the note keeps what was paid and the rate used (paid_currency on POST /transactions and PUT /transactions/{id}; for a row typed in the wrong currency use Edit with the right one). For type crypto a bare symbol is tried as <SYMBOL>-USD first (on Yahoo a bare BTC is a fund of about 38 dollars, the coin is BTC-USD). The Positions table has a Currency column: Avg cost and Price are in the instrument's own currency, Value and Total return in the display currency.
• Dividends — reinvestment switch per holding, sync, chart, Record a dividend by hand, the chart Dividends you entered vs. market data, history. A hand-entered dividend is compared with the market feed (matches market data / differs with the reason / cannot verify); Use market data replaces it, Delete removes it with its purchase.
• Market (the study of one instrument: price with the 50- and 200-day averages and Bollinger bands, RSI and MACD on one time axis, ranges 3M to All; move the pointer or tap and the box below reads out that day — indicator values, the rules that fired with their points, the score and suggestion the rules gave on that day (only data up to that day is used) and what the price did since — with your own buys and sells on the price line; How to read these panels explains each indicator; below it the table of today's values), Settings (Dividends: reinvest by default; Ideal basket: radio buttons Conservative / Balanced / Growth / My own — a preset locks the four fields, My own unlocks them and needs a total of exactly 100 %; 2FA; password).
• About — the small version label next to PF Portfolio in the top bar (for example v1.1.10); click it for the version, how long the app has been running, database state and the date of the latest stored price. Handy for screenshots when something needs support. GET /api/v1/about (login needed).
• Administrators see Users and My account only.

8.5.3 Dividend reinvestment (DRIP)¶

Rule	Behaviour
Switch	per holding (PUT /api/v1/holdings/{asset_id}/reinvest), else the user default (PUT /api/v1/auth/profile drip_default), else PF_DRIP_DEFAULT (on)
Entitlement	shares held at the close before the ex-date; a purchase on the ex-date earns nothing
Amount	shares × per-share × (1 − withholding)
Reinvest on	a BUY (source: drip, fee 0) is booked at the first close on/after the pay date; quantity = net ÷ price, rounded down to 9 decimals (as brokers such as Midas keep them); the rest is kept as cash_residual
Reinvest off	the net amount is recorded as cash income (status: paid)
No price yet	status: pending_price; the daily sync completes it (the later dividends of that asset wait, so the share count stays right)
Compounding	reinvested shares are normal shares and earn the next dividend
Idempotent	one row per user, asset and ex-date — syncing twice does nothing
Manual entry	POST /api/v1/dividends for companies the feed does not know; optional withholding, reinvest, reinvest_price. An entry within 30 days of another dividend of the same holding is refused with 409 ("looks like the same payout") unless ?force=true (the GUI asks). DELETE /api/v1/dividends/{id} removes a hand-entered row with its purchase and recomputes the later ones (feed rows: 409). GET /api/v1/dividends/verify compares hand-entered rows with the feed (amount within 2 % or equal after rounding to 2–4 decimals; ex-date within 3 days → ok; same amount but another date → date_differs; otherwise amount_differs / no_data); POST /api/v1/dividends/{id}/use-market replaces the row with the feed's version
Corrections	adding or deleting a manual trade recomputes that asset's dividends; PUT .../reinvest?apply_to_history=true and POST /api/v1/dividends/rebuild/{asset_id} do it on demand. DRIP purchases cannot be deleted by hand (409)
Returns	reinvested dividends raise the cost basis but are not new money: money_invested counts only your own purchases, total_return = market value + sale proceeds + cash dividends − money invested

Limits to know: Yahoo reports ex-dates only, so the pay date is ex-date + PF_DIVIDEND_PAY_LAG_DAYS (0) — for a company that pays about three weeks after the ex-date (NVIDIA) the reinvestment price is therefore the one around the ex-date, a small difference; the dividend is assumed to be in the asset's own currency; TEFAS funds and crypto have no dividend events; withholding is one global rate unless you pass it per manual entry.

8.5.4 Deposits and interest¶

A deposit (savings, time or flexible account) is an instrument of type deposit: no price feed, one unit = one unit of its currency, valued at its balance. Any currency works (TRY, USD, QAR, ...). The Qatari riyal and the other currencies officially fixed to the dollar (QAR 3.64, SAR 3.75, AED 3.6725, BHD 0.376, OMR 0.3845, JOD 0.709 per USD) always use that fixed rate, never a market quote.

Rule	Behaviour
Pay in, annual	a buy with the amount, the yearly rate in percent (gross), the term in days (for example 34 % and 32 days; the field suggests 32, 46, 91, 181, 367) and the withholding %; maturity = pay-in date + days. Rate and days must come together (422 otherwise). Price is forced to 1
Pay in, monthly (older form)	the monthly rate, the term in months (1–120) and the withholding %; still accepted and shown as before
Pay in, flexible	flexible: true (GUI: no term, daily-interest account): no rate, no maturity; only the balance is tracked (see Update balance)
Expected interest	annual: amount × rate / 100 × days / 365; monthly: amount × monthly rate × months; minus withholding = net; rounded to 2 decimals. Shown in Deposits and maturities (GET /api/v1/deposits) with status running, due or booked
At maturity	per pay-in, changeable until it is settled (PUT /api/v1/deposits/{id}/action): manual (you book the interest, as before), close (principal + net interest are withdrawn), renew_principal (same, the principal goes into a new term, the interest leaves as gain), renew_all (principal + net interest go into a new term: compounding)
Automatic booking	for the three automatic actions PF books the net interest on the maturity date (note auto: ..., the tax in the fee column), withdraws the term and, for a renewal, opens the next term with the same rate, days, tax and action (marked auto-renewed). It runs when the pages are opened and in the nightly sync; a term missed for several periods is settled period by period, idempotently. The renewal rate is an assumption: if the bank changed it, delete the auto row and enter the real pay-in
Booking by hand	manual terms: press Book interest (pre-filled, both values editable to what the bank credited) or use Interest received for interest that belongs to no listed term. POST /api/v1/interest; a pay-in takes its interest once (409 after)
Update balance	for an account with daily interest and a rate you do not know: type the balance the bank shows (monthly is enough); the difference to PF's balance is booked as interest (POST /api/v1/deposits/balance, optional date). Same balance books nothing; a lower balance is refused (book the withdrawal first)
Bank statement import	Trades → Import a bank statement: choose the account and the file (.xlsx, .xls or .csv), Check the file shows what would be booked, Import books it (POST /api/v1/deposits/import-statement, form fields asset_id, dry_run, file; 5 MB). Two layouts are recognised: overnight sweep (salary account whose spare money goes into a nightly deposit: opening line, then principal, gross interest and tax) and term deposit (lines Faiz Geliri with "%rate … N günlük" and Vergi Kesintisi, plus the balance). Everything else in the file (salary, bills, transfers) is ignored and never stored; the file itself is not kept. Accents are ignored when matching (older lines of one bank write "Acilisi", newer "Açılışı")
What an import books	one interest line per month (sweep) or per term (term deposit): net credited, tax in the fee column, period_from and the average balance, so the yearly rate follows; and one balance line that sets the balance to the amount swept at the end of that month (a pay-in or withdrawal for the difference; the first one is dated at the start of the first period). Importing the same file again changes nothing; a shorter statement never overwrites a fuller month; the first closing of a sweep file whose opening is before the file starts is left out The preview also warns about lines typed by hand on that account inside the period of the file (the statement already holds that money and interest, so they would count twice): delete them under Trades, then import.
Interest by month	per account with imported lines: month (or term), balance at the end, gross interest, tax, net, gross and net % per year (simple, scaled to 365 days) and, for accounts not in USD, the net % per year in USD and how much the account's currency moved against the dollar in the same days (the day's rate from the market feed; no dollar columns when no rate is available). GET /api/v1/deposits/interest-summary
Effect	interest raises the balance and counts as gain, not as money paid in: money_invested stays, total_return rises. Withdrawal and re-deposit of a renewal sit on the same day and cancel out
After booking	the row shows the realized yearly yield after tax
Not for deposits	no dividend reinvestment, no technical analysis, no price chart (the Holding page draws the balance)

Deposit rates change; the latest pay-in's rate is shown as an information line in the market-suggested basket and does not move the basket.

8.5.5 Splits and bonus issues¶

A broker books a split or a bonus issue (BIST: bedelsiz) by multiplying your share count and dividing the price. PF does the same on its own: enter the trade the way it happened (old share count, old price) and PF counts it in today's share unit — quantity × ratio, price ÷ ratio, so the money you paid never changes. Example: 10 ISCTR at 22 TL on 24 Oct 2023, then the 27 Feb 2024 bonus (ratio 2.4999) → PF shows 24.999 shares at 8.80 TL, the same figures as the broker. A trade dated on or after the split day is already in the new unit.

• Source: Yahoo's split list, read when a holder syncs (adding a first purchase, Check for new dividends now, the daily run). A new split purges the stored price bars of that instrument (they are fetched again, split-adjusted) and recomputes the dividends of every holder: feed dividends are fetched again in the new unit; reinvestment (DRIP) purchases are always in today's unit; a dividend you typed by hand keeps the money (its shares are counted in the unit of that day).
• Administrator → Splits: add a split Yahoo has wrong or late (instrument, effective date, new shares per old share: 2 for 2-for-1, 2.5 for a 150 % bonus) or remove one. A split that came from Yahoo returns at the next sync unless it is wrong at the source.
• Do not type the post-split share count of an old trade: it would be multiplied a second time. Trades already entered in the new unit before this release must be changed back to what was bought (Edit on the holding page).
• The Get market price button gives the price of an old day in the unit of that day (Yahoo's value × the split ratio), so it matches what you paid.

8.5.6 Ideal basket and the market-suggested basket¶

The ideal basket is four whole percentages (Deposits, Funds, Stocks, Crypto) that add up to 100, set in Settings. The presets are Conservative 45/30/20/5, Balanced 20/35/40/5, Growth 5/20/65/10 (deposits/funds/stocks/crypto); My own is stored in users.ideal_basket, a preset is the risk profile itself.

Using the suggestion does not move the basket further. Until 1.1.3 the button saved the tilted basket as the ideal one, and the next suggestion tilted that again (17 → 14 → 11 %). Now the user's own basket is kept in users.ideal_basket_base while the suggestion is in use, the suggestion is always worked out from it, Update to today's market view refreshes it, and Back to my own basket returns. Typing a basket in Settings is the user's own again.

The market-suggested basket starts from the user's own basket and tilts it with a few explainable rules on benchmark closes (cached 6 hours, never stored): a trend filter (price against its 200-day average) and 6-month momentum for S&P 500 and BIST 100 read in US dollars (index ÷ USD/TRY, so inflation does not make a lira index look bullish), Bitcoin, and the VIX as a risk-off flag. Stocks move up to ±PF_SUGGEST_MAX_TILT points, crypto up to ±2.5 per signal point within the same cap; what risk assets gain or lose is taken from / given to deposits and funds, and the total stays exactly 100. Every tilt has its reason in plain words. Nothing changes until the user presses "Use this as my ideal basket". Rule-based reading of a few prices, not advice, and it knows nothing about the user's taxes or goals.

8.5.8 Currencies, costs and bonuses (1.1.13)¶

Every money movement is converted at the rate of its own day; today's value at today's rate. For the display currency D (the currency switch) and an instrument in currency A, PF keeps the average-cost accounts twice, in A and in D:

• Buy: cost in D = the amount actually paid when the trade was typed in D (paid_amount), otherwise (quantity × price + fee) × rate A→D of the trade day.
• Sale: the share of the cost sold leaves both accounts; proceeds in D at the sale day's rate (or what was received when typed in D); realized P/L in D = proceeds − cost removed. Bought and sold at the same dollar price: no gain in USD, a gain in TRY when the dollar rose in between.
• Dividends and interest: at the rate of their pay day. Splits change the quantity only.
• Value = quantity × price today × rate today; unrealized = value − cost in D; of which currency effect = cost in A × rate today − cost in D (the part of the gain that is the currency's move, not the price's; shown on the Portfolio page when not zero).
• The period chart uses the same rule: each day's value at that day's rate, each payment at its own day's rate.
• A holding's own page shows its amounts in the instrument's own currency, worked out in that currency.

Example (the BTC case): 0.00012 BTC for 513.38 TRY on 2025-05-27 (BTC about 108 000 USD, USD/TRY 38.98). In USD the cost is 13.17 USD; in TRY it is exactly 513.38 TRY; today's value is 0.00012 × today's price × today's rate.

Bonus: a buy marked Bonus (received free) (source bonus): worth the day's close, booked as income on that day (Gifts and bonuses), held afterwards like a purchase of that value, never counted as money paid in; sold later, its cost is that value. A corporate bonus issue (bedelsiz) is not this: it is a split (§8.5.5).

Instrument saved in the wrong currency (before 1.1.13 the form asked for it: BTC-USD saved as TRY values a dollar price as lira): the currency selector next to the instrument on the Trades page (POST assets/{id}/currency) sets the right currency and converts every trade of it at the rate of its own day; what was paid stays in paid_currency / paid_amount and the note. Refused while dividends of it exist or another account has trades in it. Get market price warns when an instrument's stored currency differs from its source's.

Data (1.1.13): transactions.paid_currency, transactions.paid_amount (filled at start from the notes of trades typed in another currency, once), source value bonus.

Deposit renewals (1.1.14). A renewal withdraws the old term and pays the new one in on the same day (automatic at maturity, or typed by hand). The part paid back in on that day is an internal transfer: neither Money invested nor proceeds, so Money invested and the return percentage are no longer inflated by every renewal. Interest taken out stays a proceed (gain); fresh money added on top stays money in. Existing renewals are counted this way at once (calculated, nothing stored).

Days without a price (1.1.14). A fund in liquidation can be published with price 0 on some days. Those days (and any without a positive close) are left out of charts, risk, analysis and the Market study, and the current price is the last real one. In 1.1.13 such a fund made /portfolio/risk and /portfolio/analysis answer 500, so the Portfolio page showed Request failed.

Group split (1.1.14). GET /portfolio/history returns groups: per instrument its group (0 US Stocks … 5 Crypto, the page's order), gain over the period, currency (the instrument's), fx (the currency's part: each day yesterday's value in the instrument's currency times that day's move of the rate), price (= gain − fx) and today's value.

8.5.7 Endpoints (/api/v1, bearer token except login)¶

Area	Calls
Setup	GET setup/status, POST setup/admin (first run, needs the setup code)
Auth	POST auth/login (a full login sets the pf_rt cookie), auth/refresh and auth/logout (cookie + header X-PF-Refresh: 1), PUT auth/language ("" = the browser's), auth/2fa/setup (QR as data URI), auth/2fa/confirm, auth/2fa/disable, auth/password, auth/recover/request, auth/recover/confirm; GET auth/me; PUT auth/profile (risk_profile, drip_default, display_currency, ideal_basket = {"deposit":20,"fund":35,"stock":40,"crypto":5} summing to 100, reset_ideal_basket)
Labels	GET /i18n.js (public: every text, every language), GET admin/labels (status, your changes), GET admin/labels.csv?sep=comma|semicolon, POST admin/labels?dry_run=true|false (multipart file), DELETE admin/labels (administrators)
Admin (administrators only)	GET/POST admin/users, POST admin/users/{id}/reset-password (remove_2fa), reset-2fa, require-2fa, recovery (e-mail, self-service), unlock, active
Instruments	POST assets/{id}/currency (currency: correct a wrong one, trades converted at their days' rates), GET market/price (currency: the close in it; answers quote_currency and quote_price too), GET market/fx?base&quote&on, POST assets (stock/crypto = Yahoo symbol such as THYAO.IS, AAPL, BTC-USD; fund = TEFAS code; deposit = any name, no lookup; looked up on creation, ?verify=false skips it), GET assets
Trades	POST transactions (buy/sell, quantity, price, fee, trade_date, paid_currency, bonus: true with side buy and no price = the day's close; selling more than held is refused), GET transactions (asset_id, source, paging), PUT transactions/{id} (correct a hand-entered buy or sell, the instrument included), DELETE transactions/{id}, GET activity (trades, dividends and interest in one list), GET deposits, POST interest
Dividends	GET dividends, POST dividends (?force=true), DELETE dividends/{id} (hand-entered only), GET dividends/verify, POST dividends/{id}/use-market, POST dividends/sync (6 per hour), POST dividends/rebuild/{asset_id}, GET/PUT holdings/{asset_id}/reinvest
Portfolio	GET portfolio (positions, totals in the user's display currency, FX conversion), currencies, portfolio/history?period=1d|3d|1w|1m|3m|6m|ytd|1y|all (points + summary: start/end value, money in, gain, gain %), portfolio/analysis, portfolio/allocation, portfolio/rebalance, portfolio/suggestion, portfolio/risk, holdings/{asset_id}/detail (price or balance series, position, every operation)
Splits (administrators)	GET admin/splits (splits + the stocks/ETFs to pick from), POST admin/splits (asset_id, split_date, ratio), DELETE admin/splits/{id}; users see the splits of a holding in GET holdings/{id}/detail
Market	GET market/{asset_id}/indicators, market/{asset_id}/history

portfolio/rebalance compares the asset-class mix (deposits / funds / stocks / crypto) with the user's ideal basket (a preset of the risk profile or the user's own) and names the amount to add or remove for any class more than 5 points off; portfolio/suggestion returns the market-suggested basket with its reasons (§8.5.6). Indicators, rebalancing and suggestions are information, not personal investment advice.

---

Document history¶

Version	Date	Status	Changes
1.18	2026-11-03	Latest	App 1.1.14: Gain by group under the wealth chart (same period; share of wealth, price part, gain with the currency, currency effect; §8.5.1), deposit renewals are internal transfers (Money invested no longer inflated), days with price 0 no longer break risk / analysis (the Request failed Portfolio page), Turkish dotted İ in symbols, .IS symbols are stocks (§8.5.8). No schema change
1.17	2026-11-03	Superseded	App 1.1.13: one currency on the trade form (the instrument's comes from the price source; market price in the chosen currency; changing currency or date refetches or converts), prices rounded to 8 decimals instead of refused, costs at the rate of their own day and the exact amount paid when typed in the display currency, of which currency effect, holding page in the instrument's own currency (§8.5.8); Bonus (§8.5.8); currency correction of an instrument; languages (English, Turkish) and the administrators' Labels page (§8.5.1); endpoints (§8.5.7); rollback note (§8.3.1). Schema: table ui_labels, columns users.language, transactions.paid_currency, transactions.paid_amount, source value bonus (added by the app; back up first)
1.16	2026-11-02	Superseded	App 1.1.12: the login survives a reload — HttpOnly refresh cookie with rotation, 12 h idle / 7 days absolute, theft detection, every login ends on log out, password / 2FA change, reset and deactivation (§8.5.1); Back no longer needs the in-app guard; endpoints auth/refresh, auth/logout (§8.5.7). §8.3.1: upgrade from deploy-publish.sh, pf-upgrade.sh 1.1 (sha256 from releases/CHECKSUMS.txt, tidy, rollback text), rollback 1.1.12 → 1.1.11. §8.3.3: the pg_dump notice, replacing pf_db itself. Schema: table auth_refresh, column users.sessions_valid_after (added by the app; back up first). App version in the overview corrected (it still said 1.1.8)
1.15	2026-11-02	Superseded	App 1.1.11: the Price currency selector on the Trades form and on a holding's Edit row (promised in 1.18's notes but never built: only the API had it), Get market price converts to the chosen currency, bare crypto symbols look up the -USD coin.
1.14	2026-11-02	Superseded	App 1.1.10: About unchanged; new: remove an unused instrument and change its type (Trades form, next to the Instrument list; only while no trade or dividend uses it), typing BTC as crypto no longer finds an old plain BTC (the fund) but opens the coin BTC-USD, the statement preview warns about hand-typed lines inside the file's period (they may be counted twice), Weight by holding labels are left-aligned and may wrap. No schema change
1.13	2026-11-01	Superseded	App 1.1.9: About window (version shown next to the brand in the top bar; click for version, running time, database state, latest stored price date), the price-source message now reads "Connection timeout: please try later", and Turkish funds (TEFAS: close price only) get their Market study / suggestion again instead of an ATR error. No schema change
1.12	2026-10-31	Superseded	App 1.1.8: bank statement import for an overnight-sweep account and for a term deposit (.xlsx, .xls, .csv; one interest line and one balance line per month or term; §8.5.4), Interest by month table (balance, gross, tax, net, yearly rate, and in USD against the currency's move), price currency on trades (a TRY purchase of a USD coin is converted at that day's rate), crypto symbols tried as <SYMBOL>-USD first, Currency column in Positions, Forgot password always on the login page, no-term deposit form hides the tax and maturity fields, price-source calls are retried twice when the connection drops (a plain message instead of the library's text). Schema: new columns transactions.period_from, avg_balance (added by the app; back up first); new dependency xlrd
1.11	2026-10-31	Superseded	App 1.1.7: deposits: yearly rate and term in days (34 % / 32 days) with withholding, automatic interest at maturity with a per-term choice (close, renew principal, renew principal + interest, or by hand), deposits in any currency (QAR, SAR, AED, BHD, OMR, JOD use their fixed dollar peg), Update balance for daily-interest accounts, no-term (flexible) deposits (§8.5.4). Schema: new columns transactions.rate_annual, term_days, at_maturity (added by the app itself; back up first)
1.10	2026-10-31	Superseded	App 1.1.6: Market study — price with averages and Bollinger bands, RSI and MACD on one axis; pointer or tap reads out the indicators, the rules that fired, the score and suggestion of that day (no later data used) and what the price did since; your trades on the price line; a How to read these panels guide (§8.5.2). Trend and HOLD labels are coloured (bullish green, bearish red, neutral amber). No schema change
1.9	2026-10-31	Superseded	§8.3.1 points to pf-upgrade.sh (§5.7 of the host sheet) for the application upgrade; no application change (app 1.1.5).
1.8	2026-10-31	Superseded	App 1.1.5: Holding page opens with a My position card (quantity, total value, average cost, share of the portfolio, today's move, total return with %), the duplicated boxes are gone from the details, amounts are shown in the asset's own currency (a BIST stock in TRY, not the display currency), Unrealized P/L (unsold shares) and Realized P/L (from sales) carry a one-line explanation, and the description columns of the tables are left-aligned and wrap (they were right-aligned and cut off); no schema change
1.7	2026-10-31	Superseded	Numbered headings, chapter 8 of the dmz-web documentation: the sections are 8.1 to 8.5 and the former letters are numbers (A to E of Operations = 8.3.1 to 8.3.5; the Using chapter: Web GUI 8.5.1, Pages 8.5.2, DRIP 8.5.3, Deposits 8.5.4, Splits 8.5.5, Ideal basket 8.5.6, Endpoints 8.5.7); every cross-reference updated (3.C is now §8.3.3, 3.D §8.3.4). No application change (app 1.1.4).
1.6	2026-10-31	Superseded	App 1.1.4: splits and bonus issues (read from Yahoo, trades stay as entered and are counted in today's share unit; administrator page Splits; §8.5.5); Positions and Holdings analysis grouped (US Stocks, ETFs, BIST, Turkish Funds, Interest, Crypto) with separator rows; hover or tap readout on the wealth, holding and Market charts and tooltips on the bar charts; Edit on the holding page (instrument, date, quantity, price, fee); the All period percentage is gain over the capital at work (modified Dietz) instead of over the first day's tiny value; the market-suggested basket no longer drifts each time it is adopted (users.ideal_basket_base, Back to my own basket); Get market price returns the price in the unit of that day. New table asset_splits, new column users.ideal_basket_base; tarball pf-app-1.1.8.tar.gz.
1.5	2026-10-31	Superseded	App 1.1.3: browser Back moves between the screens of the app instead of leaving it (the login token lives in memory, so leaving the page logged you out); Delete on the holding page; Trades history by year, closed by default, with filters and a row limit per year; Commissions paid (counted in the cost, shown separately); the Positions and Holdings analysis tables start sorted by instrument A to Z and sort by any column header (click again to reverse), the holding selector is A to Z too; trade-form text for Quantity + Total, the total with the fee shown before you press the button, and the Instrument box starting empty; exchange rates for pairs Yahoo does not quote (TRY/QAR): the reverse pair inverted, then through the US dollar, and for currencies pegged to the dollar (QAR 3.64, SAR 3.75, AED 3.6725, BHD 0.376, OMR 0.3845) the official peg when there is no quote at all; the stray word "null" on the Trades page; §3.A: wait loop for the health check, the sed for the unit, which commands are root only; the tarball is pf-app-1.1.3.tar.gz. No schema change.
1.4	2026-10-31	Superseded	App 1.1.2: ideal basket in Settings (presets as radio buttons or "My own") with four classes incl. deposits, "add / remove" summary and the market-suggested basket (S&P 500, BIST 100 in USD, Bitcoin, VIX; cap PF_SUGGEST_MAX_TILT); deposits with monthly rate, term and withholding, interest booked by hand, Deposits and maturities; Holding pages with price chart, operation markers and every operation; dividend check against market data, delete and duplicate warning for hand-entered dividends; fractional shares to 9 decimals; Currencies page for the administrator (pick from a list or type a code; a code is accepted only when Yahoo has a rate for it; the list feeds the display-currency switch and the currency dropdown of new instruments); trade form with Total and Get market price for this date (close of that day, or the last trading day before it; you can overtype it, and typing a price yourself always works); (any two of quantity / price / total, the third is calculated); instrument type fund / ETF on Yahoo (counts as fund in the allocation, priced and paying dividends like a stock; an existing stock can be switched on its holding page, Counts as); a newly bought stock fetches its dividend history at once; BRK.B-style symbols are found as BRK-B; new look for charts (soft fill, dashed start level, end dot, large figures) and the self-hosted Inter font. Migrations: users.ideal_basket, five transactions columns, enum values deposit, etf and interest, share columns widened to 9 decimals, new table app_settings (idempotent). §3.A: upgrade check commands and rollback caveat; §4: new entries; §5 B-1 and B-2; 51 tests. pf-install.sh 1.3.
1.3	2026-10-29	Superseded	App 1.1.1: web GUI (first-run administrator page with setup code, roles User / Administrator / Owner, QR enrolment, mandatory 2FA for users and optional for administrators, forced password change), total wealth with currency switch and period chart (green / red), holdings analysis with BUY / HOLD / SELL suggestions, admin-assignable e-mail recovery (optional SMTP), e-mail notice and 24 h password-change lock after 2FA removal, "reset password and remove 2FA" in one step. Seven added users columns (idempotent). pf-install.sh 1.2 (image tag 1.1.1, commented SMTP lines, first-run "Next" text). §5 rewritten; §3.A upgrade from the tarball; §4 entries; config variables; 38 tests.
1.2	2026-10-29	Superseded	The real application replaces the starter: login with TOTP 2FA (rate limit, lockout, replay protection, no public registration), transactions, dividend reinvestment (DRIP), Yahoo/TEFAS market data on a TimescaleDB hypertable, positions and allocation in the base currency, indicators, risk statistics, class-level rebalancing hints, admin CLI. pf-install.sh 1.1: --app-src instead of --init-app, image tag 1.1.0, longer start period. New §5 (users and 2FA, DRIP rules, endpoint list); §2 file map, config variables, tests; §4 entries for secret key, 429, authenticator codes, pending_price. Pins: greenlet added (SQLAlchemy async), PyJWT/bcrypt instead of python-jose/passlib.
1.1	2026-10-29	Superseded	Rewritten around pf-install.sh (one procedure instead of nine manual steps, with the live-vs-repo NPM Network= guard). Two networks (net-pf-db is Internal=true); DB healthcheck and Notify=healthy; explicit .volume unit; pinned images (2.31.0-pg16, site-pf:<tag>) and a fully pinned, wheels-only requirements.txt; secrets as hex (URL-safe) and the URL built with quote; /docs off; Access List option; Timescale-aware backup/restore, password rotation and DB upgrade; troubleshooting; history table. Fixes of the 1.0 draft: wrong diff expectation (+ vs >), NPM snippet repeating section headers, unpinned latest tags.
1.0	2026-10-29	Superseded	Draft (manual nine-step procedure). Never committed.