Cloud API Gateway
Relevant source files
The following files were used as context for generating this wiki page:
The Cloud API Gateway provides optional, metadata-focused services that extend the capabilities of the local DJ-Assistant desktop application. It manages authentication, multi-user workspaces, and real-time B2B collaboration while ensuring that raw audio files never leave the local machine.
Sources: README.md:212-218, README.md:253-255
Architecture Overview
The gateway uses a Node.js environment built on the Fastify 5 framework. It connects to a PostgreSQL 16 database utilizing pgvector for similarity searches and integrates with Redis and BullMQ for background task processing. The system serves as a bridge between the local Tauri desktop shell and external cloud-based services.
Sources: README.md:212-230, apps/api/package.json:14-15
Component Stack
| Component | Technology | Description |
|---|---|---|
| Framework | Fastify 5 | High-performance Node.js web framework. |
| Database | PostgreSQL 16 | Primary data store for metadata, auth, and workspaces. |
| Vector Extension | pgvector | Enables similarity-based metadata queries. |
| Task Queue | BullMQ + Redis | Manages asynchronous processing and rate limiting. |
| Language | TypeScript 6 | Ensures type safety across the cloud service. |
Sources: README.md:275-285, apps/api/package.json:1-24
Core Service Modules
The API Gateway exposes several specialized modules that support the preparation pipeline. These services remain strictly additive; the application maintains core functionality offline if the gateway is unreachable.
Sources: README.md:253-255
Authentication and Workspace Management
The gateway handles user identities and separates track metadata into distinct workspaces. This allows DJs to manage different library contexts or collaborate with other users.
Sources: README.md:214-215
LLM Constraint Parser
Natural language intent (e.g., "warm-up set peaking near 128 BPM") is sent to the gateway. A language model parses this into structured constraints which are then returned to the local Beam Search optimizer. The gateway provides the explanation for the resulting sequence, but the final ordering logic remains deterministic and local.
Sources: README.md:205-210, README.md:216
B2B Collaboration
Real-time collaboration allows partners to share set structures and metadata. The gateway facilitates the exchange of these records via HTTPS or WSS. It explicitly does not transfer audio files between machines.
Sources: README.md:217-218
System Interaction Flow
The following diagram illustrates how the Cloud API Gateway interacts with the desktop application and external metadata providers.
The diagram shows the optional connectivity between the local IPC bridge and the Cloud Gateway, emphasizing the metadata-only boundary.
Sources: README.md:212-245
Data Connectivity Logic
Desktop clients interact with the gateway through the services/api.ts layer. While many commands utilize a "Mock API" when the Tauri environment is absent during development, production traffic uses invoke calls that bridge to Rust, which then initiates HTTPS requests to the gateway.
Sources: apps/desktop/src/services/api.ts:25-45
Endpoint Example: Health Check
The API includes basic health monitoring to verify service availability.
// Example of health check integration noted in changelog
// GET /health
Sources: CHANGELOG.md:162-163, apps/api/package.json:9
Implementation Constraints
- No Audio Storage: The gateway never stores or processes raw audio waveforms.
- Optional Sync: Users must explicitly opt-in to cloud sync and external providers.
- Metadata Consistency: The gateway uses shared types from
@dj-assistant/sharedto prevent contract drift between the desktop and cloud environments.
Sources: README.md:218, README.md:254, package.json:15-18
The Cloud API Gateway functions as a supportive infrastructure for advanced features like collaborative prep and AI-assisted constraint parsing, maintaining the project's local-first and privacy-focused principles.
Sources: README.md:126-130