Architecture-fit sheet

Quick reference — the questions IT/QA open with

System architecture — schematic

How it runs on your estate: one request path, one process, one file — inside your perimeter — and the screening pipeline that turns a book into a supervisory return.

Processing pipeline — the same steps every screen follows, deterministic and stdlib-only:

Deployment topologies — you choose, we don't prescribe

• All three run the same engine and the same code; the difference is only where the process sits and what data it holds. Start simple and move later without a rebuild.

First install — from a bare VM to running

On-premise (tiers A/B). For managed hosting (tier C) there is nothing to install — we host it and provision your team a login. There is no public download or self-sign-up: installs are provisioned. Full commands are in web/DEPLOY.md.

1. Provision one Linux VM you control — CPU-only (~1 core / 1 GB is ample), with Python 3.11+ and Nginx. No database server, no GPU, no cloud account.
2. Place the release and build the runtime (three dependencies, nothing else):

   tar xzf portfoliocheck-<ver>.tgz -C /opt/portfoliocheck
   python3 -m venv /opt/portfoliocheck/.venv
   /opt/portfoliocheck/.venv/bin/pip install -r /opt/portfoliocheck/web/requirements.txt  # fastapi, uvicorn, python-multipart
   chown -R www-data:www-data /opt/portfoliocheck

3. Install as a service behind TLS — the systemd unit (User=www-data, memory-capped, port 8012) and an Nginx vhost proxying 127.0.0.1:8012 with a certificate (templates ship in infra/).
4. Choose the data posture on the unit's environment: default is the built-in analyser (pure local compute, offline); PORTFOLIOCHECK_OFFLINE=1 for a hard air-gap; or point PORTFOLIOCHECK_SAFEGROUND_URL / _FLOODGUARD_URL at the on-box engines to add the live engine overlay. Every external caller stays OFF unless explicitly enabled.
5. Provision accounts (no public sign-up):

   cd /opt/portfoliocheck && .venv/bin/python manage.py adduser \
       risk@yourbank.com 'strong-passphrase' --bank "Your Bank" --role maker

6. Verify — the install is not done until these pass:

   curl -s http://127.0.0.1:8012/health  # {"status":"ok", ... }
   curl -s http://127.0.0.1:8012/diag    # migrations_ok:true, schema stamped

7. Optional — calibrate once you have loss data: point PORTFOLIOCHECK_PARAMS at a JSON parameter set; its name then appears on every report.

Thereafter every update is applied with infra/update.sh (checksum → back up code + DB → apply → health-gate → auto-rollback) — see Fleet operations below.

Relationship to ORASS — we consume the pipe, we don't replace it

Bank of Ghana already runs ORASS (Vizor/Regnology) as its returns-submission channel. ORASS has no climate module — that is the gap this tool fills. PortfolioCheck is the analytics / computation layer, never a rival submission portal. A dedicated adapter (connectors/orass.py) is the seam, switched by one environment variable PORTFOLIOCHECK_ORASS_URL:

Integration surface (fits your existing stack)

• JSON API POST /api/screen — screen one property at the point of application from a loan-origination system (JSON in, JSON out; coordinates travel in the body, not the query string).
• CSV import/export for a whole book, plus a machine-readable BoG return (CSV + Word). No proprietary formats.
• GET /health liveness/version probe for your monitoring; the ORASS adapter above for the supervisory return.

Fleet operations — one codebase, many banks, no vendor access

• Every install runs the same code, pinned to a release tag; banks differ only by configuration (engine mode, air-gap, calibration parameter set, their own database) — never a code fork. There is one product to maintain, not one per bank.
• Updates flow outward as signed releases. infra/update.sh verifies the release checksum, backs up the current code and database, applies the release (never touching the data directory), restarts, health-checks and auto-rolls-back if the new version is not healthy — so a bad release can never leave the service down. Your IT runs it; we need no access to your box.
• Support without access to your data. GET /diag reports version, configuration flags and schema/migration health (no borrower data, no secrets); manage.py supportbundle writes the same as a PII-free file your operator can email us to diagnose an air-gapped install. We never see a book to support it.
• No agent runs inside your bank. All automation is on our side, over the fleet (triage, fix, test, release) — nothing autonomous with write access sits on your box.

Enterprise IT & data — scale, identity, retention, logging, DR

• Scale — it screens a whole book in one pass. The engine is pure-Python compute with no per-asset database round-trip and no external call; a 200-asset book screens in well under a second on one core, and the dashboard is recomputed in the browser so interaction adds zero load on the box. The upload guards you see — 2,000 rows for the built-in analyser, 80 for the live-engine path — are two single constants (MAX_ROWS_SEED / MAX_ROWS_LIVE at the top of web/app.py) that protect the shared public demo; an on-premise operator raises the analyser cap to the size of their own book. The live-engine cap stays modest only because it calls the engines serially — the built-in analyser has no such limit.
• Identity & SSO. Today the app authenticates with its own provisioned accounts (PBKDF2-HMAC-SHA256, server-side revocable sessions, role-based access, no public sign-up). For an enterprise SSO estate the standard pattern is Topology A: place it behind your identity-aware reverse proxy that enforces AD / SAML / OIDC before the request reaches the app. Native SAML/OIDC and reverse-proxy header trust are the identity item on the roadmap and are wired to your directory at integration time. No credential is ever stored beyond a salted PBKDF2 hash.
• Data retention & erasure (Act 843). Retention is entirely bank-controlled — the data is one SQLite file you own, on your schedule. A portfolio is deleted in-app by its owner (owner-scoped store.delete_portfolio), which removes the book and its quarter-over-quarter snapshots; the public demo and ephemeral uploads persist nothing. Because the store holds a pseudonymised asset id + location and no borrower PII, an Act 843 erasure request is satisfied at the bank's own system of record — deleting the corresponding portfolio here removes the screened copy.
• Logging & SIEM. Two streams. Operational logs go to stdout → journald (journalctl -u portfoliocheck), so any shipper (rsyslog, Filebeat, a Splunk forwarder) can forward them to your SIEM. Separately, a tamper-evident, append-only audit log — logins and failed logins, filed returns (with fingerprint), adaptation submissions, supervisory verdicts, account changes; each with who, when, target and source IP — lives in the same SQLite store and is viewable/filterable by a supervisor at /bog/audit.
• Disaster recovery & continuity (RTO/RPO). It is not on a real-time transaction path, so it needs no HA cluster. RPO = your last SQLite backup (copy one file); RTO = minutes — re-extract the release archive and restart, the same health-gated, auto-rolled-back path infra/update.sh uses. If you require redundancy, run active-passive behind your load balancer over replicated storage for that one file; screening is deterministic and idempotent, so a standby returns identical results.

Sizing, backups & operations

• One modest Linux VM, CPU-only, run as an unprivileged systemd service (User=www-data, memory-capped) behind your Nginx/TLS.
• Deploy is a reproducible archive → extract → restart; rollback is a re-extract of the previous archive + restart.
• Backup is a copy of the single SQLite file, taken independently of deploys; the deploy archive excludes the data directory by construction.
• Data residency: everything — app, database, uploads — stays on the host you control. OFFLINE=1 gives a hard air-gap with the built-in analyser fully intact.