# 9. Portfolio organisation (folders, starring) is per-user, not shared

Date: 2026-07-07

## Status

Accepted

## Context

The home-page redesign introduced folders and starring so users can organise
their portfolios. The obvious alternative was **shared, team-level
organisation** — one folder structure per organisation that everyone sees, the
way housing-association staff might expect from a shared drive.

The user base spans three groups with conflicting mental models: Domna
analysts touching many portfolios daily, housing-association asset managers
visiting weekly, and contractors with narrow scoped access. One person's
"SHDF Wave 3" triage grouping is another's noise; a contractor can see only a
subset of any shared structure, which renders shared folders confusing
(half-empty groups) or leaky (folder names disclose portfolios they can't
see).

## Decision

Folders and starring belong to the individual user:

- `user_portfolio_folders` and `user_portfolio_config` (migration 0264) key
  everything on `user_id`. A composite FK `(folder_id, user_id) →
  user_portfolio_folders(id, user_id)` makes cross-user filing impossible at
  the database level.
- `portfolioUsers` remains pure access control; the config layer never
  grants or implies access. Config rows are created lazily and simply stop
  rendering if access is revoked (they resurface on re-invite).
- Folder deletion only unfiles; it is app-mediated (unfile + delete in one
  transaction) because the composite FK is `NO ACTION`.
- The UI states the model ("Folders are personal to you — teammates organise
  their own") and folder URLs (`/home?folder=…`) resolve per-viewer.

## Consequences

- No permission model, naming disputes, or sync semantics for shared
  structures — the feature stayed one schema PR and one page.
- Teams cannot share a curated view. If that demand materialises, shared
  organisation should be **additive** (e.g. org-level folders alongside
  personal ones), not a mutation of this schema — the per-user tables and
  the composite FK do not accommodate multi-owner folders.
- Every user starts from an unorganised list and does their own filing;
  drag-to-file exists to keep that cheap.
- Support/debugging must remember that two users looking at "the same"
  home page see different groupings by design.
