Buddy

AI learning platform built as a production-grade microservices system

Why it stands out · Architecture · Engineering · Run locally · Docs

---

Snapshot

Buddy is a full-stack learning marketplace where creators publish video tutorials and resources, students buy or enroll in content, and an AI assistant answers questions from the actual course material.

It is intentionally built beyond CRUD: the system uses 10 deployable services, event-driven messaging, HLS media processing, payments, recommendations, RAG search, observability, and cloud deployment workflows.

Area	What is implemented
Platform	Course marketplace, creator profiles, library, follows, ratings, reviews, notifications
AI	RAG assistant with Qdrant retrieval, Gemini generation, Redis cache, citations, streaming UI
ML	TensorFlow two-tower recommendation model, FAISS indexing, drift monitoring, retraining triggers
Media	FFmpeg HLS transcoding, trailer extraction, S3 presigned access, Cloudinary thumbnails
Reliability	API gateway with bulkheads, circuit breakers, retries, and partial-failure composition
Money	Wallets, transactions, PayPal, PayOS, ownership records, subscriptions, payouts

Why This Project Stands Out

Recruiter scan:

  distributed systems        10 independently deployable services
  AI product engineering     RAG + recommendation model, not a thin chatbot wrapper
  production thinking        auth, billing, observability, queues, resilience, CI/CD
  frontend depth             ReactJS 19, Next.js 16, shadcn/ui, streaming assistant UX
  data depth                 MongoDB, PostgreSQL, Prisma, Mongoose, Redis, Qdrant
  deployment readiness       Docker Compose locally, Vercel + Azure Container Apps in cloud

Architecture

flowchart TB
  User[Student / Creator] --> Web[Next.js 16 Webapp]
  Web --> Gateway[API Gateway<br/>bulkhead · circuit breaker · retry]

  Gateway --> Auth[Auth Service]
  Gateway --> UserSvc[User Service]
  Gateway --> Content[Content Service]
  Gateway --> Upload[Upload Service]
  Gateway --> Billing[Billing Service]
  Gateway --> Access[Content Access Service]
  Gateway --> Interaction[Interaction Service]
  Gateway --> Notify[Notification Service]
  Gateway --> Recommend[Recommendation Service<br/>FastAPI · ML · RAG]

  Auth --> Postgres[(PostgreSQL)]
  Billing --> Postgres
  Upload --> Postgres
  Access --> Postgres

  UserSvc --> Mongo[(MongoDB)]
  Content --> Mongo
  Interaction --> Mongo
  Notify --> Mongo
  Recommend --> Mongo

  Upload --> S3[Supabase S3]
  Upload --> Cloudinary[Cloudinary]
  Recommend --> Qdrant[(Qdrant)]
  Recommend --> FAISS[(FAISS Index)]

  Auth <--> Rabbit[RabbitMQ Event Bus]
  Content <--> Rabbit
  Billing <--> Rabbit
  Notify <--> Rabbit
  Interaction <--> Rabbit

  Gateway --> Observability[OpenTelemetry<br/>Prometheus · Grafana · Jaeger]

Loading

Engineering Highlights

Resilient Gateway

The API gateway protects downstream services with three defensive layers:

request -> bulkhead -> circuit breaker -> retry for idempotent reads -> service

Pattern	Purpose
Bulkhead	Isolates service concurrency so one slow dependency cannot exhaust the gateway
Circuit breaker	Fails fast after repeated downstream errors, then probes recovery
Retry	Uses exponential backoff for safe GET requests only
API composition	Aggregates multi-service responses with Promise.allSettled() and partial results

AI Study Assistant

course material -> chunking -> embeddings -> Qdrant retrieval -> Gemini generation -> Redis cache -> streamed answer

• Answers are grounded in enrolled tutorials and uploaded resources.
• Retrieval uses semantic embeddings through sentence-transformers.
• Responses include source references back to the original learning material.
• The UI streams markdown responses in real time.

Recommendation Engine

• Two-tower TensorFlow/Keras model separates user and item representations.
• Profile, behavior, and popularity signals are combined for ranking.
• FAISS powers fast nearest-neighbor lookup.
• Drift checks track out-of-vocabulary rates and trigger retraining when needed.

Media Pipeline

• Raw videos are converted to HLS .m3u8 streams with FFmpeg workers.
• Tutorial trailers are extracted automatically from the first 15 seconds.
• Files are served through time-limited Supabase S3 presigned URLs.
• Cloudinary stores public thumbnails and preview assets.

Tech Stack

Layer	Stack
Frontend	ReactJS 19, Next.js 16, TypeScript, Tailwind CSS v4, shadcn/ui, Radix UI, Base UI, Framer Motion, Spline
Client state	Redux Toolkit, React Redux, Redux Persist, Zustand, React Hook Form, Zod
Backend	NestJS 11, Fastify, TypeScript 5.4, CQRS, Clean Architecture, REST APIs
AI / ML	FastAPI, TensorFlow/Keras, Sentence Transformers, Qdrant, FAISS, Gemini, streaming RAG responses
Data	PostgreSQL, MongoDB, Redis, Prisma 7, Mongoose, Prisma Accelerate adapter
Messaging / Jobs	RabbitMQ, BullMQ, event-driven workflows, background media processing
Storage / Media	Supabase S3, Cloudinary, FFmpeg, HLS .m3u8 streaming, presigned URLs
Observability	OpenTelemetry, Prometheus, Grafana, Jaeger, service metrics and traces
Delivery	Docker, Docker Compose, Turborepo, GitHub Actions, Vercel, Azure Container Registry, Azure Container Apps

Service Map

Service	Port	Storage	Responsibility
api-gateway	3000	-	Reverse proxy, resilience, API composition
auth-service	3001	PostgreSQL	Registration, login, JWT, refresh rotation
user-service	3002	MongoDB	Profiles, follows, careers, skills, ratings
notification-service	3003	MongoDB	Socket.io notifications and email events
content-service	3004	MongoDB	Courses, tutorials, resources, collections
upload-service	3005	PostgreSQL	Presigned uploads, HLS transcoding, trailers
billing-service	3006	PostgreSQL	Wallets, payments, subscriptions, payouts
content-access-service	3007	PostgreSQL	Ownership checks and access grants
interaction-service	3008	MongoDB	Views, saves, engagement tracking
recommendation-service	3009	MongoDB + Qdrant	Recommendations, RAG, trending, scoring

Monorepo Shape

buddy/
  services/
    api-gateway/
    auth-service/
    user-service/
    notification-service/
    content-service/
    upload-service/
    billing-service/
    content-access-service/
    interaction-service/
    recommendation-service/
  webapp/
    src/app/
    src/features/
    src/components/
    src/lib/
  libs/
    common/
    contracts/
    testing/
  docs/
  docker-compose.yml
  turbo.json

Run Locally

Prerequisites

• Node.js >=20 <23
• npm >=10
• Docker and Docker Compose
• Python 3.10+

Start the platform

git clone https://github.com/khovan123/buddy.git
cd buddy
npm install

docker-compose up -d
npm run prisma:generate
npm run prisma:db:push
npm run dev

Useful URLs

Surface	URL
Webapp	http://localhost:8000
API Gateway	http://localhost:3000
API Docs	http://localhost:8000/api-docs
Grafana	http://localhost:3100
Prometheus	http://localhost:9090
Jaeger	http://localhost:16686
RabbitMQ Management	http://localhost:15672
Qdrant Dashboard	http://localhost:6333/dashboard

Deployment

GitHub
  -> Vercel for webapp previews and production
  -> GitHub Actions for changed-service Docker builds
  -> Azure Container Registry
  -> Azure Container Apps

The backend workflow uses path-based filtering so only affected services are rebuilt and deployed on production pushes.

Tradeoffs

Strength	Cost
Real distributed architecture	Local setup requires multiple infrastructure services
Event-driven workflows	Debugging requires tracing and message visibility
RAG + recommendations in one product	More moving parts than a standard marketplace
HLS processing pipeline	Video jobs need worker capacity and storage lifecycle management

Documentation

Document	Description
docs/SPEC.md	Technical specification and coding standards
docs/deployment.md	Vercel and Azure deployment guide
docs/api-gateway-architecture.MD	API gateway resilience design
docs/upload-service-architecture.md	Upload and video processing architecture

License

This project is private and not licensed for public distribution.

_{Built by khovan123 · full-stack engineering, AI systems, and production architecture.}