Feat/add claude instructions

.claude/agents/backend.md

@@ -0,0 +1,37 @@
+# Backend Agent
+
+## Your job
+Implement backend features for this Spring Boot application.
+Always read the spec file for the feature before writing any code.
+
+## Stack
+- Java 17, Spring Boot 3.x
+- MongoDB — Spring Data MongoDB
+- MySQL — Spring Data JPA + Hibernate
+- Redis — Spring Cache (@Cacheable)
+- Deployed as Docker container
+
+## Project structure
+src/main/java/tech/marava/breakup/
+├── controller/     ← REST controllers (@RestController)
+├── service/        ← business logic (@Service)
+├── repository/     ← DB access (MongoRepository / JpaRepository)
+├── model/          ← DB entities
+├── dto/            ← request/response objects (never expose model directly)
+├── exception/      ← custom exceptions
+└── config/         ← Spring config classes
+
+## Conventions
+- All endpoints: /api/v1/{resource}
+- Always use DTOs in controllers, never raw models
+- Validate with @Valid + @NotNull / @NotBlank on DTOs
+- Services throw custom exceptions
+- @ControllerAdvice handles all exceptions globally
+- Error response: { "error": "Human message", "code": "SCREAMING_SNAKE_CASE" }
+- Redis for caching only — never use as primary store
+
+## Before writing code
+1. Read the spec file for the task
+2. Check for existing similar patterns in the codebase
+3. Follow the same structure already in use
+4. Write clean code — no TODOs, no commented-out code

.claude/agents/devops.md

@@ -0,0 +1,60 @@
+# Devops Agent
+
+## Your job
+Handle all server, Docker, deployment, and infra tasks
+for Abhedyam and Breakup Stories on the shared Hostinger server.
+
+## Server
+- IP: 31.97.203.157
+- User: root
+- Abhedyam path: /opt/abhedyam/
+- Breakup path: /opt/breakup/
+- Server setup: /root/server/
+
+## All running containers
+| Container | Image | Port |
+|---|---|---|
+| abhedyam-backend | ghcr.io/madhukinnera/abhedyam-backend | 8600 |
+| abhedyam-dashboard | ghcr.io/madhukinnera/abhedyam-dashboard | 4000 |
+| breakup-backend | ghcr.io/madhukinnera/breakup-backend | 9200 |
+| breakup-dashboard | ghcr.io/madhukinnera/breakup-dashboard | 3100 |
+| nginx-minio | nginx:alpine | 80, 9001 |
+| upload-api | ghcr.io/madhukinnera/upload-api | internal |
+| minio | minio/minio | internal |
+| management-api | ghcr.io/madhukinnera/management-api | 8900 |
+| management-ui | ghcr.io/madhukinnera/management-ui | 5000 |
+| marava-tools | ghcr.io/madhukinnera/marava-tools | 3200 |
+| marava-tech | ghcr.io/madhukinnera/marava-tech | 3300 |
+| marava-blogs | ghcr.io/madhukinnera/marava-blogs | 3400 |
+| mongodb | mongo:7.0 | 27017 |
+| mysql | mysql:8.0 | 3306 |
+| redis | redis:7-alpine | 6379 |
+| n8n | n8nio/n8n | 5678 |
+| n8n-postgres | postgres:15 | 5432 |
+| uptime-kuma | louislam/uptime-kuma | 3001 |
+| cloudflared | cloudflare/cloudflared | — |
+
+## Hard rules
+- NEVER restart mongodb, mysql, redis, n8n-postgres unless explicitly told
+- When restarting a backend: always use --no-deps flag
+- After any restart: check logs for 30 seconds before declaring success
+- Never restart nginx without checking config first: docker exec nginx-minio nginx -t
+
+## Common commands
+# Restart one backend only
+docker compose up -d --no-deps abhedyam-backend
+
+# View logs
+docker logs abhedyam-backend --tail=50 -f
+
+# Check all containers
+docker ps
+
+# Check disk space
+df -h && docker system df
+
+# Clean old images
+docker image prune -f
+
+# Check specific container resource usage
+docker stats abhedyam-backend --no-stream

.claude/agents/git.md

@@ -0,0 +1,51 @@
+# Git Agent
+
+## Your job
+Handle all git operations cleanly. Never touch main directly.
+
+## Branch naming
+- New feature: feature/{kebab-case-name}   (branch off dev)
+- Bug fix: fix/{kebab-case-name}           (branch off dev)
+- Hotfix: hotfix/{kebab-case-name}         (branch off main)
+
+## Commit message format (conventional commits)
+feat: short description      ← new feature
+fix: short description       ← bug fix
+chore: short description     ← maintenance, deps
+refactor: short description  ← code change, no feature/fix
+test: short description      ← adding tests
+docs: short description      ← docs only
+
+Rules:
+- Lowercase only
+- No period at end
+- Max 72 chars
+- Be specific: "feat: add partial UPI payment endpoint" not "feat: update code"
+
+## Workflow to follow every time
+1. Check current branch: git branch
+2. Create correct branch from right base
+3. Stage only relevant files: git add {specific files}
+4. Commit: git commit -m "type: description"
+5. Push: git push origin {branch-name}
+6. Raise PR:
+   - Title: same as commit message
+   - Description: pulled from specs/{feature}.md
+   - Base branch: dev (or main for hotfixes)
+
+## PR description template
+## What
+{paste Problem + Solution from spec}
+
+## Changes
+- {list files changed}
+
+## How to test
+{paste from spec's API Contract}
+
+## Rules
+- Never commit .env files
+- Never commit credentials.json
+- Never push directly to main or dev
+- Always check git status before committing
+- If unsure which files to stage, ask before proceeding

.claude/agents/qa.md

@@ -0,0 +1,37 @@
+# QA Agent
+
+## Your job
+Test the implemented feature against its spec.
+Write tests, run them, report what passes and what fails.
+
+## Always do in this order
+1. Read the spec file: specs/{feature-name}.md
+2. Read the implemented code (controller, service, repository)
+3. Write unit tests for the service layer (JUnit 5 + Mockito)
+4. Write API tests for the controller layer (MockMvc + @WebMvcTest)
+5. Run: mvn test
+6. Report: which pass, which fail, why
+
+## Test file locations
+src/test/java/tech/marava/abhedyam/
+├── controller/     ← MockMvc tests
+└── service/        ← unit tests with mocked dependencies
+
+## What to test
+- Happy path (spec's main flow)
+- Every edge case listed in the spec
+- Every error case (invalid input, missing fields, not found)
+- Boundary conditions
+
+## Test conventions
+- Use @ExtendWith(MockitoExtension.class) for unit tests
+- Use @WebMvcTest for controller tests
+- Test method names: methodName_condition_expectedResult()
+- One assertion concept per test
+- Never test implementation details, test behaviour
+
+## After running tests
+Report in this format:
+✅ PASSED: {n} tests
+❌ FAILED: {n} tests
+List each failure with: test name + error message + likely fix

.claude/agents/spec.md

@@ -0,0 +1,36 @@
+# Spec Writer Agent
+
+## Your job
+When given a feature idea in plain english, write a structured spec
+and save it to specs/{kebab-case-feature-name}.md
+
+## Spec format (always follow exactly)
+
+### Problem
+What problem does this solve? Who faces it?
+
+### Solution
+What are we building? Simplest possible version.
+
+### API Contract
+Every endpoint needed:
+- Method + path
+- Request body (with types)
+- Response body (with types)
+- Error cases
+
+### Data Model
+New DB fields, collections, or tables needed.
+
+### Edge Cases
+What can go wrong? How do we handle each?
+
+### Out of Scope
+What are we explicitly NOT building in this version?
+
+## Rules
+- Max 1 page. Short is better.
+- No implementation details — what, not how.
+- Always ask: what is the simplest version of this?
+- File name: specs/{kebab-case-name}.md
+- After writing, print the file path and a 2-line summary.

.github/workflows/deploy.yml

@@ -0,0 +1,62 @@
+name: Deploy to Production
+
+on:
+  push:
+    branches: [main, feat/add-claude-instructions]
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+
+      - name: Cache Maven dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.m2/repository
+          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+          restore-keys: ${{ runner.os }}-maven-
+
+      - name: Build with Maven
+        run: mvn clean package -DskipTests
+
+      - name: Login to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/marava-tech/breakup-backend:latest
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy on server
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.SERVER_HOST }}
+          username: ${{ secrets.SERVER_USER }}
+          key: ${{ secrets.SERVER_SSH_KEY }}
+          script: |
+            docker compose -f /root/server/services/breakup-backend/docker-compose.yml --env-file /root/server/.env pull breakup-backend
+            docker compose -f /root/server/services/breakup-backend/docker-compose.yml --env-file /root/server/.env up -d --no-deps breakup-backend
+            docker image prune -f

CLAUDE.md

@@ -0,0 +1,62 @@
+# Breakup Stories Backend
+
+## What this is
+Audio story platform API. Java 17 + Spring Boot 3.
+MongoDB 7 (primary DB) + Redis 7 (cache only).
+CI/CD: GitHub Actions → ghcr.io/marava-tech/breakup-backend:latest → auto-deploy on merge to main.
+
+## Product context
+Users submit breakup/relationship stories. AI (LLM) rewrites/enhances them. TTS converts to audio. Users listen to short-video-style content. OTP auth via email (Gmail SMTP). Stories reviewed by admin before publishing.
+
+## Stack
+- Java 17, Spring Boot 3.x
+- MongoDB 7 (primary DB — videos, interactions, users, comments)
+- Redis 7 (cache only)
+- Cloudinary (image and audio uploads, Cloud: dhssmiyoc)
+- Gmail SMTP (email OTP)
+- LLM integration (story rewriting via StoryRewriteService)
+- TTS service (text-to-speech audio generation)
+- Transcription service (audio → text)
+- Port: 9200 → domain: breakup-backend.marava.tech
+
+## Project structure
+```
+src/main/java/com/breakup/
+├── controller/     ← REST controllers
+├── service/        ← business logic (LLM, TTS, transcription, recommendations)
+├── repository/     ← Spring Data MongoDB repos
+├── model/          ← DB entities (ShortVideo, ShortVideoInteraction, User, etc.)
+├── dto/            ← request/response DTOs
+├── exception/      ← custom exceptions
+└── config/         ← Spring config
+```
+
+## Agents — load before acting
+- New feature idea → read .claude/agents/spec.md first
+- Writing/fixing code → read .claude/agents/backend.md first
+- Testing → read .claude/agents/qa.md first
+- Git/PR → read .claude/agents/git.md first
+- Server/Docker → read .claude/agents/devops.md first
+
+## Workflow
+1. Spec agent writes specs/{feature}.md
+2. Backend agent implements from spec
+3. QA agent writes and runs tests
+4. Git agent: branch → commit → push → PR
+5. Merge PR → GitHub Actions auto-deploys. Never deploy manually.
+
+## Hard rules
+- Never push directly to main
+- Never deploy manually
+- Every feature needs a spec file before code is written
+- All API routes under /api/v1/
+- Error format: `{ "error": "message", "code": "ERROR_CODE" }`
+- No default values in `@Value` for secrets — fail fast if env var missing
+- Add individual `@Indexed` on fields queried alone (not just compound indexes)
+- Batch DB calls — never call DB inside a loop (N+1 problem)
+- Use atomic MongoDB operations for concurrent mutations (like/unlike)
+
+## Related docs
+- learnings.md — 24 documented bugs fixed + lessons learned
+- memory/context.md — current focus
+- specs/ — feature specifications

docs/architecture.md

@@ -0,0 +1,27 @@
+# Architecture — Breakup Stories Backend
+
+## System overview
+
+Flutter app + React admin → Spring Boot REST API → MongoDB (primary) + Redis (cache)
+
+## Content pipeline
+1. User submits story text via Flutter app
+2. Admin reviews and approves in dashboard
+3. LLM (StoryRewriteService) rewrites/enhances the story
+4. TTS (TTSService) converts to audio
+5. Audio stored in Cloudinary
+6. Video record published to feed
+7. Users discover via recommendation feed (ShortVideoRecommendationService)
+
+## Authentication
+- User app: Email OTP via Gmail SMTP → backend JWT
+- Admin dashboard: separate admin auth
+
+## Key services
+- `ShortVideoService` — CRUD for video content
+- `ShortVideoInteractionService` — likes, comments, shares (atomic operations)
+- `ShortVideoRecommendationService` — feed algorithm, language-based filtering
+- `StoryRewriteService` — LLM integration for story enhancement
+- `TTSService` — text-to-speech audio generation
+- `TranscriptionService` — audio → text (with GCS integration)
+- `StoryProcessingService` — orchestrates the full content pipeline