mirror of
https://github.com/blackboxprogramming/BlackStream.git
synced 2026-03-17 04:27:08 -05:00
797fc691f3
Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>
100 lines
3.0 KiB
Markdown
100 lines
3.0 KiB
Markdown
# BlackStream
|
|
|
|
Streaming aggregation platform — a single interface for discovering and tracking content across multiple streaming services.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
frontend/
|
|
web-app/ # React web application (search UI)
|
|
backend/
|
|
api-gateway/ # Express API (port 4000) — search and routing
|
|
recommendation-engine/ # Content recommendations (port 4000 by default)
|
|
content-aggregator/ # Cross-platform catalog aggregation (port 4001)
|
|
sync-service/ # Watch progress synchronization (port 4003)
|
|
user-service/ # Authentication and profiles (port 4002)
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# API Gateway (required for search)
|
|
cd backend/api-gateway && npm install && node index.js
|
|
|
|
# Web App
|
|
cd frontend/web-app && npm install && npm start
|
|
```
|
|
|
|
Each backend service can be started independently:
|
|
|
|
```bash
|
|
cd backend/content-aggregator && npm install && node index.js # port 4001
|
|
cd backend/user-service && npm install && node index.js # port 4002
|
|
cd backend/sync-service && npm install && node index.js # port 4003
|
|
cd backend/recommendation-engine && npm install && node index.js # port 4000
|
|
```
|
|
|
|
## API
|
|
|
|
### API Gateway (port 4000)
|
|
|
|
```
|
|
GET / # Health check
|
|
GET /search?q=<query> # Search content by title, genre, or platform
|
|
GET /search?genre=<genre> # Filter by genre
|
|
GET /search?platform=<platform> # Filter by platform
|
|
```
|
|
|
|
### Content Aggregator (port 4001)
|
|
|
|
```
|
|
GET /catalog # Full streaming catalog with platform/genre lists
|
|
GET /catalog/:id # Single title by ID
|
|
```
|
|
|
|
### User Service (port 4002)
|
|
|
|
```
|
|
POST /register # Create account { username, email, password }
|
|
POST /login # Authenticate { username, password } → token
|
|
GET /profile # Get profile (Authorization: Bearer <token>)
|
|
POST /logout # Invalidate token
|
|
```
|
|
|
|
### Sync Service (port 4003)
|
|
|
|
```
|
|
POST /progress/:userId/:contentId # Save watch progress { progressSeconds, durationSeconds }
|
|
GET /progress/:userId # All progress for a user
|
|
GET /progress/:userId/:contentId # Progress for a specific title
|
|
```
|
|
|
|
### Recommendation Engine (port 4000)
|
|
|
|
```
|
|
GET /recommendations # Personalised content recommendations
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
# API Gateway
|
|
cd backend/api-gateway && npm test
|
|
|
|
# Web App
|
|
cd frontend/web-app && npm test
|
|
```
|
|
|
|
## Status
|
|
|
|
- ✅ **API Gateway** — search endpoint returns real catalog results filtered by title, genre, or platform
|
|
- ✅ **Content Aggregator** — unified catalog API across platforms
|
|
- ✅ **User Service** — register, login, profile, and logout endpoints
|
|
- ✅ **Sync Service** — save and retrieve watch progress per user/title
|
|
- ✅ **React Frontend** — search UI with live results from the API Gateway
|
|
- ⚙️ **Recommendation Engine** — returns curated recommendations (static dataset)
|
|
|
|
## License
|
|
|
|
Copyright 2026 BlackRoad OS, Inc. All rights reserved.
|