# Veza Integration Reference

## 1. Global Configuration

### Network & Environment
| Config | Value / Default | Source of Truth |
|--------|----------------|-----------------|
| **Backend Port** | `:8080` (Default) | `cmd/api/main.go` |
| **Frontend Port** | `:3000` or `:5173` | `vite.config.ts` |
| **API Base URL** | `http://localhost:8080` | `apps/web/src/config/env.ts` (`VITE_API_URL`) |
| **Auth Header** | `Authorization: Bearer <token>` | `apps/web/src/services/api/client.ts` |
| **Time Format** | ISO 8601 Strings (`2023-12-25T15:04:05Z`) | JSON serialization of `time.Time` |

### System Limits
| Parameter | Limit | implemented In |
|-----------|-------|----------------|
| **Max Track Size** | 100 MB | `internal/core/track/service.go` |
| **Supported Audio** | MP3, FLAC, WAV, OGG, M4A, AAC | `internal/core/track/service.go` |
| **Request Timeout** | 10s (Scan), 30s (Upload/Assembly) | `internal/core/track/handler.go` |
| **Client Timeout** | 10,000ms | `apps/web/src/services/api/client.ts` |

---

## 2. API Surface Coverage

This table compares available Backend routes with Frontend service implementations.

### 🟢 Fully Implemented | ⚠️ Partial / Discrepancy | ❌ Missing in Frontend

#### Auth & Users
| Method | URL | Frontend Function | Status | Notes |
|--------|-----|-------------------|--------|-------|
| `POST` | `/api/v1/auth/login` | `authApi.login` | 🟢 | |
| `POST` | `/api/v1/auth/register` | `authApi.register` | 🟢 | |
| `POST` | `/api/v1/auth/refresh` | `client.ts` (interceptor) | 🟢 | Auto-refresh on 401 |
| `POST` | `/api/v1/auth/logout` | `authApi.logout` | 🟢 | |
| `GET` | `/api/v1/auth/me` | `authApi.getMe` | 🟢 | |
| `GET` | `/api/v1/users/:id` | `userApi.getUser` | 🟢 | |
| `PUT` | `/api/v1/users/:id` | `userApi.updateUser` | 🟢 | Requires Ownership or Admin |

#### Tracks (Core)
| Method | URL | Frontend Function | Status | Notes |
|--------|-----|-------------------|--------|-------|
| `GET` | `/api/v1/tracks` | `trackApi.getTracks` | 🟢 | Supports pagination & filters |
| `POST` | `/api/v1/tracks` | `trackApi.uploadTrack` | ⚠️ | **CRITICAL GAP**: Backend ignores metadata fields (see Section 5) |
| `GET` | `/api/v1/tracks/:id` | `trackApi.getTrack` | 🟢 | |
| `PUT` | `/api/v1/tracks/:id` | `trackApi.updateTrack` | 🟢 | |
| `DELETE` | `/api/v1/tracks/:id` | `trackApi.deleteTrack` | ❌ | Function missing in `trackApi.ts` currently |
| `GET` | `/api/v1/tracks/:id/status` | `trackApi.pollTrackStatus` | 🟢 | Used for async upload polling |

#### Tracks (Features)
| Method | URL | Frontend Function | Status | Notes |
|--------|-----|-------------------|--------|-------|
| `GET` | `/api/v1/tracks/:id/stats` | `trackApi.getTrackStats` | 🟢 | |
| `GET` | `/api/v1/tracks/:id/history` | `trackApi.getTrackHistory` | 🟢 | |
| `GET` | `/api/v1/tracks/:id/download` | `trackApi.downloadTrack` | 🟢 | |
| `POST` | `/api/v1/tracks/:id/like` | `trackApi.likeTrack` | 🟢 | |
| `DELETE` | `/api/v1/tracks/:id/like` | `trackApi.unlikeTrack` | 🟢 | |
| `GET` | `/api/v1/tracks/:id/likes` | `trackApi.getTrackLikes` | 🟢 | |
| `POST` | `/api/v1/tracks/:id/share` | `trackApi.createTrackShare` | 🟢 | |

#### Upload (Chunked)
| Method | URL | Frontend Function | Status | Notes |
|--------|-----|-------------------|--------|-------|
| `POST` | `/api/v1/tracks/initiate` | *No direct function* | ❌ | Chunked upload logic seems internal to `trackApi.uploadTrack` or unimplemented |
| `POST` | `/api/v1/tracks/chunk` | *No direct function* | ❌ | |
| `POST` | `/api/v1/tracks/complete` | *No direct function* | ❌ | |

---

## 3. Data Models Discrepancies

### User Model
| Field | Backend (`models.User`) | Frontend (`interfaces/User`) | Match? |
|-------|-------------------------|------------------------------|--------|
| `ID` | `uuid.UUID` | `string` | ✅ |
| `Username` | `string` | `string` | ✅ |
| `Birthdate` | `*time.Time` (Nullable) | `string` | ⚠️ Frontend expects ISO string, Backend sends strict null or time |
| `UsernameChangedAt` | `*time.Time` | `string` | ⚠️ Same as above |
| `TokenVersion` | `int` | *Missing* | ⚠️ Internal field? |

### Track Model
| Field | Backend (`models.Track`) | Frontend (`interfaces/Track`) | Match? |
|-------|--------------------------|-------------------------------|--------|
| `UserID` | `CreatorID` (JSON) | `creator_id` | ✅ JSON tag aligns |
| `FileID` | `*uuid.UUID` (Nullable) | `string` | ⚠️ Optional vs Nullable |
| `Duration` | `int` (Seconds) | `number` | ✅ |
| `CoverArtPath` | `cover_art_path` | `cover_art_path` | ✅ |
| `StreamManifestURL`| `stream_manifest_url` | `stream_manifest_url` | ✅ |
| `UpdatedAt` | `time.Time` | `string` | ✅ |

---

## 4. Error Handling Protocol

### Protocol Mismatch Alert 🚨
There is a **divergence** between how the Backend reports errors and how the Frontend expects them.

**Backend Format (`middleware.ErrorHandler`):**
```json
{
  "error": {
    "code": 1234,
    "message": "Error message",
    "details": ["Validation error 1"]
  }
}
```
*Note: The root object DOES NOT contain `success: false`.*

**Frontend Expectation (`utils/apiErrorHandler.ts`):**
1. Checks for `{ success: false, error: { ... } }`
2. OR Checks for `{ code: ..., message: ... }` (Root level)

**Consequence**: The Frontend `parseApiError` function will likely fail to extract the structured `ApiError` from the Backend's response, falling back to a generic "An unexpected error occurred" or the raw HTTP status message, losing valuable context (like validation details or specific error codes).

---

## 5. Action Items (Prioritized)

### 🚨 P0 - Critical Integration Fixes
*   **Fix Error Parsing**: Update `apps/web/src/utils/apiErrorHandler.ts` to handle the `{ error: { code: ... } }` format (without `success` field) or update the Backend Middleware to wrap errors in `{ success: false, ... }`.
*   **Fix Track Upload Metadata**: The Frontend creates a `FormData` with `title`, `artist`, `genre`, etc., but the Backend `UploadTrack` handler **ignores** all fields except `file`.
    *   *Remediation*: Update Backend `UploadTrack` to parse `c.PostForm` fields and pass them to `TrackService`.

### ⚠️ P1 - Type Safety & Feature Gaps
*   **Implement Chunked Uploads**: The Frontend is missing the implementation for `/tracks/initiate`, `/tracks/chunk`, and `/tracks/complete`. Large file uploads will be unreliable.
*   **Date Normalization**: Ensure Frontend correctly handles `null` values for `birthdate` and `username_changed_at` instead of potentially expecting empty strings or undefined.

### ℹ️ P2 - Completeness
*   **Implement Delete**: Add `deleteTrack` to `trackApi.ts`.
*   **Sync Async Flows**: Ensure the "Polling" logic in Frontend correctly interprets the Backend's `202 Accepted` response.