Platform strategy

╔══════════════════════════════════════════════════════════════════════════════╗
║                    PLATFORM STRATEGY & ARCHITECTURE                          ║
╚══════════════════════════════════════════════════════════════════════════════╝

Generated : 2026-07-19 (personas cross-link)
North star : docs/strategy.txt (public — edit manually)
Services   : docs/wiki-Mission_and_Services.txt (public — edit manually)
Personas   : docs/wiki-Personas.txt (public — Diane · Raj · Elena)

AUDIENCE & POSITIONING
══════════════════════

  Primary   : Small operators (5–30 doors), often family-owned portfolios
  Model     : Consulting + integration + stewardship — software is the engine
  Not       : Venture SaaS, AppFolio replacement at scale, black-box platform
  Personas  : Wiki → Personas — use for workflow & product positioning

  Family domain depth: ~500 doors (Arizona) — enterprise PM tooling in daily use.

CURRENT RUNTIME (July 2026 · rolling main)
══════════════════════════════════════════

  Entry point     : scripts/pm-menu.sh  (hub-based Bash menu)
  Database        : MariaDB / pmdb  (versioned migrations)
  QA sandbox      : pmdb_qa via Lab (PM_QA_MODE=1) — never production data
  Authorized run  : bin/run · bin/runsql · manifest/*.tsv
  Shared code     : lib/  (runsql, ledger, date, manifest, colors, tui, reports, qa_*)
  SQL queries     : sql/  (invoicing, ledger, reports, rent_collection, qa/, …)
  Statements PDF  : pandoc + templates/ + PMO letterhead settings
  Telemetry       : runtime_telemetry table (duration via pms_date_epoch_ms)
  Documentation   : docs/  + wiki-*.txt  ([y] System → wiki / refresh)
  Forum / notes   : commentorium → notes table
  Finance contract: docs/workflows-finance.txt
  QA framework    : docs/qa-regression-framework.md

PLATFORMS
═════════

  Production      : Ubuntu (DigitalOcean / similar) — pms-server-install/
  Also supported  : Arch Linux hosts; macOS for local development + QA Lab
  Date arithmetic : lib/date.sh
                      · GNU date on Linux (Arch/Ubuntu)
                      · BSD date on stock macOS (no coreutils required)
                      · Homebrew gdate used when present
  Bash            : scripts aim for Bash 3.2+ (macOS system bash);
                    mapfile polyfill + portable arrow keys in lib/tui.sh
                    (stty on /dev/tty; no key=$(read_key); no fractional read -t).
                    Login shell may be zsh — scripts still run under bash via shebang.
  MariaDB admin   : Lab bootstrap discovers CREATE privilege via
                      PMS_DB_ADMIN_USER / PMS_DB_ADMIN_CNF, OS unix_socket
                      user (Homebrew), root, then ~/.my.cnf

DESIGN PRINCIPLES
═════════════════

  • One script = one responsibility
  • Everything is a file — transparent, inspectable
  • Minimal dependencies for the PRODUCT: Bash + MariaDB client
  • Product design contract: docs/PRODUCT_DESIGN_CONTRACT.md
      — Core office = MariaDB + Bash (never rewrite hubs in Python/Node)
      — Landing / Demo Theater UI / steward pulse may use barebone tools
        (static HTML, optional Python utilities, GoAccess) ONLY if listed in
        manifest/perimeter_tools.tsv
  • Portable across Linux / Unix / macOS (same Lab battles)
  • Schema-first with live documentation
  • Two inventories: manifest/scripts.tsv + sql.tsv (product);
      manifest/perimeter_tools.tsv (storefront & host helpers)

DEPLOYMENT MODEL (hybrid — longer term)
═══════════════════════════════════════

  Phase 1: Managed cloud environment — fast onboarding, backups, support
  Phase 2: Operator-owned export — data sovereignty, on-prem or self-host

  Production layout: docs/pms.file_folder_layout.txt
    /opt/pms/releases/vX.Y/   versioned application
    /etc/pms/db.conf          secured credentials
    /var/lib/pms/             reports, backups, data

WIKI STRUCTURE
══════════════

  Public topics  : Schema, Workflows, Reports, Features, Mission, Personas, …
  Operator-only  : Internal Strategy (PIN required in wiki)

SUCCESS CRITERIA
════════════════
  • 5–150 unit portfolios operated with clear, defensible records
  • Statements reconcile; numbers are explainable
  • Cloud-to-local migration without losing integrity
  • Features ship as small scripts — customer feels ownership of the system