---

# Media Orchestration Stack

## Overview
This repository presents a **self-hosted media orchestration stack** designed for portfolio and demonstration purposes.  
It highlights **API-first architecture, containerization, and client integration** practices using Docker Compose and Node.js.

The stack aggregates **distributed, user-owned libraries**, organizes them, and exposes them to client applications (e.g., Infuse, Kodi) via standard protocols like HTTP/WebDAV and a lightweight Jellyfin-compatible API shim.  
All design decisions emphasize **clean engineering patterns, secure credential handling, and professional documentation**.

---

## ASCII Architecture

Client (Infuse/Kodi) │ ▼ Faux-Jellyfin API (Node/Express) │ ├── search ──▶ Jackett (Torznab) │ ├── resolve/stream ──▶ lawful cache provider (HTTPS) │ └── library organization ──▶ Zurg (HTTP/WebDAV)

This flow enables client applications to browse/search a library, check cache availability, and stream content via secure HTTPS endpoints.

---

## Tech Stack

- **Docker Compose** for orchestration  
- **Node.js / Express** for API shim  
- **Jackett (Torznab)** for search endpoints  
- **Lawful caching provider API** (abstracted, env-driven)  
- **Zurg** for library organization and WebDAV exposure  

---

## Key Features

- API-first compatibility layer (“FauxJellyfin”)  
- Search → Resolve → Play pipeline with **cached-only results**  
- Organized library structure for Movies/TV  
- Containerized services with `.env`-driven secrets  
- Windows-friendly setup and paths  

---

## Setup (Local / Development)

1. Install prerequisites:
   - Docker Desktop (with WSL2 enabled if on Windows)
   - Node.js 20+
   - Jackett running locally (`http://localhost:9117`)

2. Copy `.env.example` → `.env`, then fill in values:
   ```bash
   JACKETT_API_KEY=your_key_here
   CACHE_API_TOKEN=your_cache_token_here

3. Start the stack:

   docker compose up -d

4. Connect Infuse (or other client):

   • Add server: http://<YOUR_PC_IP>:8096
   • Use any credentials (authentication shim is static)

---

Professional Value

This project demonstrates:

• Designing and documenting an end-to-end architecture
• Building an API layer with Node.js and Express
• Secure handling of credentials with environment variables
• Using Docker Compose to orchestrate multiple services
• Troubleshooting client/server compatibility

---

Security & Ethics

• Secrets are never committed; use .env for sensitive keys
• For remote access, enable TLS, reverse proxy, and IP allowlists
• Role-based access should be applied if exposed outside localhost
• This project demonstrates engineering patterns only — no instructions or references to questionable sources are provided

---

Next Steps

• Harden remote access (VPN or reverse proxy)
• Add monitoring/log shipping (Grafana/Promtail stack)
• Extend FauxJellyfin API to handle richer metadata
• Optional: add request UI and CI/CD checks

---

Contributing

Contributions welcome! Please follow Conventional Commits and check CONTRIBUTING.md for details.

---

⚡ To apply this:  
1. Replace your current `README.md` with the content above.  
2. Commit + push:  
   ```powershell
   git add README.md
   git commit -m "docs: polish README with architecture and security sections"
   git push origin <branch-name>