dealspace/MVP.md

# Dealspace MVP Scope

**Version:** 1.0 — 2026-02-28  
**Status:** Planning. Defines what ships in v1.0 vs what comes later.

---

## Executive Summary

v1.0 ships a complete, end-to-end M&A deal workflow. An IB advisor can run a real deal from first request to buyer data room access. No AI matching, no external integrations, no mobile — just the core flow that makes Dealspace useful on day one.

**Target:** 6 sprints. Demoable to Misha after Sprint 2. Shippable after Sprint 6.

---

## 1. v1.0 Scope (Must Ship)

### What the IB Analyst Needs on Day 1

1. **Create a project** — name it, configure workstreams (Finance, Legal, IT, HR, Operations)
2. **Invite participants** — seller admin, seller workers, assign to workstreams
3. **Issue request list** — create requests, set priority/due dates, assign to seller users
4. **Track progress** — see what's answered, what's pending, who's blocking
5. **Vet answers** — approve or reject with comments
6. **Publish to data room** — approved answers become visible to buyers
7. **Onboard buyers** — invite buyer teams, they see published content

That's the minimum viable deal. Everything below supports this flow.

### Core Features — v1.0

| Feature | Details |
|---------|---------|
| **Entry Model** | Project → Workstream → Request List → Request/Answer. Full tree per SPEC.md. |
| **RBAC** | All 7 roles: `ib_admin`, `ib_member`, `seller_admin`, `seller_member`, `buyer_admin`, `buyer_member`, `observer`. Workstream-scoped permissions. |
| **Task Inbox** | The worker view. Seller members see "What do I need to do?" — not the full deal room. |
| **Request Routing Chain** | Forward to CFO → forward to accountant → done → returns up the chain. `assignee_id`, `return_to_id`, `origin_id` fields. |
| **File Upload** | Attach files to answers. Stored compressed + encrypted. |
| **PDF Watermarking** | Dynamic watermark at serve time: `{user_name} · {org_name} · {datetime} · CONFIDENTIAL`. PDF only in v1.0. |
| **Answer Vetting** | IB reviews submitted answers. Approve → published. Reject → back to seller with comment. |
| **Data Room** | Buyer view: see published answers only. Pre-dataroom content invisible (DB-level, not UI filter). |
| **Invite Flow** | Email-based invites. Accept → set password → you're in. |
| **Auth** | Email + password. TOTP (2FA) required for admin roles. Session tokens with refresh. |
| **Audit Log** | Every access grant, file download, status change, login. Never disabled. |
| **Marketing Website** | muskepo.com — embedded in binary. Simple landing, signup CTA. |

### What's NOT in v1.0

| Feature | Why Not Now |
|---------|-------------|
| **AI Matching** | Fireworks embeddings + cosine similarity is straightforward, but human confirmation UX adds scope. v1.1. |
| **Email/Slack/Teams Integration** | OAuth flows, DKIM verification, thread mapping — complex auth + security surface. v1.1+. |
| **Video Watermarking** | ffmpeg transcoding at serve time is CPU-intensive, needs worker queue. v1.1. |
| **DOCX/XLSX Watermarking** | XML manipulation is fiddly; PDF covers 80% of use cases. v1.1. |
| **MCP Server** | Depends on stable schema + real usage patterns to know what tools matter. v2.0. |
| **SSO/SAML** | Enterprise feature. Password + TOTP is fine for launch. v2.0. |
| **Key Rotation** | Ship with a good initial key derivation setup. Document rotation procedure for v1.1. |
| **Mobile App** | Never, or much later. Responsive web handles phones. |
| **Public API** | Let the product stabilize first. v2.0. |
| **Webhooks** | Same — need to know what events matter. v2.0. |
| **Custom Themes** | Built-in Light/Dark/High-contrast is enough. Per-project branding is v2.0. |
| **White-labeling** | Per-firm branding is enterprise upsell. v2.0. |

---

## 2. v1.1 Scope

Ship within 4-6 weeks after v1.0 launch.

| Feature | Details |
|---------|---------|
| **AI Matching** | Embed request text (Fireworks nomic-embed-text-v1.5). Score ≥ 0.72 → suggest match. Human clicks "Confirm" or "Not a match". |
| **DOCX Watermarking** | Inject watermark into document.xml header/footer. |
| **XLSX Watermarking** | Sheet protection + watermark row at top. |
| **Answer Broadcast** | One answer satisfies N requests → all requesters notified. Uses `answer_links` table. |
| **Delegation** | Out-of-office routing. "Forward my tasks to X until date Y." |
| **Email Channel (Inbound)** | Accept replies via email. DKIM verification required. Map to entry via `channel_threads`. |
| **Key Rotation Procedure** | Documented + tested process for rotating project encryption keys. |

---

## 3. v2.0 Scope

6+ months out. After real customers are using the platform.

| Feature | Details |
|---------|---------|
| **MCP Server** | Expose deal context to AI tools. Read: list requests, query answers. Write: suggest routing (human confirmation). |
| **SSO/SAML** | Okta, Azure AD, etc. Enterprise requirement for larger banks. |
| **Slack/Teams Integration** | Participate in deals without logging in. Thread-mapped via `channel_threads`. |
| **Custom Themes** | Per-project brand colors + logo. CSS vars make this trivial once prioritized. |
| **Public API** | RESTful API with API keys. Document with OpenAPI. |
| **Webhooks** | Push notifications: answer published, request overdue, buyer accessed. |
| **Per-Firm White-labeling** | "Powered by [hidden]" — full brand takeover. Enterprise pricing. |
| **Video Watermarking** | ffmpeg overlay pipeline. Needs worker queue for CPU-bound transcoding. |

---

## 4. Build Order (v1.0 Sprints)

### Sprint 1: Foundation (Week 1-2)
**Goal:** Skeleton that boots, connects to DB, returns health check.

- [ ] Project structure per SPEC.md 11.1
- [ ] SQLite + migrations (8 tables from SPEC.md 16.6)
- [ ] `lib/crypto.go` — Pack/Unpack, AES-256-GCM, key derivation
- [ ] `lib/types.go` — Entry, User, Access structs
- [ ] `lib/dbcore.go` — EntryRead, EntryWrite, EntryDelete (the three choke points)
- [ ] `lib/rbac.go` — CheckAccess, role definitions
- [ ] `lib/store.go` — ObjectStore interface + filesystem impl
- [ ] `api/middleware.go` — logging, CORS, panic recovery
- [ ] `api/routes.go` — `/health` returns 200
- [ ] Basic config loading from `.env`
- [ ] `make build`, `make run`, `make test`

**Demo:** `curl /health` returns `{"status":"ok"}`.

### Sprint 2: Core Flow (Week 3-4)
**Goal:** Create project, workstreams, requests. Invite users. This is the first Misha demo.

- [ ] User registration + login (email/password)
- [ ] Session management (JWT or opaque tokens)
- [ ] `POST /api/projects` — create project
- [ ] `POST /api/workstreams` — create workstream under project
- [ ] `POST /api/requests` — create request under workstream
- [ ] `GET /api/projects/:id` — project with workstreams tree
- [ ] `GET /api/workstreams/:id/requests` — requests in workstream
- [ ] Invite flow — generate invite link, accept, set password
- [ ] Access grants — assign role + workstream to user
- [ ] Basic portal UI: login, project list, workstream tabs, request list

**Demo:** Johan logs in as IB admin, creates "TechCorp Sale" project, adds Finance workstream, creates request "Provide audited financials FY2024", invites seller user.

### Sprint 3: Worker View (Week 5-6)
**Goal:** Task inbox. The accountant sees what they need to do.

- [ ] `GET /api/inbox` — returns entries where `assignee_id = me`
- [ ] Task inbox UI — list of "my tasks" with status, due date, priority
- [ ] Request detail view — see full request, thread of events
- [ ] Forward action — assign to someone else, set `return_to_id`
- [ ] Return action — mark done, returns to `return_to_id`
- [ ] entry_events table population — every action creates event
- [ ] Routing chain visibility for IB admin

**Demo:** Seller accountant logs in, sees "Provide audited financials" in their inbox, clicks in, sees request details.

### Sprint 4: Files (Week 7-8)
**Goal:** Upload answers with attachments. Download with watermark.

- [ ] `POST /api/answers` — create answer linked to request
- [ ] File upload endpoint — stores via ObjectStore
- [ ] File metadata in answer's Data JSON
- [ ] `lib/watermark.go` — PDF watermark injection
- [ ] `GET /api/files/:id` — serve file with watermark applied
- [ ] Answer submission — seller marks answer ready for review
- [ ] UI: upload files, attach to answer, submit

**Demo:** Accountant uploads PDF, submits answer. Downloads their own upload — watermark shows their name + timestamp.

### Sprint 5: Data Room (Week 9-10)
**Goal:** IB vets answers. Approved → published to data room. Buyers see it.

- [ ] Answer vetting UI — IB sees submitted answers
- [ ] Approve action — `status = approved`, `stage = dataroom`
- [ ] Reject action — `status = rejected`, add rejection reason, back to seller
- [ ] Data room view — buyers see published answers only
- [ ] Buyer invite flow — same as seller but buyer roles
- [ ] Stage-based visibility in CheckAccess — buyers can't see pre-dataroom
- [ ] Audit log writes for vetting actions + file downloads

**Demo:** IB approves answer. Logs in as buyer — sees the published answer in data room. Downloads PDF — watermark shows buyer's name.

### Sprint 6: Polish (Week 11-12)
**Goal:** Production-ready. Marketing site. Demo data. Deploy.

- [ ] TOTP (2FA) for admin roles
- [ ] Password reset flow
- [ ] Marketing website — embedded in binary, serves at `/`
- [ ] Demo data seed script — realistic TechCorp Sale scenario
- [ ] Error handling polish — consistent error responses
- [ ] Rate limiting on auth endpoints
- [ ] Caddy config for muskepo.com
- [ ] systemd unit for Dealspace binary
- [ ] Deploy to 82.24.174.112
- [ ] Smoke test checklist

**Demo:** Full flow end-to-end. Marketing site live at muskepo.com.

---

## 5. Demo Scenario

**Setup:** IB advisor at Goldman Sachs is selling TechCorp, a mid-market tech company. First 10 minutes in Dealspace.

### Minute 0-2: Create the Deal

1. **Login** → IB admin dashboard (empty state: "Create your first project")
2. **Click "New Project"** → Modal: Project name, deal type, expected close date
   - Name: "TechCorp Sale"
   - Type: "Sell-side M&A"
   - Expected close: 2026-06-30
3. **Create** → Lands in project view with default workstreams

**Screen:** Project header (TechCorp Sale), workstream tabs (Finance | Legal | IT | HR | Operations), empty request list.

### Minute 2-4: Configure Workstreams

1. **Click Finance tab** → Empty state: "No requests yet"
2. **Click "Add Request List"** → Name: "Initial Due Diligence"
3. **Add requests** (quick-add mode, one per line):
   - "Audited financial statements FY2023-2025" (Priority: High)
   - "Revenue breakdown by customer top 20" (Priority: High)
   - "Cap table and option pool details" (Priority: Normal)
   - "AR/AP aging reports" (Priority: Normal)
4. **Repeat for Legal tab:**
   - "Material contracts list"
   - "IP portfolio summary"
   - "Pending litigation summary"

**Screen:** Finance tab shows 4 requests, all status "Open", assigned to "Seller (unassigned)".

### Minute 4-6: Invite Seller Team

1. **Click "Manage Team"** → Team panel slides out
2. **Click "Invite Seller"** → Enter email: sarah@techcorp.com
   - Role: Seller Admin
   - Message: "Welcome to the TechCorp sale process. You'll manage your team's responses."
3. **Send invite** → Sarah gets email with magic link
4. **Add another:** mike@techcorp.com
   - Role: Seller Member
   - Workstreams: Finance (checkbox)
   - Message: "You'll be handling the financial document requests."

**Screen:** Team panel shows: Johan (IB Admin), Sarah (Seller Admin - Pending), Mike (Seller Member - Pending).

### Minute 6-8: Seller Accepts & Sees Inbox

*Switch to Sarah's perspective*

1. **Sarah clicks invite link** → Set password screen → Sets password → Lands in app
2. **Dashboard:** "TechCorp Sale" project card, 7 requests awaiting assignment
3. **Click into project** → Sees all requests, can assign to team
4. **Assigns "Audited financial statements" to Mike**

*Switch to Mike's perspective*

1. **Mike clicks invite link** → Set password → Lands in app
2. **Task Inbox:** Shows 1 task — "Audited financial statements FY2023-2025"
   - From: Goldman Sachs
   - Due: 2026-03-15
   - Priority: High
3. **Click task** → Request detail: full description, empty answer area
4. **Upload button** → Select PDF → File uploads
5. **"Submit Answer"** → Status changes to "Submitted"

**Screen:** Mike's inbox now empty. Task shows "Submitted" status.

### Minute 8-10: IB Vets & Publishes

*Back to Johan (IB admin)*

1. **Notification badge:** "1 answer ready for review"
2. **Click into vetting queue** → Shows Mike's submitted answer
3. **Preview PDF** → Watermark visible: "Johan Jongsma · Goldman Sachs · 2026-02-28 · CONFIDENTIAL"
4. **Click "Approve & Publish"** → Answer moves to data room
5. **Status updates:** Request shows "Published ✓"

**Later: Onboard buyer**

1. **"Invite Buyer"** → buyer@apollo.com, Buyer Admin
2. **Buyer logs in** → Sees data room with 1 published document
3. **Downloads PDF** → Watermark: "Tom Smith · Apollo · 2026-02-28 · CONFIDENTIAL"

**End state:** One complete request cycle. IB created request → Seller answered → IB vetted → Buyer accessed. Watermarks prove chain of custody.

---

## 6. Success Metrics for v1.0

Not revenue. Product quality. What makes this a success before a single dollar changes hands?

### Functionality Metrics

| Metric | Target |
|--------|--------|
| **End-to-end completion** | One full request cycle (create → answer → vet → publish → buyer download) works without errors |
| **RBAC enforcement** | Zero test cases where user sees/modifies data they shouldn't |
| **Watermark integrity** | 100% of downloaded PDFs have correct watermark with actual user/org/timestamp |
| **Audit completeness** | Every file download and status change has audit log entry |

### Performance Metrics

| Metric | Target |
|--------|--------|
| **Page load (p95)** | < 500ms for inbox, project view, request detail |
| **File upload** | < 2s for 10MB PDF |
| **Watermarked download** | < 3s for 10MB PDF (watermark applied at serve time) |
| **Concurrent users** | Handle 50 simultaneous users without degradation |

### Usability Metrics (Misha Demo)

| Metric | Target |
|--------|--------|
| **Time to first request** | IB admin can create project + first request in < 2 minutes |
| **Worker clarity** | Seller member understands their task inbox within 30 seconds of first login |
| **Zero training** | Misha can complete demo scenario without Johan explaining UI |

### Security Metrics

| Metric | Target |
|--------|--------|
| **No plaintext content** | All Summary/Data fields encrypted in DB — `SELECT` returns gibberish |
| **Session security** | Tokens expire, refresh works, logout invalidates |
| **TOTP enforcement** | Admin roles blocked from sensitive actions without 2FA |

### Reliability Metrics

| Metric | Target |
|--------|--------|
| **Uptime** | 99% in first month (allows for hotfixes) |
| **Data integrity** | Zero data loss, zero corruption in normal operation |
| **Graceful errors** | No unhandled panics in production logs |

---

## 7. Risk Mitigations

| Risk | Mitigation |
|------|------------|
| **PDF watermarking is slow** | Cache watermarked versions per (file, user, hour). Invalidate on user/project change. |
| **RBAC bugs expose data** | Every CheckAccess path has explicit test. No data query without RBAC. |
| **Demo fails in front of Misha** | Sprint 2 demo is minimal. Practice run before call. Fallback: video recording. |
| **Scope creep** | This document is the contract. Features not listed are explicitly v1.1+. |
| **Key management** | Ship with per-project derived keys. Rotation documented but not automated in v1.0. |

---

## 8. Open Questions

Resolve before Sprint 3:

1. **Invite UX:** Magic link (one-click) vs. invite code (manual entry)?
   - Lean: Magic link. Simpler UX, standard pattern.

2. **Request quick-add:** Inline form vs. bulk paste (one per line)?
   - Lean: Both. Inline for singles, paste mode for mass import.

3. **Notification strategy:** In-app only, or email for key events?
   - Lean: In-app only for v1.0. Email notifications are v1.1.

4. **Watermark font:** System font or embedded?
   - Lean: Embedded. Consistent across all environments.

---

*This document defines v1.0. Features not listed here are not in v1.0. No exceptions without updating this document first.*