# Boards — design & plan

> Status: **planning only** — deferred while we test the current beta. Not built yet.
> Boards is the **Epic-tier collaborative workspace** feature.

## Concept

A **Board** is a shared workspace for one client or project — the single place that
holds everything about it (the "vault"). It has an **owner**, optional **members**,
and a set of content **sections**. A private board with no members doubles as the
**personal vault**, so one engine covers both needs.

## Tiering

- **Epic** users can **create** boards and **invite** collaborators.
- **Any tier** (Free/Pro) can be a **member** of a board they're invited to — otherwise
  there's no one to collaborate with.
- The `boards` capability flag is already wired in `tiers.ts` / `useAuth` caps.

## Collaboration model

- Members have a **role**: **Owner / Editor / Viewer**.
  - Owner: full control, manage members, delete board.
  - Editor: edit content.
  - Viewer: read-only (e.g. share a status board with a client).
- **Invite by email**, reusing Resend + the existing signup/approval flow:
  - Invitee has an account → added as a member.
  - No account → invite link → sign up → gains access.
- **v1 is "refresh to see changes"** (SQLite WAL handles concurrent access fine at
  this scale). Real-time (WebSockets/SSE) is a later, optional add.

## What a Board holds (sections)

- **Overview / critical info** — pinned essentials (key links, credential *pointers*, account refs).
- **Links** — important URLs (Bitwarden, hosting, repos).
- **Projects** — assigned projects (status, billing, etc.). See below.
- **Tasks** — board-level to-dos.
- **Files** — uploads (logos, briefs, PDFs, contracts) — later phase, via R2.
- **Calendar** — dates, calls, deadlines; reuses the reminder system.
- **Collaborators** — member list + roles.
- **Notes** — freeform rich-text.

## Assigning projects into boards

Projects gain an optional **`board_id`**:
- Unassigned projects stay personal (today's behaviour).
- Assigned projects live inside a board and are visible to that board's members.

This makes Boards the **client layer above Projects** we kept deferring. Care needed
on what "assign" means for ownership/visibility once boards are shared.

## The architectural shift (the hard part)

Den is currently **single-user**: every row is scoped `WHERE user_id = ?`. Collaboration
means board content moves to **`board_id` + a membership table**, and every board query
checks "is this user a member, and with what role?". The heavy work is the **access
model**, not the UI.

### Data model sketch

- `boards` (id, owner_id, name, type, created_at)
- `board_members` (board_id, user_id, role, status[invited/active])
- Board content tables (`board_links`, `board_notes`, `board_events`, `board_files`, …) keyed by `board_id`
- `projects.board_id` (nullable)

## File storage — Cloudflare R2 (decided)

- R2 free tier (~10 GB). S3-compatible; needs an account + API keys as droplet env vars
  (same pattern as Resend/Google).
- Uploads must be **access-gated** (only board members can download — signed URLs or a
  proxied auth'd endpoint), **size/type limited**, and **per-board quota**'d.
- Keeps files off the droplet disk and out of the SQLite backup concern.

## Ideas to make it work well

- **Board templates** — "Client" / "Project" / "Personal vault" presets so a new board isn't blank.
- **Activity feed** — "who changed what" (essential once shared).
- **Comments / @mentions** on items — lightweight collaboration without real-time.
- **Viewer role for clients** — read-only board sharing.
- **Calendar → reminders** — board events fire through the reminder system.
- **Personal vault = a private board** (no members) — same engine.

## Recommended phasing

1. **Phase 1 — Solo Boards (container / vault):** single-owner board; notes + links +
   assign projects + board tasks. Reuses today's single-user scoping (owner-only).
   Delivers the vault + client-grouping immediately and validates the content model.
   Pro-gated for solo use.
2. **Phase 2 — Collaboration (Epic):** membership table, invites, roles, shared access.
   This is where the access-model rework lands.
3. **Phase 3 — Files (R2) + Calendar + (maybe) real-time.**

Each phase ships value and de-risks the next; Phase 1 alone gives the client-vault.

## Open questions to revisit

- Board-level tasks vs rolled-up project tasks — one list or two?
- What happens to an assigned project's billing/time-log visibility for Viewers?
- Invite limits per board (anti-abuse) and per Epic account.
- Backup/retention for R2 files.