Implement adjudicated DO items across backend, frontend, deploy

From the ROADMAP adjudication (12 of 13 DO items; D2 is a commit action).

Backend:
- B3: pytest suite (auth, entity CRUD, rollup) + dev deps + pytest config
- B4: cap document uploads at TEN31_MAX_UPLOAD_SIZE (default 50MB), stream-
  checked with partial-file cleanup, 413 on overflow
- B7: type AuditLog.detail as dict|list|str|None to match the JSON column
- B10: index foreign-key columns (migration a7b8c9d0e1f2 + index=True)
- B11: cli delete-user logs file-removal errors instead of swallowing them

Frontend:
- F2: distinguish "server unreachable" from "logged out"; retry prompt
- F4: confirm before destructive holdings-replace on import; step progress
- F6: expandable audit-log detail with full JSON
- F7: empty-state on the Investments page
- F8: shared role helpers (WRITER_ROLES/canEditRound/isApprover), used by
  EntitiesList, AuditLog, Import, ValuationWorkflow

Deploy:
- D5: run tsc --noEmit before packaging (build script)
- D6: TEN31_LOG_LEVEL env var (defaults to info)

Verified: 8/8 backend tests pass; alembic upgrades to head with 13 FK
indexes; upload limit rejects oversized + cleans up; frontend tsc + vite
build clean; dev server serves and proxies to the API.

backend/alembic/versions/a7b8c9d0e1f2_fk_indexes.py

@@ -0,0 +1,50 @@
+"""add indexes on foreign-key columns
+
+Indexes the FK columns that are commonly filtered/joined and are not already the left-most
+column of an existing unique constraint (those are covered by the constraint's index). Names
+match SQLModel's index=True default (ix_<table>_<column>) so the ORM and DB stay in sync.
+
+Revision ID: a7b8c9d0e1f2
+Revises: f6a7b8c9d0e1
+Create Date: 2026-07-01 09:30:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+
+revision: str = 'a7b8c9d0e1f2'
+down_revision: Union[str, None] = 'f6a7b8c9d0e1'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+# (index_name, table, column)
+_INDEXES = [
+    ('ix_users_primary_account_id', 'users', 'primary_account_id'),
+    ('ix_holdings_entity_id', 'holdings', 'entity_id'),
+    ('ix_positions_holding_id', 'positions', 'holding_id'),
+    ('ix_valuation_rounds_submitted_by', 'valuation_rounds', 'submitted_by'),
+    ('ix_valuation_rounds_approved_by', 'valuation_rounds', 'approved_by'),
+    ('ix_valuations_position_id', 'valuations', 'position_id'),
+    ('ix_audit_log_actor_user_id', 'audit_log', 'actor_user_id'),
+    ('ix_entity_access_entity_id', 'entity_access', 'entity_id'),
+    ('ix_documents_entity_id', 'documents', 'entity_id'),
+    ('ix_documents_investor_user_id', 'documents', 'investor_user_id'),
+    ('ix_documents_uploaded_by', 'documents', 'uploaded_by'),
+    ('ix_capital_account_statements_investor_user_id',
+     'capital_account_statements', 'investor_user_id'),
+    ('ix_capital_account_statements_document_id',
+     'capital_account_statements', 'document_id'),
+]
+
+
+def upgrade() -> None:
+    for name, table, column in _INDEXES:
+        op.create_index(name, table, [column])
+
+
+def downgrade() -> None:
+    for name, table, _column in reversed(_INDEXES):
+        op.drop_index(name, table_name=table)

backend/pyproject.toml

@@ -14,6 +14,13 @@ dependencies = [
     "aiosqlite==0.21.0",
     "starlette-session==0.4.3",
     "openpyxl==3.1.5",
+    "msoffcrypto-tool==6.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.3.4",
+    "httpx==0.28.1",  # required by starlette's TestClient
 ]
 
 [project.scripts]
@@ -23,3 +30,6 @@ ten31portal-cli = "ten31portal.cli:main"
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

backend/ten31portal/audit.py

@@ -16,7 +16,12 @@ def record_audit(
     object_id: int | None = None,
     detail: Any = None,
 ) -> AuditLog:
-    """Write one audit log entry and flush it."""
+    """Write one audit log entry and flush it.
+
+    ``detail`` is a small JSON-serializable payload describing the change (typically a dict of
+    changed fields, sometimes an identifying value on delete, or None). It is persisted to a
+    JSON column on AuditLog.
+    """
     entry = AuditLog(
         actor_user_id=actor_user_id,
         action=action,

backend/ten31portal/cli.py

@@ -1,4 +1,4 @@
-"""CLI commands for Ten31Portal."""
+"""CLI commands for Ten31Portal (also driven by the StartOS service Actions)."""
 
 import argparse
 import sys
@@ -8,7 +8,21 @@ from sqlmodel import Session, select
 from ten31portal.auth import hash_password
 from ten31portal.database import engine
 from ten31portal.db_init import run_migrations
-from ten31portal.models import User, UserRole
+from ten31portal.models import (
+    AuditLog, CapitalAccountStatement, Document, EntityAccess, User, UserRole,
+    ValuationRound,
+)
+
+
+def _find_user(session: Session, username: str | None, email: str | None) -> User | None:
+    """Look a user up by username (preferred) or email."""
+    if username:
+        u = session.exec(select(User).where(User.username == username)).first()
+        if u:
+            return u
+    if email:
+        return session.exec(select(User).where(User.email == email)).first()
+    return None
 
 
 def create_user(args: argparse.Namespace) -> None:
@@ -16,8 +30,10 @@ def create_user(args: argparse.Namespace) -> None:
     run_migrations()
 
     with Session(engine) as session:
-        existing = session.exec(select(User).where(User.email == args.email)).first()
-        if existing:
+        if session.exec(select(User).where(User.username == args.username)).first():
+            print(f"Error: user with username {args.username} already exists.", file=sys.stderr)
+            sys.exit(1)
+        if args.email and session.exec(select(User).where(User.email == args.email)).first():
             print(f"Error: user with email {args.email} already exists.", file=sys.stderr)
             sys.exit(1)
 
@@ -29,13 +45,179 @@ def create_user(args: argparse.Namespace) -> None:
 
         user = User(
             name=args.name,
-            email=args.email,
+            username=args.username,
+            email=args.email or None,
             password_hash=hash_password(args.password),
             role=role,
+            is_service_admin=bool(getattr(args, "service_admin", False)),
         )
         session.add(user)
         session.commit()
-        print(f"Created user: {user.name} ({user.email}) with role {user.role.value}")
+        print(f"Created user: {user.name} ({user.username}) with role {user.role.value}")
+
+
+def reset_password(args: argparse.Namespace) -> None:
+    """Reset a user's password (and re-enable their login)."""
+    run_migrations()
+
+    with Session(engine) as session:
+        user = _find_user(session, args.username, args.email)
+        if user is None:
+            who = args.username or args.email
+            print(f"Error: no user found for '{who}'.", file=sys.stderr)
+            sys.exit(1)
+        user.password_hash = hash_password(args.password)
+        user.login_enabled = True
+        session.add(user)
+        session.commit()
+        print(f"Password reset for {user.name} ({user.username}).")
+
+
+def list_users(args: argparse.Namespace) -> None:
+    """Print all user accounts."""
+    run_migrations()
+
+    with Session(engine) as session:
+        users = session.exec(select(User).order_by(User.role, User.name)).all()  # type: ignore[arg-type]
+        if not users:
+            print("No users.")
+            return
+        print(f"{'USERNAME':<20} {'NAME':<24} {'ROLE':<14} {'STATUS':<10} EMAIL")
+        print("-" * 84)
+        for u in users:
+            status = "active" if u.is_active else "disabled"
+            tag = "  [SERVICE ADMIN]" if u.is_service_admin else ""
+            print(f"{u.username:<20} {u.name:<24} {u.role.value:<14} {status:<10} {u.email or '-'}{tag}")
+        print(f"\n{len(users)} user(s). The Service Admin cannot be deleted.")
+
+
+def delete_user(args: argparse.Namespace) -> None:
+    """Delete a user account and its dependent rows. The Service Admin is protected."""
+    run_migrations()
+
+    from ten31portal import storage
+
+    with Session(engine) as session:
+        user = _find_user(session, args.username, args.email)
+        if user is None:
+            who = args.username or args.email
+            print(f"Error: no user found for '{who}'.", file=sys.stderr)
+            sys.exit(1)
+        if user.is_service_admin:
+            print(f"Error: '{user.username}' is the Service Admin and cannot be deleted.", file=sys.stderr)
+            sys.exit(1)
+
+        uid = user.id
+
+        # Entity-access grants and capital-account statements are this user's own data.
+        for acc in session.exec(select(EntityAccess).where(EntityAccess.user_id == uid)).all():
+            session.delete(acc)
+        for stmt in session.exec(
+            select(CapitalAccountStatement).where(CapitalAccountStatement.investor_user_id == uid)
+        ).all():
+            session.delete(stmt)
+
+        # Documents addressed privately to this investor are removed (file + row); documents
+        # they uploaded stay, with the uploader cleared.
+        for doc in session.exec(select(Document).where(Document.investor_user_id == uid)).all():
+            try:
+                storage.delete_file(doc.storage_path)
+            except OSError as exc:
+                # Don't abort the whole deletion, but surface it — a swallowed disk/permission
+                # error would silently orphan the file on the data volume.
+                print(f"Warning: could not delete file {doc.storage_path}: {exc}", file=sys.stderr)
+            session.delete(doc)
+        for doc in session.exec(select(Document).where(Document.uploaded_by == uid)).all():
+            doc.uploaded_by = None
+            session.add(doc)
+
+        # Preserve history/rounds by clearing the references to this user.
+        for rnd in session.exec(
+            select(ValuationRound).where(
+                (ValuationRound.submitted_by == uid) | (ValuationRound.approved_by == uid)
+            )
+        ).all():
+            if rnd.submitted_by == uid:
+                rnd.submitted_by = None
+            if rnd.approved_by == uid:
+                rnd.approved_by = None
+            session.add(rnd)
+        for log in session.exec(select(AuditLog).where(AuditLog.actor_user_id == uid)).all():
+            log.actor_user_id = None
+            session.add(log)
+
+        # Detach any linked sub-accounts so they log in on their own again.
+        for sub in session.exec(select(User).where(User.primary_account_id == uid)).all():
+            sub.primary_account_id = None
+            session.add(sub)
+
+        name, username = user.name, user.username
+        session.delete(user)
+        session.commit()
+        print(f"Deleted user {name} ({username}).")
+
+
+def dedupe_holdings(args: argparse.Namespace) -> None:
+    """Remove duplicate holdings/positions left by old double-imports (fixes inflated Invested)."""
+    run_migrations()
+    from ten31portal.models import Entity
+    from ten31portal.routers.import_router import dedupe_entity
+
+    with Session(engine) as session:
+        if args.entity_id:
+            entities = [e for e in [session.get(Entity, args.entity_id)] if e]
+        else:
+            entities = session.exec(select(Entity).order_by(Entity.name)).all()  # type: ignore[arg-type]
+        total_h = total_p = 0
+        for ent in entities:
+            res = dedupe_entity(ent.id, session)
+            if res["removed_holdings"] or res["removed_positions"]:
+                print(f"{ent.name}: removed {res['removed_holdings']} holding(s), "
+                      f"{res['removed_positions']} position(s)")
+            total_h += res["removed_holdings"]
+            total_p += res["removed_positions"]
+        session.commit()
+        if total_h or total_p:
+            print(f"\nDone. Removed {total_h} duplicate holding(s) and {total_p} position(s).")
+        else:
+            print("No duplicates found — nothing to clean up.")
+
+
+def reset_holdings(args: argparse.Namespace) -> None:
+    """Clear a fund's holdings/positions/rounds so it can be re-imported from scratch."""
+    run_migrations()
+    from ten31portal.models import Entity
+    from ten31portal.routers.import_router import reset_entity_holdings
+
+    with Session(engine) as session:
+        entity = None
+        if args.entity_id:
+            entity = session.get(Entity, args.entity_id)
+        elif args.name:
+            entity = session.exec(select(Entity).where(Entity.name == args.name)).first()
+        if entity is None:
+            print(f"Error: no fund found for '{args.name or args.entity_id}'. "
+                  f"Check the exact name with list-funds.", file=sys.stderr)
+            sys.exit(1)
+        res = reset_entity_holdings(entity.id, session)
+        session.commit()
+        print(f"Cleared {entity.name}: removed {res['holdings']} holding(s), "
+              f"{res['positions']} position(s), {res['rounds']} round(s). "
+              f"Re-import the fund's NAV to repopulate it.")
+
+
+def list_funds(args: argparse.Namespace) -> None:
+    """Print every entity's id and name (so the exact name is known for reset-holdings)."""
+    run_migrations()
+    from ten31portal.models import Entity
+
+    with Session(engine) as session:
+        entities = session.exec(select(Entity).order_by(Entity.name)).all()  # type: ignore[arg-type]
+        if not entities:
+            print("No funds yet.")
+            return
+        for e in entities:
+            print(f"[{e.id}] {e.name} ({e.type.value})")
 
 
 def main() -> None:
@@ -44,13 +226,49 @@ def main() -> None:
 
     create = sub.add_parser("create-user", help="Provision a new user")
     create.add_argument("--name", required=True)
-    create.add_argument("--email", required=True)
+    create.add_argument("--username", required=True)
+    create.add_argument("--email", required=False, default=None)
     create.add_argument("--role", required=True, choices=[r.value for r in UserRole])
     create.add_argument("--password", required=True)
+    create.add_argument("--service-admin", action="store_true",
+                        help="Mark as the protected built-in Service Admin")
+
+    reset = sub.add_parser("reset-password", help="Reset a user's password")
+    reset.add_argument("--username", required=False, default=None)
+    reset.add_argument("--email", required=False, default=None)
+    reset.add_argument("--password", required=True)
+
+    sub.add_parser("list-users", help="List all user accounts")
+
+    delete = sub.add_parser("delete-user", help="Delete a user (not the Service Admin)")
+    delete.add_argument("--username", required=False, default=None)
+    delete.add_argument("--email", required=False, default=None)
+
+    dedupe = sub.add_parser("dedupe-holdings", help="Remove duplicate holdings/positions")
+    dedupe.add_argument("--entity-id", type=int, required=False, default=None,
+                        help="Limit to one entity; omit to clean all")
+
+    sub.add_parser("list-funds", help="List entities (funds/SPVs) with their ids")
+
+    reset = sub.add_parser("reset-holdings", help="Clear a fund's holdings to re-import fresh")
+    reset.add_argument("--name", required=False, default=None, help="Exact fund name")
+    reset.add_argument("--entity-id", type=int, required=False, default=None)
 
     args = parser.parse_args()
     if args.command == "create-user":
         create_user(args)
+    elif args.command == "reset-password":
+        reset_password(args)
+    elif args.command == "list-users":
+        list_users(args)
+    elif args.command == "delete-user":
+        delete_user(args)
+    elif args.command == "dedupe-holdings":
+        dedupe_holdings(args)
+    elif args.command == "list-funds":
+        list_funds(args)
+    elif args.command == "reset-holdings":
+        reset_holdings(args)
     else:
         parser.print_help()
 

backend/ten31portal/config.py

@@ -5,3 +5,7 @@ import os
 
 DB_PATH: str = os.getenv("TEN31_DB_PATH", "/data/ten31portal/portal.db")
 SESSION_SECRET: str = os.getenv("TEN31_SESSION_SECRET", "change-me-in-production")
+DOCS_DIR: str = os.getenv("TEN31_DOCS_DIR", "/data/ten31portal/documents")
+# Cap on a single uploaded document. The docs dir shares the data volume with the DB, so an
+# unbounded upload could fill the disk and take the portal down. Default 50 MB.
+MAX_UPLOAD_SIZE: int = int(os.getenv("TEN31_MAX_UPLOAD_SIZE", str(50 * 1024 * 1024)))

backend/ten31portal/models.py

@@ -11,10 +11,27 @@ from sqlmodel import Field, SQLModel, Column, String, JSON, UniqueConstraint
 # --- Enums ---
 
 class UserRole(str, enum.Enum):
-    approver = "approver"
+    # Internal staff
+    approver = "approver"        # "Managing Partner" — full access incl. valuation sign-off
+    operations = "operations"    # full access except final sign-off
     cfo = "cfo"
     fund_admin = "fund_admin"
     viewer = "viewer"
+    # External accounts (entity-scoped via EntityAccess)
+    investor = "investor"
+    fund_administrator = "fund_administrator"
+
+
+# External roles see only the entities granted to them.
+EXTERNAL_ROLES = (UserRole.investor, UserRole.fund_administrator)
+
+
+class DocumentCategory(str, enum.Enum):
+    capital_account = "capital_account"
+    k1 = "k1"
+    statement = "statement"
+    tax = "tax"
+    other = "other"
 
 
 class EntityType(str, enum.Enum):
@@ -43,10 +60,21 @@ class User(SQLModel, table=True):
 
     id: int | None = Field(default=None, primary_key=True)
     name: str
-    email: str = Field(sa_column=Column(String, unique=True, nullable=False))
+    username: str = Field(sa_column=Column(String, unique=True, nullable=False))
+    email: str | None = Field(default=None, sa_column=Column(String, unique=True, nullable=True))
     password_hash: str
     role: UserRole
     is_active: bool = Field(default=True)
+    # The built-in Service Admin (bootstrap account). Can be reset but never deleted.
+    is_service_admin: bool = Field(default=False)
+    # False for members imported without a password; set True when an admin sets one.
+    login_enabled: bool = Field(default=True)
+    # When an investor invests under several legal names (one per Partner/vehicle), each name
+    # is its own account. Linking the secondary accounts to one "primary" lets that person sign
+    # in once and see every name's investments. Null = this account logs in on its own.
+    primary_account_id: int | None = Field(default=None, foreign_key="users.id", index=True)
+    # Fund-administrator investor ID (from the eNAV ALLOC SI tab) for idempotent re-import.
+    external_investor_id: str | None = Field(default=None, sa_column=Column(String, nullable=True))
     created_at: datetime = Field(default_factory=datetime.utcnow)
 
 
@@ -66,7 +94,7 @@ class Holding(SQLModel, table=True):
     __tablename__ = "holdings"
 
     id: int | None = Field(default=None, primary_key=True)
-    entity_id: int = Field(foreign_key="entities.id")
+    entity_id: int = Field(foreign_key="entities.id", index=True)
     company_name: str
     created_at: datetime = Field(default_factory=datetime.utcnow)
 
@@ -75,7 +103,7 @@ class Position(SQLModel, table=True):
     __tablename__ = "positions"
 
     id: int | None = Field(default=None, primary_key=True)
-    holding_id: int = Field(foreign_key="holdings.id")
+    holding_id: int = Field(foreign_key="holdings.id", index=True)
     security_name: str
     investment_date: date
     shares: str | None = None  # Decimal stored as string
@@ -93,9 +121,9 @@ class ValuationRound(SQLModel, table=True):
     entity_id: int = Field(foreign_key="entities.id")
     quarter_end: date
     status: RoundStatus = Field(default=RoundStatus.draft)
-    submitted_by: int | None = Field(default=None, foreign_key="users.id")
+    submitted_by: int | None = Field(default=None, foreign_key="users.id", index=True)
     submitted_at: datetime | None = None
-    approved_by: int | None = Field(default=None, foreign_key="users.id")
+    approved_by: int | None = Field(default=None, foreign_key="users.id", index=True)
     approved_at: datetime | None = None
     return_note: str | None = None
     is_seed: bool = Field(default=False)
@@ -110,7 +138,7 @@ class Valuation(SQLModel, table=True):
 
     id: int | None = Field(default=None, primary_key=True)
     round_id: int = Field(foreign_key="valuation_rounds.id")
-    position_id: int = Field(foreign_key="positions.id")
+    position_id: int = Field(foreign_key="positions.id", index=True)
     value_cents: int
     created_at: datetime = Field(default_factory=datetime.utcnow)
 
@@ -119,9 +147,63 @@ class AuditLog(SQLModel, table=True):
     __tablename__ = "audit_log"
 
     id: int | None = Field(default=None, primary_key=True)
-    actor_user_id: int | None = Field(default=None, foreign_key="users.id")
+    actor_user_id: int | None = Field(default=None, foreign_key="users.id", index=True)
     action: str
     object_type: str
     object_id: int | None = None
-    detail: str | None = Field(default=None, sa_column=Column(JSON, nullable=True))
+    # An action-specific JSON payload describing the change (stored in a JSON column). Most
+    # callers pass a dict of changed fields (e.g. an entity update); some pass an identifying
+    # field on delete, and some pass None. Matches AuditLogResponse.detail in schemas.py.
+    detail: dict | list | str | None = Field(default=None, sa_column=Column(JSON, nullable=True))
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class EntityAccess(SQLModel, table=True):
+    """Which entities an external account may view."""
+    __tablename__ = "entity_access"
+    __table_args__ = (
+        UniqueConstraint("user_id", "entity_id", name="uq_access_user_entity"),
+    )
+
+    id: int | None = Field(default=None, primary_key=True)
+    user_id: int = Field(foreign_key="users.id")
+    entity_id: int = Field(foreign_key="entities.id", index=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class Document(SQLModel, table=True):
+    """An uploaded file. Shared to a fund (investor_user_id null) or private to one investor."""
+    __tablename__ = "documents"
+
+    id: int | None = Field(default=None, primary_key=True)
+    entity_id: int = Field(foreign_key="entities.id", index=True)
+    investor_user_id: int | None = Field(default=None, foreign_key="users.id", index=True)
+    category: DocumentCategory = Field(default=DocumentCategory.other)
+    title: str
+    original_filename: str
+    content_type: str
+    size_bytes: int
+    storage_path: str  # opaque filename on the data volume, relative to DOCS_DIR
+    uploaded_by: int | None = Field(default=None, foreign_key="users.id", index=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class CapitalAccountStatement(SQLModel, table=True):
+    """An investor's capital-account figures for one fund as of a date."""
+    __tablename__ = "capital_account_statements"
+    __table_args__ = (
+        UniqueConstraint("entity_id", "investor_user_id", "as_of_date",
+                         name="uq_capacct_entity_investor_date"),
+    )
+
+    id: int | None = Field(default=None, primary_key=True)
+    entity_id: int = Field(foreign_key="entities.id")
+    investor_user_id: int = Field(foreign_key="users.id", index=True)
+    as_of_date: date
+    commitment_cents: int = 0          # initial capital commitment
+    beginning_balance_cents: int = 0
+    contributions_cents: int = 0       # paid-in capital
+    distributions_cents: int = 0       # capital returned (for DPI)
+    ending_balance_cents: int = 0      # current capital value
+    document_id: int | None = Field(default=None, foreign_key="documents.id", index=True)
     created_at: datetime = Field(default_factory=datetime.utcnow)

backend/ten31portal/routers/document_router.py

@@ -0,0 +1,156 @@
+"""Document upload, listing, download, and deletion with per-account access control."""
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+from sqlmodel import Session, select
+
+from ten31portal.audit import record_audit
+from ten31portal.auth import (
+    accessible_entity_ids, can_access_entity, get_current_user,
+    household_user_ids, require_internal_admin,
+)
+from ten31portal.database import get_session
+from ten31portal.models import (
+    Document, DocumentCategory, Entity, User, UserRole,
+)
+from ten31portal.schemas import DocumentResponse
+from ten31portal import storage
+
+router = APIRouter(prefix="/api/documents", tags=["documents"])
+
+
+def _can_upload(user: User, entity_id: int, session: Session) -> bool:
+    """Internal admins upload anywhere; external fund admins upload for their entities."""
+    if user.role in (UserRole.approver, UserRole.cfo, UserRole.operations):
+        return True
+    if user.role == UserRole.fund_administrator:
+        return can_access_entity(user, entity_id, session)
+    return False
+
+
+def _can_view(user: User, doc: Document, session: Session) -> bool:
+    allowed = accessible_entity_ids(user, session)
+    if allowed is None:  # internal staff
+        return True
+    if doc.entity_id not in allowed:
+        return False
+    # Investors only see shared docs or those addressed to any of their linked names;
+    # fund admins see all docs for the entity.
+    if user.role == UserRole.investor:
+        return (
+            doc.investor_user_id is None
+            or doc.investor_user_id in household_user_ids(user, session)
+        )
+    return True
+
+
+@router.get("")
+def list_documents(
+    entity_id: int | None = None,
+    investor_user_id: int | None = None,
+    user: User = Depends(get_current_user),
+    session: Session = Depends(get_session),
+) -> list[DocumentResponse]:
+    query = select(Document)
+    if entity_id is not None:
+        query = query.where(Document.entity_id == entity_id)
+    if investor_user_id is not None:
+        query = query.where(Document.investor_user_id == investor_user_id)
+    rows = session.exec(query.order_by(Document.created_at.desc())).all()  # type: ignore[union-attr]
+    visible = [d for d in rows if _can_view(user, d, session)]
+    return [DocumentResponse.model_validate(d, from_attributes=True) for d in visible]
+
+
+@router.post("", status_code=201)
+def upload_document(
+    entity_id: int = Form(...),
+    category: DocumentCategory = Form(DocumentCategory.other),
+    title: str | None = Form(None),
+    investor_user_id: int | None = Form(None),
+    file: UploadFile = File(...),
+    user: User = Depends(get_current_user),
+    session: Session = Depends(get_session),
+) -> DocumentResponse:
+    entity = session.get(Entity, entity_id)
+    if entity is None:
+        raise HTTPException(status_code=404, detail="Entity not found")
+    if not _can_upload(user, entity_id, session):
+        raise HTTPException(status_code=403, detail="Insufficient permissions")
+
+    # If targeting a specific investor, they must have access to this entity.
+    if investor_user_id is not None:
+        target = session.get(User, investor_user_id)
+        if target is None:
+            raise HTTPException(status_code=404, detail="Investor not found")
+        if not can_access_entity(target, entity_id, session):
+            raise HTTPException(
+                status_code=400,
+                detail="That investor does not have access to this entity.",
+            )
+
+    try:
+        storage_name, size = storage.save_upload(file)
+    except storage.UploadTooLarge as exc:
+        raise HTTPException(status_code=413, detail=str(exc))
+    doc = Document(
+        entity_id=entity_id,
+        investor_user_id=investor_user_id,
+        category=category,
+        title=title or (file.filename or "Untitled"),
+        original_filename=file.filename or storage_name,
+        content_type=file.content_type or "application/octet-stream",
+        size_bytes=size,
+        storage_path=storage_name,
+        uploaded_by=user.id,
+    )
+    session.add(doc)
+    session.flush()
+    record_audit(session, user.id, "upload", "document", doc.id, {
+        "entity_id": entity_id,
+        "investor_user_id": investor_user_id,
+        "category": category.value,
+        "filename": doc.original_filename,
+    })
+    session.commit()
+    session.refresh(doc)
+    return DocumentResponse.model_validate(doc, from_attributes=True)
+
+
+@router.get("/{document_id}/download")
+def download_document(
+    document_id: int,
+    user: User = Depends(get_current_user),
+    session: Session = Depends(get_session),
+) -> FileResponse:
+    doc = session.get(Document, document_id)
+    if doc is None or not _can_view(user, doc, session):
+        raise HTTPException(status_code=404, detail="Document not found")
+    try:
+        path = storage.full_path(doc.storage_path)
+    except ValueError:
+        raise HTTPException(status_code=404, detail="Document not found")
+    if not path.is_file():
+        raise HTTPException(status_code=404, detail="File missing on disk")
+    return FileResponse(
+        path,
+        media_type=doc.content_type,
+        filename=doc.original_filename,
+    )
+
+
+@router.delete("/{document_id}")
+def delete_document(
+    document_id: int,
+    admin: User = Depends(require_internal_admin),
+    session: Session = Depends(get_session),
+) -> dict[str, str]:
+    doc = session.get(Document, document_id)
+    if doc is None:
+        raise HTTPException(status_code=404, detail="Document not found")
+    storage.delete_file(doc.storage_path)
+    record_audit(session, admin.id, "delete", "document", document_id, {
+        "filename": doc.original_filename,
+    })
+    session.delete(doc)
+    session.commit()
+    return {"status": "deleted"}

backend/ten31portal/storage.py

@@ -0,0 +1,62 @@
+"""File storage on the data volume for uploaded documents."""
+
+import os
+import shutil
+from pathlib import Path
+from uuid import uuid4
+
+from fastapi import UploadFile
+
+from ten31portal.config import DOCS_DIR, MAX_UPLOAD_SIZE
+
+
+class UploadTooLarge(Exception):
+    """Raised when an upload exceeds MAX_UPLOAD_SIZE. The partial file is removed first."""
+
+
+def ensure_docs_dir() -> Path:
+    path = Path(DOCS_DIR)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def save_upload(file: UploadFile) -> tuple[str, int]:
+    """Stream an upload to disk under an opaque name. Returns (storage_path, size_bytes).
+
+    Enforces MAX_UPLOAD_SIZE as it streams so a runaway upload can't fill the data volume;
+    the partial file is deleted before UploadTooLarge propagates.
+    """
+    docs = ensure_docs_dir()
+    suffix = Path(file.filename or "").suffix
+    storage_name = f"{uuid4().hex}{suffix}"
+    dest = docs / storage_name
+    size = 0
+    try:
+        with dest.open("wb") as out:
+            while chunk := file.file.read(1024 * 1024):
+                size += len(chunk)
+                if size > MAX_UPLOAD_SIZE:
+                    raise UploadTooLarge(
+                        f"Upload exceeds the {MAX_UPLOAD_SIZE}-byte limit."
+                    )
+                out.write(chunk)
+    except UploadTooLarge:
+        dest.unlink(missing_ok=True)
+        raise
+    return storage_name, size
+
+
+def full_path(storage_path: str) -> Path:
+    """Resolve a stored file, guarding against path traversal."""
+    docs = ensure_docs_dir().resolve()
+    candidate = (docs / storage_path).resolve()
+    if not str(candidate).startswith(str(docs) + os.sep):
+        raise ValueError("Invalid storage path")
+    return candidate
+
+
+def delete_file(storage_path: str) -> None:
+    try:
+        full_path(storage_path).unlink(missing_ok=True)
+    except ValueError:
+        pass

backend/tests/conftest.py

@@ -0,0 +1,77 @@
+"""Shared pytest fixtures: an in-memory DB and a FastAPI TestClient.
+
+The client is created WITHOUT the context-manager form on purpose, so the app lifespan (which
+runs real Alembic migrations against the configured DB_PATH) never fires. Tables come from
+SQLModel.metadata.create_all against a throwaway in-memory database instead.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy.pool import StaticPool
+from sqlmodel import Session, SQLModel, create_engine
+
+import ten31portal.models  # noqa: F401 — importing registers every table on SQLModel.metadata
+from ten31portal.auth import hash_password
+from ten31portal.database import get_session
+from ten31portal.main import app
+from ten31portal.models import User, UserRole
+
+
+@pytest.fixture
+def engine():
+    eng = create_engine(
+        "sqlite://",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,  # one shared in-memory connection across sessions
+    )
+    SQLModel.metadata.create_all(eng)
+    yield eng
+    SQLModel.metadata.drop_all(eng)
+
+
+@pytest.fixture
+def session(engine):
+    with Session(engine) as s:
+        yield s
+
+
+@pytest.fixture
+def client(engine):
+    def override_get_session():
+        with Session(engine) as s:
+            yield s
+
+    app.dependency_overrides[get_session] = override_get_session
+    yield TestClient(app)
+    app.dependency_overrides.clear()
+
+
+def make_user(session, *, username="admin", password="password123",
+              role=UserRole.approver, name="Test User", email=None, **kwargs):
+    user = User(
+        name=name,
+        username=username,
+        email=email,
+        password_hash=hash_password(password),
+        role=role,
+        **kwargs,
+    )
+    session.add(user)
+    session.commit()
+    session.refresh(user)
+    return user
+
+
+@pytest.fixture
+def approver(session):
+    return make_user(session, username="approver", role=UserRole.approver)
+
+
+@pytest.fixture
+def auth_client(client, approver):
+    """A TestClient already logged in as an approver (a writer)."""
+    resp = client.post(
+        "/api/auth/login", json={"login": "approver", "password": "password123"}
+    )
+    assert resp.status_code == 200, resp.text
+    return client

backend/tests/test_auth.py

@@ -0,0 +1,40 @@
+"""Auth: login works, and protected/writer endpoints reject the wrong caller."""
+
+from tests.conftest import make_user
+from ten31portal.models import UserRole
+
+
+def test_login_success(client, approver):
+    resp = client.post(
+        "/api/auth/login", json={"login": "approver", "password": "password123"}
+    )
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["username"] == "approver"
+
+
+def test_login_wrong_password(client, approver):
+    resp = client.post(
+        "/api/auth/login", json={"login": "approver", "password": "nope"}
+    )
+    assert resp.status_code == 401
+
+
+def test_me_requires_authentication(client):
+    assert client.get("/api/auth/me").status_code == 401
+
+
+def test_me_returns_current_user(auth_client):
+    resp = auth_client.get("/api/auth/me")
+    assert resp.status_code == 200
+    assert resp.json()["role"] == "approver"
+
+
+def test_writer_endpoint_rejects_viewer(client, session):
+    """A viewer is authenticated but not a writer — create-entity must 403, not 401."""
+    make_user(session, username="viewer", role=UserRole.viewer)
+    login = client.post(
+        "/api/auth/login", json={"login": "viewer", "password": "password123"}
+    )
+    assert login.status_code == 200
+    resp = client.post("/api/entities", json={"name": "X", "type": "fund"})
+    assert resp.status_code == 403

backend/tests/test_entities.py

@@ -0,0 +1,32 @@
+"""Entity CRUD round-trips through the API as a writer."""
+
+
+def test_entity_crud_roundtrip(auth_client):
+    # Create
+    created = auth_client.post(
+        "/api/entities",
+        json={"name": "Ten31 Fund I", "type": "fund", "vintage_year": 2025},
+    )
+    assert created.status_code == 201, created.text
+    entity_id = created.json()["id"]
+
+    # Read (single)
+    got = auth_client.get(f"/api/entities/{entity_id}")
+    assert got.status_code == 200
+    assert got.json()["name"] == "Ten31 Fund I"
+
+    # List
+    listed = auth_client.get("/api/entities")
+    assert listed.status_code == 200
+    assert any(e["id"] == entity_id for e in listed.json())
+
+    # Update
+    patched = auth_client.patch(
+        f"/api/entities/{entity_id}", json={"name": "Ten31 Fund I, LP"}
+    )
+    assert patched.status_code == 200
+    assert patched.json()["name"] == "Ten31 Fund I, LP"
+
+
+def test_get_missing_entity_404(auth_client):
+    assert auth_client.get("/api/entities/99999").status_code == 404

backend/tests/test_rollup.py

@@ -0,0 +1,48 @@
+"""The entity rollup aggregates invested cost and the latest signed valuation correctly."""
+
+from datetime import date
+
+from ten31portal.models import (
+    Entity, EntityType, Holding, Position, RoundStatus, Valuation, ValuationRound,
+)
+
+
+def test_rollup_sums_cost_and_latest_signed_value(auth_client, session):
+    entity = Entity(name="Rollup Fund", type=EntityType.fund)
+    session.add(entity)
+    session.commit()
+    session.refresh(entity)
+
+    holding = Holding(entity_id=entity.id, company_name="Acme")
+    session.add(holding)
+    session.commit()
+    session.refresh(holding)
+
+    position = Position(
+        holding_id=holding.id,
+        security_name="Acme Series A",
+        investment_date=date(2025, 1, 15),
+        cost_cents=100_000,
+    )
+    session.add(position)
+    session.commit()
+    session.refresh(position)
+
+    rnd = ValuationRound(
+        entity_id=entity.id,
+        quarter_end=date(2026, 3, 31),
+        status=RoundStatus.approved,
+    )
+    session.add(rnd)
+    session.commit()
+    session.refresh(rnd)
+
+    session.add(Valuation(round_id=rnd.id, position_id=position.id, value_cents=150_000))
+    session.commit()
+
+    resp = auth_client.get("/api/entities/rollup")
+    assert resp.status_code == 200, resp.text
+    row = next(r for r in resp.json() if r["id"] == entity.id)
+    assert row["invested_cents"] == 100_000
+    assert row["last_signed_value_cents"] == 150_000
+    assert row["committed_cents"] == 0  # no capital-account statements added