StreamMind AI

AI-powered streaming discovery layer built with a scalable architecture.

Features • Architecture • Quick Start • Development • Roadmap

---

What is StreamMind AI?

StreamMind AI is an open-source, extension-first AI-powered movie discovery platform. Users connect their own LLM API key (BYOK — Bring Your Own Key) and receive intelligent, hallucination-free movie recommendations powered by real catalog data from TMDB.

This is NOT another "call ChatGPT and show the result" project.

StreamMind implements:

• Strict LLM output validation with Zod schemas
• Hallucination detection (rejects movies not in the catalog)
• Automatic retry on invalid responses
• Dependency-inverted provider architecture
• Production-grade security practices

---

Features

• 🧠 AI-Powered Recommendations — Natural language → intelligent movie suggestions
• 🔑 BYOK (Bring Your Own Key) — Your API key, your cost, your privacy
• 🎬 Real Catalog Data — Powered by TMDB, not hallucinated movies
• ✅ Hallucination Prevention — Every recommendation is cross-checked against the catalog
• 🔌 Extension-First — Chrome Extension (Manifest V3) as the primary interface
• 🏗 Modular Architecture — Clean separation of concerns, ready for SaaS
• 🌙 Dark Mode UI — Elegant, modern interface inspired by Vercel & Linear
• 🛡 Security-First — API keys never leave your device

---

Architecture

┌──────────────────────────────────────────────────────┐
│                   Chrome Extension                   │
│  React + TypeScript + Tailwind + Manifest V3         │
│                                                      │
│   ┌─────────┐  ┌───────────┐  ┌──────────────┐       │
│   │ Setup   │  │  Search   │  │  Movie Cards │       │
│   │ (BYOK)  │  │   View    │  │  (Results)   │       │
│   └─────────┘  └─────┬─────┘  └──────────────┘       │
└──────────────────────┼───────────────────────────────┘
                       │ HTTP (API Key per-request)
┌──────────────────────┼───────────────────────────────┐
│                Backend API (Fastify)                 │
│                                                      │
│  ┌─────────────────┐  ┌──────────────────────────┐   │
│  │ Recommendation  │  │    Input Sanitization    │   │
│  │    Service      │  │ (Prompt Injection Guard) │   │
│  └────────┬────────┘  └──────────────────────────┘   │
│           │                                          │
│  ┌────────┴────────┐  ┌──────────────────────────┐   │
│  │ LLM Orchestrator│  │      Catalog Service     │   │
│  │(Retry+Validate) │  │      (TMDB Adapter)      │   │
│  └────────┬────────┘  └──────────────────────────┘   │
│           │                                          │
│  ┌────────┴────────────────────────────────────┐     │
│  │         LLM Provider Interface              │     │
│  │  ┌──────────┐ ┌───────────┐ ┌──────────┐    │     │
│  │  │ OpenAI   │ │ Anthropic │ │  Google  │    │     │
│  │  │ Adapter  │ │  (TODO)   │ │  (TODO)  │    │     │
│  │  └──────────┘ └───────────┘ └──────────┘    │     │
│  └─────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────┘

For detailed architecture decisions, see ARCHITECTURE.md.

---

Quick Start

Prerequisites

• Node.js ≥ 18
• pnpm ≥ 8
• TMDB API Key — Get one free
• OpenAI API Key — Get one here

1. Clone & Install

git clone https://github.com/your-username/streammind-ai.git
cd streammind-ai
pnpm install

2. Configure Environment

cp .env.example .env
# Edit .env with your TMDB_API_KEY

3. Build Packages

pnpm build

4. Start Backend

cd apps/api
pnpm dev

5. Load Extension

1. Build the extension: cd apps/extension && pnpm build
2. Open Chrome → chrome://extensions/
3. Enable "Developer mode"
4. Click "Load unpacked" → select apps/extension/dist
5. Click the StreamMind icon in the toolbar
6. Enter your OpenAI API key in the setup screen
7. Start discovering movies!

---

Development

Project Structure

streammind-ai/
├── apps/
│   ├── api/                 # Fastify backend server
│   └── extension/           # Chrome extension (React + Vite)
├── packages/
│   ├── shared-types/        # Zod schemas + TypeScript types
│   ├── llm-adapter/         # LLM orchestration layer
│   ├── catalog-core/        # TMDB integration
│   └── recommendation-core/ # Business logic
├── docs/                    # Additional documentation
└── .github/                 # CI/CD workflows

Commands

Command	Description
pnpm dev	Start all packages in watch mode
pnpm build	Build all packages
pnpm typecheck	Run TypeScript checks
pnpm lint	Lint all packages
pnpm test	Run all tests
pnpm clean	Remove all build artifacts

---

Security

StreamMind AI takes security seriously:

• API keys are stored locally only — encrypted by Chrome's storage API
• Keys are NEVER logged — not in the backend, not in the extension
• Keys are NEVER stored server-side — passed per-request, then discarded
• Input sanitization — protects against prompt injection
• LLM output validation — prevents hallucinated data from reaching the user
• Rate limiting — built into the backend

See ARCHITECTURE.md for detailed security considerations.

---

Roadmap

v0.1 — MVP ✅

• Chrome Extension (Manifest V3)
• BYOK (OpenAI)
• TMDB integration
• Hallucination prevention
• Dark mode UI

v0.2 — Multi-Provider

• Anthropic Claude adapter
• Google Gemini adapter
• Response caching (Redis)
• Improved ranking algorithm

v1.0 — SaaS-Ready

• User taste profiles
• Hybrid recommendation engine
• Vector database for semantic search
• Billing integration
• Multi-region deployment

See ROADMAP.md for the full roadmap.

---

Contributing

We welcome contributions! Please read our Contributing Guide before submitting a PR.

---

License

Copyright © 2026 DaviStarlight. All rights reserved. See LICENSE for details.

---

Built with ❤️ and clean architecture principles.