Backend & API Reference

This document covers the internal server routes hosted by the Next.js application in web/. All endpoints currently operate in-memory; persistence and authentication will be added in a future milestone.

Common Conventions

• Base URL (local): http://localhost:3000

• Format: JSON request/response.

• Auth: None (development only). Do not expose these endpoints publicly without adding auth + rate limiting.

• Timezones: All timestamps use ISO 8601 in UTC.

Submissions API

POST /api/submissions

Accepts project details from the public web form.

{
  "assetName": "Synapse Compute",
  "contactEmail": "[email protected]",
  "projectWebsite": "https://synapse.xyz",
  "missionSummary": "GPU credit marketplace for AI teams...",
  "tokenAddress": "4Nd1N...",
  "keyMetrics": "18% MoM wallet growth",
  "additionalNotes": "Investor deck: https://..."
}

Responses:

• 200 OK – submission accepted and queued for analyst review.

• 4xx – validation failure; response includes { "error": "message" }.

Behaviour:

• Records submissions in a server-side map keyed by UUID.

• Auto-purges entries after 24 hours to honour the privacy promise.

GET /api/submissions

Internal endpoint returning the current in-memory queue. Use for debugging while the server is running; data disappears after TTL.

Dashboard API

Data Model

Defined in web/src/types/dashboard.ts:

• DashboardMetric: numeric KPI with period deltas.

• PipelineStage: eight-stage verification checkpoint status.

• AssetSnapshot: portfolio item with stage, analyst owner, risk flags, and optional KYC metadata.

• VerificationEvent: chronological event log referencing an asset + stage.

AssetSnapshot.kyc contains:

{
  status: "unknown" | "pending" | "verified" | "failed";
  provider?: string;
  referenceId?: string;
  verifiedAt?: string | null;
}

GET /api/dashboard

Returns the full dashboard payload:

{
  "metrics": [...],
  "pipeline": [...],
  "assets": [...],
  "events": [...],
  "generatedAt": "2025-10-29T16:20:00.000Z"
}

Seed data includes two example assets (synapse-compute, atlas-mobility) and recent verification events to drive prototypes.

POST /api/dashboard

Upserts an asset and/or records a verification event. Either object can be omitted if only one action is needed.

{
  "asset": {
    "id": "atlas-mobility",
    "name": "Atlas Mobility",
    "symbol": "ATMO",
    "network": "Solana",
    "missionSummary": "Tokenised rail electrification credits...",
    "analystOwner": "K. Banerjee",
    "stage": "mission-prep",
    "submittedAt": "2025-10-01T18:35:10.000Z",
    "riskFlags": ["Awaiting founder history review"]
  },
  "event": {
    "assetId": "atlas-mobility",
    "stage": "mission-prep",
    "status": "in-progress",
    "summary": "Draft brief routed to mobility diligence pod."
  }
}

Responses:

• 201 Created – event logged (with optional asset upsert).

• 200 OK – asset upsert without event.

• Includes the refreshed dashboard snapshot plus asset/event echoes.

Validation Rules:

• stage must be one of the eight verification keys.

• status must be pending, in-progress, or complete.

• submittedAt / recordedAt must be valid ISO timestamps.

• Events require an existing asset (or one included in the same request).

• Optional kyc payloads accept status, provider, referenceId, and verifiedAt (ISO timestamp).

KYC API (Persona Proxy)

These endpoints simulate a trusted third-party integration so engineers can test the KYC flow locally. Production wiring should swap the session URLs and webhook signing with the real provider.

POST /api/kyc/initiate

Creates a pending Persona session for an asset.

{
  "assetId": "synapse-compute",
  "assetName": "Synapse Compute",
  "analystOwner": "A. Romero"
}

Response (201 Created):

{
  "session": {
    "referenceId": "kyc_synapse-compute_c1d7...",
    "assetId": "synapse-compute",
    "assetName": "Synapse Compute",
    "provider": "Persona",
    "status": "pending",
    "createdAt": "2025-10-29T16:30:10.000Z",
    "expiresAt": "2025-10-30T16:30:10.000Z"
  },
  "verificationUrl": "https://persona-verify.techinvestor.com/session/kyc_synapse-compute_c1d7..."
}

The dashboard store is updated to mark the asset’s KYC status as pending.

POST /api/kyc/callback

Simulates the Persona webhook when a session resolves.

{
  "referenceId": "kyc_synapse-compute_c1d7...",
  "status": "verified",
  "verifiedAt": "2025-10-29T17:05:42.000Z"
}

Responses:

• 200 OK – session updated, dashboard asset KYC information refreshed.

• 4xx – invalid payload or unknown reference.

If status is verified, the asset’s kyc.status becomes verified and the green flag can render in future UI layers.

Future Enhancements

• Persist submissions and dashboard data in Postgres (via Prisma) for durability.

• Add analyst authentication and role-based access control.

• Integrate automated scoring engines (mission, risk) and background workers for data refresh.

• Emit webhooks or SSE streams so the dashboard UI can live-update.