Dibas Kumar Borborah

Full Stack Engineer | AI/ML Enthusiast

🎬 Plex-Deeper: AI-Powered Media Description Generator

Demo working preview

Welcome to Plex-Deeper — a full-stack, agent-driven platform that creates rich media descriptions (short, detailed, images & sources) in near-realtime while off-loading heavy LLM workloads to background workers.

👉 Built with Next.js 15 (App Router) on the frontend and a Mastra-orchestrated AI backend, Plex-Deeper keeps the developer experience local-first (Redis + Postgres) while remaining cloud-ready for Vercel, Fly.io & Neon.

🔗 Project Links

🚀 How to Use Query X Extension

To get the full experience of Query X, you'll need to install the Chrome extension that scrapes page content and metadata. Here's how to set it up:

Step 1: Clone and Install Extension

# Clone the extension repository
git clone https://github.com/dibkb/query-x-extension

# Navigate to the extension directory and install dependencies
cd query-x-extension && pnpm install

Step 2: Build the Extension

# Build the extension to create the dist folder
pnpm run build

Step 3: Load Extension in Chrome

  1. Open Chrome and navigate to chrome://extensions/
  2. Enable "Developer mode" (toggle in top right corner)
  3. Click "Load unpacked" and select the dist folder from the extension directory

Step 4: Get Extension ID

  1. After loading the extension, you'll see it listed on the chrome://extensions/ page
  2. Look for the Extension ID under your Query X extension (it will look like: lmahehkeleeobdljhkilajlgebegemfl)
  3. Copy this ID - you'll need it for the next step

Step 5: Configure Extension ID in Query X

  1. Go to the Query X live application
  2. You'll see an extension setup section where you can enter your Extension ID
  3. Paste the Extension ID you copied in Step 4
  4. Click "Save ID" to configure the connection

Step 6: Start Using Query X

Once configured, the extension will automatically:

  • Scrape page content and metadata when you visit websites
  • Send this data to Query X for AI-powered analysis
  • Generate rich descriptions with sources and images

The extension works seamlessly in the background - just browse normally and Query X will process the content!

⚡ Tech Stack Overview

  • Client/UI → Next.js 15, React 19, Server Components, Tailwind v4, shadcn/ui, next-themes, React-Query
  • API Runtime → Next.js Edge/Server, REST-style API Routes (/app/api/**)
  • Queue & Messaging → Bee-Queue + Redis
  • Database / ORM → Postgres (local → Neon), Drizzle ORM + drizzle-kit migrations
  • AI Orchestration → Mastra agents & workflows, @mastra/memory
  • Workers → Stand-alone Node processes

🏗️ High-Level Architecture

🛠️ Request Lifecycle (Example)

  1. User types text → useDebounce fires → React-Query mutation hits /api/query.
  2. API Route
    • Stores a row in queries table (status = "pending").
    • Enqueues a short-description job in Redis.
  3. Worker (workers/short-description.ts)
    • Pops job → runs Mastra workflow.
    • Persists LLM output → updates DB row to completed.
  4. Client polls (soon WebSocket) until status==completed → updates UI in near-realtime.

🧩 Major Sub-Systems

1. Client / UI

  • Next.js 15 App Router with Server Components.
  • Tailwind v4 & shadcn/ui for design-system primitives.
  • Dark / light mode via next-themes.
  • React-Query handles caching & background-refetch.
  • Chrome Extension Scraper (query-x-extension) runs in the user's browser, scrapes page metadata/content and posts it to /api/scrape for downstream processing.

2. API Layer

  • REST-like routes under /app/api/**.
  • Light CRUD with Drizzle ORM.
  • Job enqueue logic lives in lib/queue.ts.

3. Queue & Messaging

  • Bee-Queue atop Redis.
  • Separate queues: short-description, detailed-description, image-generation, etc.
  • Guarantees at-least-once delivery; workers ensure idempotency.

4. Background Workers

  • Written in TypeScript, executed with tsx.
  • Each worker listens to a single queue & invokes Mastra workflows.

5. AI Orchestration (Mastra)

  • Agents (src/mastra/agents/**) for focused tasks (Google Search, auto-complete).
  • Workflows (src/mastra/workflows/**) coordinate multi-step reasoning with Zod schema validation.
  • Conversation memory powered by @mastra/memory backed by Postgres.

6. Database Layer

  • Postgres (local Docker or Neon Serverless).
  • Strict typing via Drizzle.
  • Migrations under /migrations/*.
# Required ENV Vars
DATABASE_URL=postgres://...
REDIS_HOST=...
REDIS_PORT=6379
OPENAI_API_KEY=sk-...
MASTRA_API_KEY=...

🔮 Roadmap

  • Replace polling with WebSockets / SSE.
  • Redis cache layer for repeat LLM prompts.
  • OpenTelemetry tracing around Mastra calls.
  • Feature flags via Unleash.
  • Helm charts for Kubernetes-native deploys.

📂 Folder Cheat-Sheet

app/            Next.js pages, components, API routes
workers/        Stand-alone job processors
src/mastra/     Agents, workflows, models
lib/            Helpers (queue, redis, utils)
hooks/          React hooks
migrations/     DB schema evolution
components/ui   Design-system primitives

🚀 Run Locally

# 1. Clone & install deps
pnpm i

# 2. Start Postgres & Redis (Docker-Compose)
docker compose up -d postgres redis

# 3. Run migrations
drzl push

# 4. Launch everything
pnpm dev      # Next.js frontend & API
pnpm worker   # Background workers (tsx node)

Enjoy building with Plex-Deeper and feel free to contribute! 🎉