diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..38d6848 Binary files /dev/null and b/.DS_Store differ diff --git a/._.DS_Store b/._.DS_Store new file mode 100644 index 0000000..28c42fb Binary files /dev/null and b/._.DS_Store differ diff --git a/docs/._DATAROOM-SPEC.md b/docs/._DATAROOM-SPEC.md new file mode 100644 index 0000000..05857d6 Binary files /dev/null and b/docs/._DATAROOM-SPEC.md differ diff --git a/docs/DATAROOM-SPEC.md b/docs/DATAROOM-SPEC.md new file mode 100644 index 0000000..0bad070 --- /dev/null +++ b/docs/DATAROOM-SPEC.md @@ -0,0 +1,836 @@ +# Dataroom Architecture + +| | | +|---|---| +| **Version** | 1.3 | +| **Date** | 2026-03-22 | +| **Author** | Johan Jongsma | +| **Status** | Draft — for review by Misha | + +*How files, request lists, visibility, tasks, and notifications fit together.* + +## The Problem with "Multiple Datarooms" + +Traditional deal platforms (and DropBox-based workflows) create separate folder trees for each buyer. This causes: + +- **File duplication** — the same income statement exists in 5 folders, each potentially a different version +- **Sync nightmares** — Seller uploads v3, IB updates Buyer A's folder but forgets Buyer B +- **No single source of truth** — which copy is current? +- **Rigid structure** — adding a buyer means cloning an entire folder tree + +DealSpace solves this by storing every file **once** and controlling **who can see it** through visibility rules. A "dataroom" is not a place where files live — it's a **lens** that shows each party the files they're allowed to see. + +--- + +## Parties + +| Role | Description | +|------|-------------| +| **IB** (Investment Bank) | Runs the deal. Pays for DealSpace. Controls all visibility and routing. The intermediary between Seller and Buyers. | +| **Seller** | The company being sold. Uploads documents when requested. Never sees who is asking — all requests come through the IB. | +| **Buyer / PE** | Interested parties evaluating the company. Each buyer sees only what the IB has shared with them. Buyers never see each other. | + +--- + +## Organizations & People + +Organizations and people exist **across deals** — they're platform-level entities, not per-project copies. When an IB adds "Blackstone" to three different deals, it's the same org record, with the same people. Only their **role** and **permissions** vary per deal. + +### Organizations + +``` +org_id — unique, platform-wide +name — "Blackstone" +domains — ["blackstone.com"] (for auto-matching users) +logo — URL +website, phone, address, etc. +``` + +An org is created once (typically via scrape when first encountered) and reused across deals. When the IB looks up `blackstone.com` for a second deal, DealSpace returns the existing record — no re-scrape. + +### People + +People belong to an organization. Their profile is platform-level, but their **role in a deal** is per-deal. + +``` +person (platform-level): + name — "Sarah Chen" + email — "schen@blackstone.com" + title — "Managing Director" + phone, photo, bio, linkedin + +deal membership (per-deal): + person → Sarah Chen + org → Blackstone + deal_role — "lead_contact" | "reviewer" | "uploader" | "viewer" +``` + +### Deal Roles + +Within a deal, each person has a role that determines what they can do and what gets routed to them: + +| Deal Role | Description | Typical Person | +|-----------|-------------|----------------| +| `deal_lead` | Primary contact for this org in the deal. Receives all communications. Can delegate. | MD, Partner, VP | +| `reviewer` | Reviews and approves documents before they go up the chain. | Director, Senior Associate | +| `uploader` | Uploads documents to answer requests. Cannot approve. | Associate, Analyst, Assistant | +| `viewer` | Read-only access to the dataroom. No tasks. | Observers, junior staff, advisors | +| `admin` | Manages the org's team within the deal. Can add/remove people. | Office manager, deal coordinator | + +A person can hold multiple roles (e.g., `deal_lead` + `admin`). + +### Automated Routing + +Deal roles enable semi-automated task routing. When the IB assigns a task to an org (not a specific person), DealSpace routes it based on roles: + +**Inbound request to Seller org:** +``` +IB assigns "Provide Statement KLM" to Seller org + → auto-routes to Seller's deal_lead (CFO) + → CFO can accept, or delegate to a reviewer/uploader in their org +``` + +**Category-based routing:** +Organizations can configure routing rules per document category: + +``` +Seller org routing rules: + Financial/* → CFO (deal_lead) + Legal/* → General Counsel (reviewer) + HR/* → VP People (reviewer) + Operations/* → COO (reviewer) + IT/* → CTO (reviewer) + (default) → CFO (deal_lead) +``` + +When a request for "Employee benefits summary" comes in tagged `HR`, it skips the CFO and goes directly to VP People. The CFO still has visibility (as deal_lead) but doesn't have to manually route every request. + +**Approval chains:** +The routing rules also define who approves on the way back: + +``` +Assistant uploads "Employee Benefits Summary.pdf" + → auto-returns to VP People (reviewer) for approval + → VP People approves → auto-returns to CFO (deal_lead) + → CFO approves → returns to IB +``` + +The IB can override any auto-routing — these are defaults, not constraints. + +### The IB's Own Team + +When the IB creates a deal, their org is automatically added as the first party. The 3-4 bankers working the deal are visible in the Parties tab, with roles: + +``` +Muskepo (IB): + Michael Muskepo — deal_lead + Sarah Kim — reviewer + James Park — uploader, admin +``` + +This makes it clear to the Seller and to IB management who's running the deal. + +### Advisors + +Sellers often bring their own advisors — accountants, lawyers, consultants. These are separate orgs added to the deal with their own roles: + +``` +Seller: Acme Corp + CFO, COO, etc. + +Seller's Counsel: Baker McKenzie + Partner (reviewer) — reviews legal docs before release + Associate (uploader) — prepares and uploads legal docs + +Seller's Accountant: Deloitte + Partner (reviewer) — reviews financial docs + Manager (uploader) — prepares financial docs +``` + +Each advisor org has its own routing rules and visibility scope. The IB controls what each advisor can see — typically limited to their domain (legal advisor sees Legal/*, not Financial/*). + +--- + +## The Deal Lifecycle + +### Phase 1: Preparation + +1. IB creates the deal in DealSpace +2. IB loads their **standard request list** (template) — the checklist of everything they typically need from a seller +3. IB adds the Seller org to the deal +4. IB assigns requests to people at the Seller org +5. Seller uploads documents to answer each request +6. These uploads form the **internal dataroom** — only visible to the IB + +### Phase 2: Initial Offering + +7. IB reviews the internal dataroom +8. IB selects a subset of documents to include in the offering +9. IB shares those documents with "all buyers" — this is the **public dataroom** +10. Buyers are invited to the deal and see only the shared documents +11. Buyers receive a notification: "N documents available" + +### Phase 3: Due Diligence + +12. Each buyer submits their **own request list** — questions and document requests specific to their evaluation +13. IB receives these requests. For each one, IB either: + - **Links an existing file** — "we already have this from Phase 1" + - **Goes back to the Seller** — assigns a new task to get the information +14. When the Seller provides new documents, IB decides visibility: + - Share with the requesting buyer only + - Share with all buyers (if it's common-sense information) +15. When sharing with all buyers, others are notified via batched digest + +### Phase 4: Narrowing + +16. Some buyers drop out, some advance +17. IB may revoke access for eliminated buyers +18. Remaining buyers get deeper access — more sensitive documents shared +19. Process repeats until deal closes + +### Phase 5: Confirmatory Due Diligence + +20. Preferred buyer selected — deal enters final phase +21. Many documents are **refreshed** (updated financials, revised contracts, etc.) +22. Refreshed documents replace the originals silently — no new-document notification +23. Buyer already has access; they see the latest version next time they open it +24. New documents in this phase are shared directly, also without fanfare +25. The dataroom is now a living reference, not a drip feed + +--- + +## Data Model + +### Objects (files) + +Every file is stored exactly once. + +``` +object_id — unique identifier +project_id — which deal this belongs to +filename — "Q3-2025-Income-Statement.pdf" +category — ["Financial", "Historical", "Income Statements"] +stage — draft | review | published +uploaded_by — user who uploaded it +uploaded_at — timestamp +``` + +### Document Versioning + +When a document is updated (e.g., Seller uploads a refreshed income statement), the new version does **not** go live automatically. It follows an approval flow: + +``` +Seller uploads v2 of "Income Statement Q3" + → v2 stored as pending, v1 still served to buyers + → Anonymization runs on v2 (using existing entity registry) + → If no new entities detected and deal is in confirmatory stage: + auto-approve → v2 replaces v1 silently + → Otherwise: + IB reviews anonymized v2 → approves → v2 replaces v1 +``` + +Once approved: +- v2 **replaces** v1 — all existing answer links and visibility rules carry over automatically +- v1 is retained in version history but no longer served by default +- Buyers who already downloaded v1 see v2 next time they open the dataroom + +**Notification behavior depends on deal stage:** + +| Deal Stage | Version Update Behavior | +|------------|------------------------| +| Phase 2-3 (active DD) | Notify buyers: "Updated document available" | +| Phase 4 (narrowing) | Notify only if IB explicitly flags it | +| Phase 5 (confirmatory) | Silent replacement — no notification | + +- IB can always see the full version history and compare versions +- Audit log records who downloaded which version and when +- If a buyer downloaded v1 and v2 replaces it, the audit log retains both records + +### Folder Structure + +The `category` field is a list of tags that creates the illusion of a folder tree: + +``` +Financial/ + Historical/ + Income Statements/ + Q3-2025-Income-Statement.pdf ← category: ["Financial","Historical","Income Statements"] + Q4-2025-Income-Statement.pdf + Projections/ + ... +Legal/ + Corporate/ + Articles of Incorporation.pdf ← category: ["Legal","Corporate"] +``` + +This is a **UI presentation of tags**, not actual nested storage. A file can appear in multiple categories. The IB's "standard dataroom structure" is a category template applied to new deals. + +### Request Lists + +The driver of all document flow. Three types in a typical deal: + +| Request List | From | To | Purpose | +|-------------|------|-----|---------| +| IB Standard RL | IB | Seller | "Give us everything we need to sell your company" | +| Buyer A RL | Buyer A | IB | "We need these specific things to evaluate" | +| Buyer B RL | Buyer B | IB | Different buyer, different questions | + +Each request list contains **requests** — individual line items like "Provide audited financial statements for the last 3 years." + +### Answer Links (many-to-many) + +A single file can answer multiple requests from multiple request lists. + +``` +Request: "Audited financials 2023-2025" (from IB Standard RL) + └── links to → Q3-2025-Income-Statement.pdf + +Request: "Historical P&L" (from Buyer A RL) + └── links to → Q3-2025-Income-Statement.pdf ← same file, different request + +Request: "Revenue breakdown by quarter" (from Buyer B RL) + └── links to → Q3-2025-Income-Statement.pdf ← same file again +``` + +The file exists once. Three requests point to it. No duplication. + +### Q&A (Text Answers) + +Not every request needs a document. Buyers often ask questions that require a text answer: + +- *"What is the customer concentration?"* +- *"Are there any pending litigations?"* +- *"What's the current headcount by department?"* + +These are handled as **text answers** on a request — same routing and visibility rules as document answers, just without a file attachment. + +#### LLM-Suggested Answers + +When a buyer asks a question, the answer may already exist — buried in a document that was uploaded for a completely different request. The LLM scans the existing document set and suggests answers: + +``` +Buyer B asks: "What is the customer concentration?" + +LLM finds: In "2025-Annual-Report.pdf" (uploaded for Buyer A's request +"Revenue breakdown"), page 14 states: "Top 5 customers represent 42% +of revenue, with the largest customer at 11%." + +Suggested answer: "Top 5 customers = 42% of revenue; largest = 11% +(source: 2025 Annual Report, p.14)" +``` + +The IB reviews the suggestion, edits if needed, and approves. The answer is posted to Buyer B's request with the source document optionally linked. + +This works because: +- Documents are flat with content summaries — the LLM can search across all of them +- The answer might come from a document uploaded for the IB's own RL, or from a different buyer's request +- Buyers never see that the answer was sourced from another buyer's request — they just see the answer + +#### Q&A Visibility + +Same rules as documents: +- IB sees all Q&A across all buyers +- Each buyer sees only their own questions and the answers shared with them +- Seller sees questions as "IB asks..." — never the original buyer + +### Object Visibility + +Who can see each file is controlled by explicit visibility rules. + +``` +object_id — which file +scope — "internal" | "all_buyers" | "org:{org_id}" +granted_by — which IB user authorized this +granted_at — when +``` + +A single file can have multiple visibility entries: + +| object_id | scope | meaning | +|-----------|-------|---------| +| doc-123 | `internal` | IB can see it (always present) | +| doc-123 | `all_buyers` | Every buyer in the deal sees it | +| doc-456 | `internal` | IB only — not shared yet | +| doc-456 | `org:buyer-A` | Only Buyer A sees this | +| doc-789 | `internal` | Uploaded by Seller, under IB review | + +#### How Each Party's "Dataroom" is Derived + +**IB (internal view):** All objects in the project. Plus metadata showing sharing status ("not shared", "shared with all", "Buyer A only"). + +**Seller:** Objects they uploaded + objects the IB explicitly shared with them (e.g., the request list, IB comments). + +**Buyer A:** Objects where visibility scope includes `all_buyers` OR `org:buyer-A`. This is their "dataroom." They have no knowledge that other documents or other buyers exist. + +**Buyer B:** Same logic, different org_id → completely different view of the same underlying file set. + +--- + +## RBAC + +### Permissions Matrix + +| Action | IB | Seller | Buyer | +|--------|-----|--------|-------| +| Upload files | Yes | Yes (answering requests) | No | +| See all files in deal | Yes | No | No | +| See own uploads | Yes | Yes | N/A | +| See shared files | Yes | Only what's shared with them | Only what's shared with them | +| Change file visibility | Yes | No | No | +| Share with specific buyer | Yes | No | No | +| Share with all buyers | Yes | No | No | +| Revoke buyer access | Yes | No | No | +| See who has access to a file | Yes | No | No | +| See other buyers exist | Yes | Configurable | Never | +| Download (full) | Yes | No | No | +| Download (watermarked) | Configurable | Yes | Yes | +| Create request list | Yes | No | Yes (their own RL) | +| Assign tasks | Yes | Within their org | No | +| See who requested a document | Yes | Never (anonymized by IB) | Own requests only | + +### Anonymization & Redaction + +Seller documents often contain information that must not reach buyers in raw form — customer names, vendor names, employee names, contract counterparties, sometimes even the Seller's own name (the company is often code-named, e.g., "Project Atlas"). + +This is not simple find-and-replace. It requires **consistent entity replacement across the entire dataroom** — if "Acme Corp" appears in 40 documents, it must become "Customer A" in all 40. + +#### Entity Registry + +Each deal maintains an **entity registry** — a mapping table of real names to anonymized labels: + +``` +Entity Registry — Project Atlas: + + Customers: + Acme Corp → Customer A + Globex Industries → Customer B + Initech → Customer C + + Vendors: + Smith & Sons → Vendor A + Delta Logistics → Vendor B + + Employees: + Jane Rodriguez → [redacted] / "the VP of Sales" + + The Company: + Springfield Manufacturing → "the Company" / "Project Atlas" +``` + +This registry is **deal-wide**. Every document processed through the anonymization layer uses the same mapping, ensuring consistency. + +#### LLM-Assisted Detection + +When the IB uploads or reviews a document before sharing: + +1. LLM scans the document and identifies entities — company names, person names, addresses, phone numbers, contract counterparties +2. Each entity is matched against the registry: + - **Known entity** → auto-replaced with its alias ("Acme Corp" → "Customer A") + - **New entity** → flagged for IB to classify and assign an alias +3. IB reviews the anonymized version and approves + +``` +LLM detected 3 entities in "Top-Customers-2025.xlsx": + + ✓ Acme Corp → Customer A (auto-matched from registry) + ✓ Globex Industries → Customer B (auto-matched) + ⚠ Wayne Enterprises → [NEW — assign alias?] + Suggested: Customer D + + [Approve All] [Review Individually] +``` + +#### Consistency Across Documents + +The entity registry ensures that: +- "Acme Corp" in the revenue breakdown is the same "Customer A" as in the contracts folder +- A buyer reading the financial model and then a customer contract sees consistent references +- When a new document mentions a previously-registered entity, it's auto-replaced without IB intervention + +#### What Gets Anonymized + +| Category | Treatment | +|----------|-----------| +| Customer names | Replaced: "Customer A", "Customer B", ... | +| Vendor/supplier names | Replaced: "Vendor A", "Vendor B", ... | +| Employee names (below C-suite) | Redacted or replaced with role: "the VP of Sales" | +| C-suite names | Usually kept (buyers need to know who they're dealing with) | +| The company itself | Replaced with codename until LOI stage | +| Addresses, phone numbers | Redacted unless relevant | +| Contract values | IB decides per document — sometimes ranges replace exact figures | + +#### Versioning & Anonymization + +Two versions of each document exist internally: + +- **Original** — as uploaded by the Seller, with all real names. Only visible to IB. +- **Anonymized** — processed through the entity registry. This is what buyers see. + +When the Seller uploads a new version, the anonymization runs again using the same registry. The IB reviews the anonymized output (not the original — they've already seen that). If no new entities are detected, it can auto-approve. + +#### Approval Flow + +``` +Seller uploads document + → LLM scans for entities + → Known entities auto-replaced via registry + → New entities flagged for IB + → IB assigns aliases for new entities (added to registry) + → IB reviews anonymized version + → IB approves → document available in buyer datarooms +``` + +In later deal stages (confirmatory), anonymization may be relaxed — the buyer knows who the company is by then. The IB controls this per-stage. + +### Watermarking + +Every download by a Seller or Buyer is watermarked at serve time: + +``` +{user_name} · {org_name} · {datetime} · CONFIDENTIAL +``` + +This is non-negotiable and cannot be disabled. IB downloads may optionally be watermarked. + +### Buyer Isolation + +Buyers must never: +- See other buyers' names, org names, or any identifying information +- Know how many other buyers exist +- See documents shared exclusively with other buyers +- See other buyers' request lists or questions + +This is enforced at the **data layer**, not just the UI. Queries for buyer users filter by their org's visibility scope before results leave the database. + +--- + +## Task Chain + +A request becomes a **task** when it needs action from someone. Tasks route through a chain of people, tracking who assigned it and who it should return to. + +### Example Flow + +Buyer C submits a request: *"Provide Statement KLM"* + +``` +1. Buyer C asks + → appears in IB's task inbox + +2. IB assigns to Seller CFO + → assignee: CFO + → return_to: IB + → origin: Buyer C (hidden from Seller) + → CFO sees: "IB requests Statement KLM" + +3. CFO delegates to Director of Operations + → assignee: Director + → return_to: CFO + +4. Director delegates to Assistant + → assignee: Assistant + → return_to: Director + +5. Assistant completes the work, uploads the file + → task returns to Director + +6. Director reviews, approves + → task returns to CFO + +7. CFO approves + → task returns to IB + +8. IB reviews, anonymizes if needed + → releases to Buyer C's dataroom + → Buyer C's request is marked as answered +``` + +### Fields on Each Request + +``` +assignee_id — who currently owns this task +return_to_id — who it goes back to when done +origin_id — who originally asked (hidden from Seller) +stage — open | in_progress | review | complete +due_date — optional deadline +``` + +### Auto-Flow + +When the current assignee marks a task as **complete** or **approved**, the system automatically reassigns to `return_to_id`. No manual handoff needed — the task flows back up the chain by itself: + +``` +Assistant completes → auto-assigns to Director +Director approves → auto-assigns to CFO +CFO approves → auto-assigns to IB +``` + +If the reviewer **rejects**, the task flows back down to the previous assignee with a note. + +### Visibility Along the Chain + +**IB sees everything.** Regardless of where a task currently sits in the chain, the IB can see: +- Current assignee ("sitting with: Assistant, Seller Org") +- How long it's been there +- The full chain history (who had it, for how long) +- Whether it's at risk of missing a deadline + +**Delegators see their subtree.** The CFO who delegated to the Director can see that the Director re-delegated to the Assistant, and that the Assistant has had it for 3 days. The Assistant cannot see that the CFO delegated it — only that the Director assigned it. + +### Nudging + +Tasks that sit too long get nudged automatically: + +| Condition | Action | +|-----------|--------| +| Task unactioned for 48h | Remind current assignee | +| Task unactioned for 5 days | Escalate to the person who delegated it | +| Task approaching due date (2 days) | Remind assignee + notify delegator | +| Task overdue | Notify IB + delegator + assignee | + +Nudge frequency is configurable per deal. Nudges go to individuals, not broadcast. + +### Key Rules + +- **Seller never sees the origin.** The CFO sees "IB requests Statement KLM", not "Buyer C wants Statement KLM." The IB is always the visible requester. +- **Each person in the chain sees it in their task inbox.** "My Tasks" shows everything currently assigned to you. +- **The chain is unbounded.** CFO → Director → Assistant → Intern → ... → back up the chain. Each handoff is tracked. +- **Approval on the way back up.** Each person in the return chain reviews before passing it up. Any person can reject and send it back down. +- **IB always has full visibility.** Even when a task is 4 levels deep in the Seller's org, the IB can see exactly where it is and who's holding it up. + +--- + +## LLM-Assisted Matching + +When a buyer submits a request list, many items will overlap with documents already in the internal dataroom. Instead of the IB manually hunting through hundreds of files, the LLM suggests matches. + +### How It Works + +1. Buyer B submits their RL with 80 line items +2. DealSpace runs each request against the existing document set (filename, category, content summary, linked request text) +3. The LLM returns suggested matches with confidence: + +``` +Request: "Audited financial statements 2023-2025" + → Suggested match: Q3-2025-Income-Statement.pdf (92% confidence) + → Suggested match: 2024-Annual-Audit-Report.pdf (88% confidence) + → No match found for: "Environmental compliance certificates" +``` + +4. IB reviews the suggestions in a single approval screen: + - **Accept** — link the file to the request, set visibility for Buyer B + - **Reject** — not the right document, will need to source it + - **Accept + share with all** — this is common-sense info, share with everyone + +5. Unmatched requests become tasks, routed to the Seller + +### What the LLM Matches On + +- Document filename and category tags +- The original request text that the document answered (from the IB's own RL) +- Document content summary (extracted at upload time) +- Semantic similarity — "P&L" matches "Profit and Loss Statement" matches "Income Statement" + +### IB Always Approves + +The LLM never auto-shares. Every suggestion requires explicit IB approval. The LLM saves time finding candidates — the IB makes the decision. + +--- + +## Notifications + +### The Problem + +When IB shares a document with all buyers, each buyer should know. But: +- Don't spam — 50 documents shared in one afternoon shouldn't mean 50 emails +- Stay relevant — don't notify about documents a buyer already has +- Respect isolation — never leak information about other buyers + +### Batched Digests + +Notifications are **batched** per buyer, delivered as periodic digests: + +``` +Subject: 12 new documents available — Project Atlas + +Hi Sarah, + +12 new documents have been added to your dataroom since your last visit: + + Financial (4) + • Q3 2025 Income Statement + • Q4 2025 Income Statement + • 2025 Balance Sheet + • Revenue Breakdown by Region + + Legal (3) + • Articles of Incorporation + • Board Resolutions 2024-2025 + • Shareholder Agreement + + Operations (5) + • ... + +View your dataroom: [link] +``` + +### Batching Rules + +- **Frequency:** Configurable per deal — hourly, daily, or on-demand +- **Deduplication:** Only notify about documents the buyer hasn't seen yet +- **Relevance:** If a document was shared because Buyer A asked for it, and Buyer B already has it via a different request link, don't include it in Buyer B's digest +- **Grouping:** Group by category (the same tags used for the folder view) + +### Task Notifications + +Task assignments are **near-immediate but coalesced** — if the IB assigns 10 requests to the CFO in one sitting, they arrive as a single notification, not 10 emails. Coalescing window: 15 minutes. + +``` +Subject: 3 new requests assigned to you — Project Atlas + +You have 3 new requests: + + • Provide Statement KLM (due: Mar 28) + • Board meeting minutes 2024 (due: Mar 30) + • Employee headcount by department (due: Apr 2) + +View your tasks: [link] +``` + +### Daily Status Digest + +Every active participant gets a daily summary (morning, their timezone) of their open tasks: + +``` +Subject: Your daily update — Project Atlas + +Tasks assigned to you: 5 + • 2 new (assigned yesterday) + • 1 due today: "Provide Statement KLM" + • 1 overdue (3 days): "Environmental compliance certs" + • 1 in progress + +Tasks you're waiting on: 3 + • Delegated to J. Smith (2 days ago, no action yet) + • Delegated to M. Lee (completed, pending your review) + • Delegated to R. Patel (in progress) +``` + +No daily digest is sent if nothing has changed since the last one. + +--- + +## Deal Stages & Gates + +A deal progresses through defined stages. Each stage controls default behavior for notifications, visibility, and document updates. + +``` +preparation → offering → due_diligence → narrowing → confirmatory → closed +``` + +| Stage | Description | Notification Default | +|-------|-------------|---------------------| +| `preparation` | IB collecting from Seller | No buyer access | +| `offering` | Initial docs shared with buyers | Notify on new shares | +| `due_diligence` | Buyers asking questions, requesting docs | Notify on new shares | +| `narrowing` | Fewer buyers, deeper access | Notify only if IB flags | +| `confirmatory` | Final buyer, refreshing docs | Silent — no notifications | +| `closed` | Deal done | Dataroom frozen, read-only | + +### Stage Transitions + +- IB controls stage transitions manually +- Moving to `closed` freezes the dataroom — no uploads, no visibility changes, download-only +- Moving to `confirmatory` switches notification behavior to silent by default +- Revoking a buyer's access can happen at any stage (buyer eliminated) + +### Deadline Gates + +The IB can set deadlines on stages: + +- "Round 1 bids due by March 30" — after which buyer access may be frozen or restricted +- "Final documents due April 15" — Seller deadline for all outstanding requests +- Deadlines trigger automated reminders via the nudging system + +--- + +## Audit Trail + +Every meaningful action is logged. This is non-negotiable — the audit log cannot be disabled, paused, or tampered with. + +### What's Logged + +| Event | Details Recorded | +|-------|-----------------| +| Document uploaded | Who, when, filename, category, size | +| Document viewed | Who, when, which version | +| Document downloaded | Who, when, which version, watermark ID | +| Visibility changed | Who granted/revoked, which file, which party | +| Request created | Who, which RL, text | +| Request answered | Who, text/file, which request | +| Task assigned | Who assigned, to whom, which request | +| Task completed | Who, when, how long it took | +| Login | Who, when, IP, device | +| Stage transition | Who, from/to stage, when | +| Access granted/revoked | Who, which org, by whom | + +### Analytics for IB + +The audit trail isn't just compliance — it's a **buyer engagement signal**. The IB can see: + +- **Activity heatmap** — which buyers are actively reviewing documents vs. going cold +- **Document interest** — which files get the most views/downloads (signals what matters to buyers) +- **Response time** — how quickly each buyer engages with new documents +- **Coverage** — which documents a buyer hasn't opened yet + +``` +Buyer A: Last active 2 hours ago, downloaded 47 of 150 docs, avg response: 4 hours +Buyer B: Last active 12 days ago, downloaded 3 of 150 docs — likely dropping out +Buyer C: Downloaded everything within 24 hours — very engaged +``` + +This helps the IB prioritize which buyers to focus on, and when to follow up. + +### Retention + +Audit logs are retained for the life of the deal plus a configurable retention period (default: 7 years, per regulatory requirements). Logs are immutable — append-only, no edits, no deletes. + +--- + +## Standard Templates + +IB firms reuse the same structure across deals. DealSpace supports templates for: + +### Request List Templates +A standard checklist (e.g., "M&A Due Diligence — Full") that can be loaded into any new deal. Contains sections and individual request items, but no answers or files. + +### Dataroom Category Templates +A standard folder structure (e.g., "Financial / Historical / ...", "Legal / Corporate / ...") that defines the category tags available in a deal. When the Seller uploads a file, they pick from these categories. + +Templates are org-level resources — each IB firm maintains their own library. + +--- + +## Summary + +| Concept | Implementation | +|---------|---------------| +| File | Stored once as an Object, tagged with categories | +| Folder structure | UI rendering of category tags, not physical nesting | +| Dataroom | A filtered view based on the viewer's visibility scope | +| Internal dataroom | All objects (IB-only view) | +| Buyer's dataroom | Objects where scope = `all_buyers` or `org:{buyer}` | +| Request → File link | Answer Links (many-to-many) | +| Q&A | Text answers on requests, same visibility rules as documents | +| "Copy file to another dataroom" | Add a visibility scope entry (no file duplication) | +| Document versioning | Replace-in-place, notification behavior varies by deal stage | +| Task routing | assignee_id / return_to_id / origin_id chain, auto-flow on completion | +| Task nudging | Automated escalation at 48h, 5d, near-deadline, overdue | +| LLM matching | Suggests document + text matches for buyer requests, IB approves | +| Notifications | Batched digests for documents, coalesced for tasks, daily status | +| Audit trail | Every view, download, share, assignment — immutable, always on | +| Buyer analytics | Engagement signals from audit data — activity, interest, coverage | +| Deal stages | preparation → offering → DD → narrowing → confirmatory → closed | +| Organizations | Platform-level, reused across deals, matched by domain | +| People | Belong to orgs, deal roles determine routing and permissions | +| Auto-routing | Tasks route by org deal_role + category-based rules | +| Advisors | Separate orgs with scoped visibility (legal sees Legal/*, etc.) |