Ten31-Portal/ROADMAP.md

Ten31Portal — ROADMAP

Deferred / parked work, grounded in a read-only survey of the current tree on 2026-07-01 and adjudicated the same day (investigate → debate → judge over each item). 13 items were dropped as not-worth-it and removed; what remains is either scheduled work (DO) with a ready plan, or your decision (ESCALATE / HIGH). Priority key: P2 = nice-to-have, P3 = trivial.

Current state

Working internal fund-admin portal (FastAPI + SQLModel + SQLite backend, React/Vite/Tailwind frontend, StartOS 0.4.0 packaging). Phase-1 (entities, holdings, positions, valuation rounds, sign-off, audit, CSV import, four roles) is built. Phase-2 (external investor / fund-admin accounts, capital accounts, documents) is built but largely uncommitted in the working tree. No test suite. Single git commit to date.

---

HIGH — owner's call (not backlog; surfaced, never auto-judged)

• H1. Session secret: backup coverage + change-me fallbacks. start.sh:5-11 persists a random secret to /data/.session-secret, but backups.ts:4 backs up only the main volume — if /data is a separate volume, a restore regenerates the secret and silently logs everyone out. Separately, main.ts:27 and config.py:7 fall back to a hardcoded change-me string if the env var is unset. Reinforced by D8 below: adjudication confirmed the secret really is regenerated whenever /data is wiped, so the backup-coverage question is live. Needs verification of the volume mapping, then a fix. (security + data continuity)
• H2. Login hardening. auth_router.py:14 has no rate limiting / lockout on failed logins, and auth_router.py:60 allows a 4-character password minimum. External-facing attack surface. (security)

---

DO — adjudicated worth-doing + low-risk (your go-ahead to schedule)

Backend

• B3. Backend test suite (P2). ~3,500-line financial system of record with zero tests. Plan: add pytest/pytest-asyncio/httpx as dev deps in pyproject.toml (leave runtime deps); add backend/tests/ with a conftest.py overriding get_session (database.py:10) to a fresh in-memory SQLite + a TestClient fixture and an authenticated-user fixture; first tests cover auth (login works; anon + cross-user access rejected), one CRUD router round-trip, and the rollup (entity_router.py:36) asserting correct aggregate numbers. Additive; no prod-code change.
• B4. Document upload size limit (P2). Uploads stream to disk with no cap, on the same volume as the DB — a runaway upload can fill it and take the portal down. Plan: add MAX_UPLOAD_SIZE to config.py (env TEN31_MAX_UPLOAD_SIZE, default 50 MB); in storage.save_upload (19-30) check size in the stream loop, unlink the partial and raise 413; optional early Content-Length check; add an over-limit test.
• B7. Fix audit detail type label (P3). models.py:154 types detail as str | None but callers store dicts. Plan: change annotation to dict | list | str | None to match schemas.py; add a one-line comment with examples; note it in record_audit (audit.py:17). Documentation/label only — no migration, no call-site changes.
• B10. FK indexes (P3). ~a dozen linking columns have no indexes; zero indexes anywhere. Plan: one additive Alembic migration adding create_index on the FK columns (users.primary_account_id, holdings.entity_id, positions.holding_id, valuation_rounds., valuations., audit_logs.actor_user_id, entity_access., documents., capital_account_statements.*); mirror with index=True on the model Fields; downgrade drops them. No query-code change.
• B11. cli.py silent delete errors (P3). cli.py:123-126 except Exception: pass discards real disk/permission failures and orphans files. Plan: capture the exception, print a warning to stderr (matching existing style) with the failing storage_path, continue the loop; optionally narrow the catch to OSError. No DB/API change.

Frontend

• F2. AuthContext: network vs auth failure (P2, medium conf). A momentary connection blip wrongly shows a logged-out login screen. Plan: export ApiError from api.ts; add an error/offline flag to AuthState; change the line-18 bootstrap catch to inspect the error — 401/403 = logged out, network/5xx = offline flag; render a "couldn't reach the server, retrying" banner (with retry) vs. the login screen.
• F4. Import page: add a real confirmation (P2). One checkbox + Confirm can permanently erase a fund's holdings, positions, and valuation history with no final "are you sure?". Plan: in Import.tsx, gate the destructive replace (before the commit at ~145-152) behind a confirmation dialog that spells out what's cleared; add per-step progress labels ("Saving members…", "Loading holdings…"). Inputs already persist, so the retry concern is minor.
• F6. AuditLog expandable detail (P2). The "what changed" column is truncated with no way to read the rest — exactly when the log matters (a dispute). Data's already sent. Plan: add an expanded-row state; remove the always-truncate classes / make the row clickable; render a full-width row with pretty-printed JSON in a <pre>; add a title on the collapsed cell.
• F7. Investments empty-state (P3, medium conf). An entity with no holdings shows a row of zeros + empty table that reads as "failed to load." Plan: in Investments.tsx, when groups.length === 0 render an empty-state block ("No investments recorded yet" + one line of guidance) instead of the table. Display-only.
• F8. Centralize role checks (P3). Four pages hand-copy role lists; the shared helpers already exist in api.ts and just aren't used. Plan: add WRITER_ROLES + canEditRound to api.ts; point AuditLog/Import at the existing isAdmin; import the shared list in EntitiesList; use canEditRound in ValuationWorkflow. Keep every list byte-identical; do NOT merge fund_admin (internal) and fund_administrator (external) — they are distinct roles.

Deploy

• D2. Commit the version stub files (P2). index.ts is tracked and imports 20 untracked v_0_2_*.ts files — committing as-is breaks a fresh checkout. Plan: stage the 20 files with the modified index.ts and commit together (they carry real release notes); verify a clean checkout builds. The missing v_0_2_2 is intentional (versions are an unordered set).
• D5. Type-check in build (P2). A tsc --noEmit check script exists but never runs; it passes clean today. Plan: in s9pk.mk (~117) change npm run build to npm run check && npm run build. One line; identical behavior today, catches future type errors.
• D6. TEN31_LOG_LEVEL env var (P3). start.sh:41 hardcodes --log-level info. Plan: add LOG_LEVEL="${TEN31_LOG_LEVEL:-info}" near the other env defaults and use "$LOG_LEVEL" on line 41 — same generate-or-default pattern already in the file. Default stays info.

---

ESCALATE — your decision (touches something that matters)

• B1. Pagination on list endpoints (P2, blast radius HIGH). Every list except audit loads all rows, two with an extra query per row — fine now, will slow and time out as data grows.
  • Judge's lean: worth doing, but split it first — it's an epic.
  • Why it's yours: changes observable API behaviour across 5 investor-facing endpoints; two lists filter for permissions in Python after the query, so a naive page limit could silently return short/wrong lists of capital-account figures. Sequence the mechanical offset/limit pass separately from the two permission-filtered endpoints.
• F5. ValuationWorkflow input validation (P2, blast radius HIGH). The Value box accepts a negative number and it reaches the DB uncorrected.
  • Judge's lean: fix it, but the robust fix is not frontend-only.
  • Why it's yours: ValuationBulkItem.value_cents (schemas.py:165) has no ge=0 and round_router.py:140 writes it directly — proper fix adds a backend constraint + the three frontend guards, crossing onto a money-write path beyond the item's stated scope.
• D7. Force override of default admin creds (P3, blast radius HIGH). A normal install ships the top admin account with a password printed in the public setup guide (admin / Ten31) and nothing forces a change.
  • Judge's lean: worth fixing now — external investor/fund-admin accounts are being onboarded, so "I'm the only user" no longer holds.
  • Why it's yours: changes auth on the most powerful account and rewrites first-boot in ~3 spots + 2 docs; a careless change could lock you (or a live deploy) out. Suggested direction: reuse the session-secret generate-and-persist pattern to mint a random admin password on first boot and print it once; add a StartOS config field; test an upgrade path.
• D8. Uninstall alert wording (P3, blast radius LOW — escalated on a corrected fact). The adjudication caught that the original survey premise was wrong: the session secret is regenerated whenever /data is wiped (start.sh:5-11), so the item is valid, not moot. It sits next to the open H1 backup question. Re-triage together with H1 using the corrected facts rather than as a standalone wording tweak.