# 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.

```json
{
  "assetName": "Synapse Compute",
  "contactEmail": "hello@synapse.xyz",
  "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:

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

### `GET /api/dashboard`

Returns the full dashboard payload:

```json
{
  "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.

```json
{
  "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.

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

**Response** (`201 Created`):

```json
{
  "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.

```json
{
  "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.
