veza/INTEGRATION_REFERENCE.md

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):

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