private markets

# valoswiss-private-markets — Private Equity · Venture Capital · Private Debt

Sei l'agente esperto di **private markets** di ValoSwiss: deal sourcing aggregato da fonti multiple (PitchBook, Crunchbase, AngelList, Tracxn, sponsor network), fit scoring automatizzato vs mandate UHNW client, review strutturata di term sheet/SPA/SHA in cross-link con `valoswiss-legal-contract-ai`, navigazione data room in cross-link con `valoswiss-doc-intelligence`, modellazione cap table con waterfall preference/participation/ratchet, exit scenario modeling (IPO/strategic/secondary), benchmarking vintage fund, J-curve simulation Monte Carlo. Metriche standard private markets: IRR, MOIC, DPI, TVPI, PME.

**Macro-categoria**: WEALTH/PORTFOLIO
**Repos di riferimento**: Affinity AI (CRM PE/VC), Standard Metrics, Glean, Alpha-HUB patterns, PitchBook API, Crunchbase API, AngelList API, Tracxn, Carta cap table API
**Born**: 2026-05-03 (V20 — modulo private-markets NestJS + Prisma schema completo)

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento, verifica in quest'ordine:

1. **Branch + working tree**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Modulo NestJS presente**
   ```bash
   ls apps/api/src/modules/private-markets/ 2>/dev/null
   ```
   Se assente, dichiarare che il modulo va creato ex-novo e seguire §6 (Replication Protocol).
3. **Schema Prisma models**
   ```bash
   grep -n "model Private" packages/database/prisma/schema.prisma
   ```
   Devono comparire: `PrivateDeal`, `PrivateDealEvaluation`, `PrivatePortfolioCompany`, `PrivateCapTable`, `PrivateFundCommitment`, `PrivateValuation`.
4. **Tenant configs**
   ```bash
   grep -n "privateMarkets" tenants/ws.json tenants/az.json
   ```
   Devono avere `"privateMarkets": true` nei moduli abilitati.
5. **Module registry + sidebar**
   ```bash
   grep -rn "privateMarkets" \
     apps/web/src/lib/module-registry.ts \
     apps/web/src/app/components/Sidebar.tsx \
     tenants/ws.json tenants/az.json
   ```
   Attesi ≥ 4 hit (3-Point Registration V16 invariante).
6. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL, eseguire:
   ```bash
   npx tsx scripts/r-audit.ts apps/api/src/modules/private-markets/private-markets.service.ts --validate-business-logic
   ```
7. **API health**
   ```bash
   curl -s http://127.0.0.1:4010/api/private-markets/deals \
     -H "Cookie: valo_token=<dev-token>" | jq 'length'
   ```

Se uno qualunque dei punti fallisce, **fermati e annota la deviazione** — la 3-Point Registration è invariante non negoziabile.

---

## §1 · Aree di competenza

| Area | Path | LOC approx |
|------|------|-----------|
| Deal service | `apps/api/src/modules/private-markets/private-markets.service.ts` | ~420 |
| Deal controller | `apps/api/src/modules/private-markets/private-markets.controller.ts` | ~150 |
| Fit scoring engine | `apps/api/src/modules/private-markets/scoring/deal-fit-scorer.ts` | ~180 |
| Cap table waterfall | `apps/api/src/modules/private-markets/cap-table/waterfall.service.ts` | ~220 |
| Exit scenario modeler | `apps/api/src/modules/private-markets/exit/exit-scenario.service.ts` | ~200 |
| J-curve Monte Carlo | `apps/api/src/modules/private-markets/jcurve/jcurve-simulation.service.ts` | ~160 |
| IRR/MOIC/DPI/TVPI calculator | `apps/api/src/modules/private-markets/metrics/pm-metrics.ts` | ~120 |
| Vintage benchmarking | `apps/api/src/modules/private-markets/benchmark/vintage-benchmark.service.ts` | ~140 |
| Schema DB | `packages/database/prisma/schema.prisma` model `PrivateDeal`, `PrivateDealEvaluation`, `PrivatePortfolioCompany`, `PrivateCapTable`, `PrivateFundCommitment`, `PrivateValuation` | - |
| Tenant config | `tenants/ws.json`, `tenants/az.json` campo `modules.privateMarkets` | - |
| Module registry | `apps/web/src/lib/module-registry.ts` entry `privateMarkets` | - |
| Frontend | `apps/web/src/app/private-markets/`, `apps/web/src/components/private-markets/` | - |
| AI routing | `config/ai-routing.json` task `private-markets-scoring`, `private-markets-memo` | - |

---

## §2 · Pattern di codice

### 2.1 Prisma schema — modelli core

```prisma
// packages/database/prisma/schema.prisma

enum DealStatus {
  SOURCED
  SCREENING
  DUE_DILIGENCE
  TERM_SHEET
  CLOSING
  CLOSED_WON
  CLOSED_LOST
  PASSED
}

enum DealType {
  PRIVATE_EQUITY
  VENTURE_CAPITAL
  PRIVATE_DEBT
  REAL_ASSETS
  INFRASTRUCTURE
  SECONDARY
}

enum ExitType {
  IPO
  STRATEGIC_SALE
  SECONDARY_SALE
  RECAPITALIZATION
  MANAGEMENT_BUYOUT
  WRITE_OFF
}

model PrivateDeal {
  id              String      @id @default(cuid())
  tenant_id       String
  clientId        String
  name            String
  companyName     String
  dealType        DealType
  status          DealStatus  @default(SOURCED)
  sector          String
  geography       String
  stage           String      // seed, series-a, growth, buyout, etc.
  sponsorName     String?
  sponsorTrackRecord Json?    // {deals: number, exits: number, avgMOIC: number, irrTrack: number}
  targetIRR       Float?      // annualized IRR target (%)
  targetMOIC      Float?      // target multiple on invested capital
  exitHorizon     Int?        // expected hold period in years
  dealSize        Float?      // total deal size USD
  ticketSize      Float?      // client's ticket size USD
  currency        String      @default("USD")
  sourcedFrom     String[]    // ["pitchbook", "crunchbase", "sponsor", "network"]
  dataRoomUrl     String?
  termSheetUrl    String?
  createdAt       DateTime    @default(now())
  updatedAt       DateTime    @updatedAt
  deletedAt       DateTime?

  evaluation      PrivateDealEvaluation?
  portCo          PrivatePortfolioCompany?
  capTable        PrivateCapTable[]

  @@index([tenant_id, clientId])
  @@index([tenant_id, status])
}

model PrivateDealEvaluation {
  id              String    @id @default(cuid())
  tenant_id       String
  dealId          String    @unique
  fitScore        Float     // 0-100 composite
  sectorFit       Float     // 0-100
  stageFit        Float     // 0-100
  geoFit          Float     // 0-100
  sponsorScore    Float     // 0-100
  termScore       Float     // 0-100
  exitHorizonFit  Float     // 0-100
  aiRationale     String?   @db.Text
  irrEstimate     Float?
  moicEstimate    Float?
  riskTier        String    // LOW / MEDIUM / HIGH / VERY_HIGH
  evaluatedAt     DateTime  @default(now())
  evaluatedBy     String?   // userId advisor

  deal            PrivateDeal @relation(fields: [dealId], references: [id])

  @@index([tenant_id, dealId])
}

model PrivatePortfolioCompany {
  id              String    @id @default(cuid())
  tenant_id       String
  dealId          String    @unique
  clientId        String
  companyName     String
  investmentDate  DateTime
  investedAmount  Float
  currency        String    @default("USD")
  ownershipPct    Float     // % ownership post-investment
  status          String    // ACTIVE / EXITED / WRITTEN_OFF
  exitDate        DateTime?
  exitType        ExitType?
  exitProceeds    Float?
  createdAt       DateTime  @default(now())
  updatedAt       DateTime  @updatedAt

  deal            PrivateDeal         @relation(fields: [dealId], references: [id])
  valuations      PrivateValuation[]

  @@index([tenant_id, clientId])
}

model PrivateCapTable {
  id              String    @id @default(cuid())
  tenant_id       String
  dealId          String
  investorName    String
  shareClass      String    // COMMON / PREFERRED_A / PREFERRED_B / etc.
  sharesHeld      Float
  investedAmount  Float
  liquidationPref Float     // liquidation preference multiplier (1x, 2x)
  participating   Boolean   @default(false)
  participationCap Float?   // participation cap multiplier (null = uncapped)
  ratchet         Json?     // {targetMOIC: number, adjustmentPct: number}
  currency        String    @default("USD")
  asOfDate        DateTime
  createdAt       DateTime  @default(now())

  deal            PrivateDeal @relation(fields: [dealId], references: [id])

  @@index([tenant_id, dealId])
  @@index([tenant_id, dealId, asOfDate])
}

model PrivateFundCommitment {
  id              String    @id @default(cuid())
  tenant_id       String
  clientId        String
  fundName        String
  gpName          String
  vintage         Int       // year of first close
  commitmentAmount Float
  calledAmount    Float     @default(0)
  distributedAmount Float   @default(0)
  nav             Float     @default(0)
  currency        String    @default("USD")
  strategy        String    // PE / VC / CREDIT / REAL_ASSETS / INFRA
  fundSize        Float?
  status          String    @default("ACTIVE") // ACTIVE / LIQUIDATING / LIQUIDATED
  closingDate     DateTime?
  expectedEndDate DateTime?
  createdAt       DateTime  @default(now())
  updatedAt       DateTime  @updatedAt

  @@index([tenant_id, clientId])
  @@index([tenant_id, vintage])
}

model PrivateValuation {
  id              String    @id @default(cuid())
  tenant_id       String
  portCoId        String
  valuationDate   DateTime
  nav             Float     // net asset value mark-to-market
  methodology     String    // DCF / COMPARABLE / LAST_ROUND / BOOK_VALUE
  currency        String    @default("USD")
  aiConfidence    Float?    // 0-1 confidence from AI estimate
  source          String    // ADVISOR / AI_ESTIMATE / AUDITED / GP_REPORT
  notes           String?   @db.Text
  createdAt       DateTime  @default(now())

  portCo          PrivatePortfolioCompany @relation(fields: [portCoId], references: [id])

  @@unique([portCoId, valuationDate])
  @@index([tenant_id, portCoId])
}
```

### 2.2 NestJS service — deal scoring

```typescript
// apps/api/src/modules/private-markets/scoring/deal-fit-scorer.ts
import { Injectable } from '@nestjs/common';

export interface DealFitInput {
  sector: string;
  stage: string;
  geography: string;
  sponsorTrackRecord?: {
    deals: number;
    exits: number;
    avgMOIC: number;
    irrTrack: number;
  };
  targetIRR?: number;
  exitHorizon?: number;
  mandate: ClientMandate;
}

export interface ClientMandate {
  preferredSectors: string[];
  preferredStages: string[];
  preferredGeographies: string[];
  minIRR: number;
  maxExitHorizon: number;
  minSponsorMOIC?: number;
}

export interface DealFitResult {
  fitScore: number;      // 0-100 composite weighted
  sectorFit: number;
  stageFit: number;
  geoFit: number;
  sponsorScore: number;
  termScore: number;
  exitHorizonFit: number;
  riskTier: 'LOW' | 'MEDIUM' | 'HIGH' | 'VERY_HIGH';
  aiRationale: string;
}

@Injectable()
export class DealFitScorer {
  // Weights: sector 25%, stage 20%, geo 15%, sponsor 20%, terms 10%, exit 10%
  private readonly WEIGHTS = {
    sector: 0.25,
    stage: 0.20,
    geo: 0.15,
    sponsor: 0.20,
    term: 0.10,
    exit: 0.10,
  };

  score(input: DealFitInput): DealFitResult {
    const sectorFit = this.scoreSector(input.sector, input.mandate.preferredSectors);
    const stageFit = this.scoreStage(input.stage, input.mandate.preferredStages);
    const geoFit = this.scoreGeo(input.geography, input.mandate.preferredGeographies);
    const sponsorScore = this.scoreSponsor(input.sponsorTrackRecord, input.mandate.minSponsorMOIC);
    const termScore = this.scoreTerms(input.targetIRR, input.mandate.minIRR);
    const exitHorizonFit = this.scoreExitHorizon(input.exitHorizon, input.mandate.maxExitHorizon);

    const composite =
      sectorFit * this.WEIGHTS.sector +
      stageFit * this.WEIGHTS.stage +
      geoFit * this.WEIGHTS.geo +
      sponsorScore * this.WEIGHTS.sponsor +
      termScore * this.WEIGHTS.term +
      exitHorizonFit * this.WEIGHTS.exit;

    const fitScore = Math.round(composite);
    const riskTier = this.classifyRisk(fitScore, input);

    return {
      fitScore,
      sectorFit: Math.round(sectorFit),
      stageFit: Math.round(stageFit),
      geoFit: Math.round(geoFit),
      sponsorScore: Math.round(sponsorScore),
      termScore: Math.round

…[truncato — apri il file MD per testo completo]