Add scripts to run application in developement mode

[yb175]

📋 Product Requirements Document (PRD)

1. Overview

Feature: Development Mode Scripts for PullShark AI
Priority: High
Status: Open
Owner: TBD

---

2. Problem Statement

Currently, PullShark AI can only be run using Docker Compose, which has several limitations for active development:

• Slow Iteration: Developers must rebuild Docker images for every code change, adding friction to the development cycle
• Resource Intensive: Running full Docker containers consumes more system resources than necessary during development
• Debugging Difficulty: Attaching debuggers and inspectors to containerized processes is more complex
• Hot Reload Absence: Changes to code require container restarts rather than instant hot module replacement
• Developer Onboarding: New contributors face a steeper learning curve when Docker is the only option

---

3. Goals & Success Metrics

Goals

1. Enable developers to run the application locally without Docker
2. Provide hot-reload capabilities for both frontend and backend
3. Simplify debugging with direct access to Node.js processes
4. Reduce development startup time from minutes to seconds
5. Maintain parity with production environment configuration

Success Metrics

• Development environment starts in < 30 seconds
• Code changes reflect in < 3 seconds (hot reload)
• 100% feature parity between Docker and local development modes
• Zero configuration required for developers after initial setup

---

4. User Stories

As a backend developer,
I want to run the Express server locally with auto-restart on file changes,
So that I can iterate quickly without rebuilding Docker images.

As a frontend developer,
I want to run the Vite dev server with hot module replacement,
So that I can see my UI changes instantly in the browser.

As a full-stack developer,
I want to run both frontend and backend concurrently with a single command,
So that I can develop features that span the entire stack efficiently.

As a new contributor,
I want clear documentation on setting up the local development environment,
So that I can start contributing code within 15 minutes.

---

5. Technical Scope

5.1 Backend Development Scripts

Technology Stack:

• Node.js with TypeScript
• Express.js server
• Prisma ORM (PostgreSQL adapter)
• BullMQ + Redis for job queues
• MongoDB (Mongoose)

Required Scripts:

• npm run dev - Start backend server with hot-reload using tsx/nodemon
• npm run worker:dev - Start BullMQ worker with auto-restart
• npm run db:migrate - Run Prisma migrations
• npm run db:seed - Seed database with test data
• npm run db:studio - Open Prisma Studio for database inspection

Dependencies to Add:

• nodemon or tsx --watch for auto-restart
• concurrently for running multiple processes

---

5.2 Frontend Development Scripts

Technology Stack:

• React 19
• Vite build tool
• Redux Toolkit for state management
• Tailwind CSS

Existing Scripts (Already Available):

• npm run dev - Vite dev server with HMR ✅
• npm run build - Production build ✅
• npm run preview - Preview production build ✅

Status: Frontend scripts are already configured properly.

---

5.3 Root-Level Development Scripts

Required Scripts (in root package.json):

• npm run dev - Start both frontend and backend concurrently
• npm run dev:backend - Start only backend services
• npm run dev:frontend - Start only frontend
• npm run dev:worker - Start only the analysis worker
• npm run setup - Install all dependencies and initialize databases

Implementation:
Create a root-level package.json with workspace configuration or use concurrently to orchestrate services.

---

6. Environment Configuration

6.1 Prerequisites Documentation

Create a DEVELOPMENT.md file documenting:

• Required software versions:
  • Node.js (v18+)
  • Redis (v7+)
  • PostgreSQL (v14+)
  • MongoDB (v6+)
• Installation instructions for each platform (macOS, Linux, Windows)
• Environment variable setup guide

6.2 Environment Files

• Provide .env.example files for both backend and root
• Document all required environment variables
• Include sensible defaults for local development

---

7. Database Setup

7.1 PostgreSQL (Prisma)

• Scripts to create local database
• Automatic migration on first run
• Seed script with sample data

7.2 MongoDB

• Connection string configuration
• Optional: Local MongoDB setup guide or MongoDB Atlas free tier

7.3 Redis

• Local Redis server or Redis Cloud free tier
• Connection configuration
• Health check before starting services

---

8. Implementation Plan

Phase 1: Backend Scripts (Priority: High)

• Add tsx or nodemon to backend devDependencies
• Create backend/package.json scripts:
  • dev: Start server with hot-reload
  • worker:dev: Start worker with hot-reload
  • db:migrate: Run Prisma migrations
  • db:seed: Seed database
• Test each script individually

Phase 2: Root-Level Orchestration (Priority: High)

• Create root package.json with workspaces
• Add concurrently dependency
• Create orchestration scripts:
  • dev: Run frontend + backend + worker
  • dev:backend: Backend only
  • dev:frontend: Frontend only
• Test concurrent execution

Phase 3: Documentation (Priority: Medium)

• Create DEVELOPMENT.md with:
  • Prerequisites installation
  • Environment setup
  • Database initialization
  • Running in development mode
  • Troubleshooting guide
• Update main README.md with development section
• Add .env.example files

Phase 4: Developer Experience Enhancements (Priority: Low)

• Add health check scripts
• Create setup automation script
• Add VS Code launch configurations
• Add debugging documentation

---

9. Acceptance Criteria

✅ Must Have:

• Backend runs locally with npm run dev and auto-restarts on file changes
• Frontend runs locally with npm run dev with HMR
• Worker runs locally with npm run worker:dev
• Single command (npm run dev from root) starts entire stack
• DEVELOPMENT.md clearly documents setup process
• All environment variables documented in .env.example

🎯 Should Have:

• Database migration scripts included
• Seed data available for testing
• Health check before starting services
• Clear error messages when prerequisites are missing

🌟 Nice to Have:

• Automated setup script that installs dependencies
• VS Code debugging configuration
• Git hooks for pre-commit checks

---

10. Technical Considerations

10.1 Port Configuration

• Backend: 3000 (configurable via env)
• Frontend: 5173 (Vite default, configurable)
• Worker: No port (background process)

10.2 Cross-Platform Compatibility

• Scripts must work on macOS, Linux, and Windows
• Use cross-platform tools (cross-env, concurrently)
• Document platform-specific quirks

10.3 Backward Compatibility

• Docker Compose workflow must remain fully functional
• No breaking changes to existing environment variables
• CI/CD pipelines should not be affected

---

11. Risks & Mitigations

Risk	Impact	Mitigation
Database connection issues	High	Add connection health checks and clear error messages
Redis not running locally	High	Document Redis installation; provide fallback queue mechanism
Port conflicts	Medium	Make all ports configurable via environment variables
Platform-specific issues	Medium	Test on macOS, Linux, Windows; document known issues
Dependency version mismatches	Low	Lock versions in package.json; provide version checks

---

12. Out of Scope

The following are explicitly NOT part of this feature:

• ❌ Replacing Docker Compose for production deployments
• ❌ Creating a GUI for managing development environment
• ❌ Auto-installation of system dependencies (PostgreSQL, Redis, etc.)
• ❌ Integration with other IDEs beyond VS Code
• ❌ Performance optimizations for Docker-based development

---

13. References

• Backend README
• Frontend README
• Docker Compose Configuration
• Backend package.json (Express + Prisma + BullMQ stack)
• Frontend package.json (React + Vite stack)

---

14. Timeline

Estimated Effort: 8-12 hours
Proposed Timeline:

• Phase 1 (Backend Scripts): 3-4 hours
• Phase 2 (Root Orchestration): 2-3 hours
• Phase 3 (Documentation): 2-3 hours
• Phase 4 (Enhancements): 1-2 hours

Target Completion: Within 1 sprint

---

15. Questions & Decisions Needed

• Should we use tsx --watch or nodemon for backend hot-reload?
• Do we need a local setup script or just documentation?
• Should Redis and PostgreSQL be run via Docker or installed locally?
• What seed data should be included for development?

---

Created by: @yb175
Last Updated: 2026-02-26

[yb175]

@coderabbitai please make a prd of the issue and add it in description

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch details of issue `#43`
gh issue view 43 --json number,title,body,author,labels,assignees,state

Length of output: 209

---

🏁 Script executed:

#!/bin/bash
# Check repository structure to understand the application type
ls -la

# Check if there's a package.json (Node.js project)
if [ -f "package.json" ]; then
  echo "=== package.json found ==="
  cat package.json
fi

# Check if there's a requirements.txt or pyproject.toml (Python project)
if [ -f "requirements.txt" ]; then
  echo "=== requirements.txt found ==="
  cat requirements.txt
fi

if [ -f "pyproject.toml" ]; then
  echo "=== pyproject.toml found ==="
  cat pyproject.toml
fi

# Check README for context
if [ -f "README.md" ]; then
  echo "=== README.md found ==="
  cat README.md
fi

# Check for docker-compose or Dockerfile
if [ -f "docker-compose.yml" ]; then
  echo "=== docker-compose.yml found ==="
  cat docker-compose.yml
fi

if [ -f "Dockerfile" ]; then
  echo "=== Dockerfile found ==="
  cat Dockerfile
fi

Length of output: 3971

---

🏁 Script executed:

#!/bin/bash
# Check backend structure and technology
echo "=== Backend Structure ==="
ls -la backend/

# Check if backend has package.json or requirements.txt
if [ -f "backend/package.json" ]; then
  echo "=== Backend package.json ==="
  cat backend/package.json
fi

if [ -f "backend/requirements.txt" ]; then
  echo "=== Backend requirements.txt ==="
  head -20 backend/requirements.txt
fi

if [ -f "backend/pyproject.toml" ]; then
  echo "=== Backend pyproject.toml ==="
  cat backend/pyproject.toml
fi

# Check frontend structure and technology
echo "=== Frontend Structure ==="
ls -la frontend/

if [ -f "frontend/package.json" ]; then
  echo "=== Frontend package.json ==="
  cat frontend/package.json
fi

# Check docker-compose.yaml for more details
echo "=== Docker Compose Configuration ==="
cat docker-compose.yaml

Length of output: 4290

---

🏁 Script executed:

#!/bin/bash
# Update issue `#43` with the PRD
gh issue edit 43 --body "## 📋 Product Requirements Document (PRD)

### 1. Overview
**Feature:** Development Mode Scripts for PullShark AI  
**Priority:** High  
**Status:** Open  
**Owner:** TBD

---

### 2. Problem Statement

Currently, PullShark AI can only be run using Docker Compose, which has several limitations for active development:

- **Slow Iteration:** Developers must rebuild Docker images for every code change, adding friction to the development cycle
- **Resource Intensive:** Running full Docker containers consumes more system resources than necessary during development
- **Debugging Difficulty:** Attaching debuggers and inspectors to containerized processes is more complex
- **Hot Reload Absence:** Changes to code require container restarts rather than instant hot module replacement
- **Developer Onboarding:** New contributors face a steeper learning curve when Docker is the only option

---

### 3. Goals & Success Metrics

#### Goals
1. Enable developers to run the application locally without Docker
2. Provide hot-reload capabilities for both frontend and backend
3. Simplify debugging with direct access to Node.js processes
4. Reduce development startup time from minutes to seconds
5. Maintain parity with production environment configuration

#### Success Metrics
- Development environment starts in < 30 seconds
- Code changes reflect in < 3 seconds (hot reload)
- 100% feature parity between Docker and local development modes
- Zero configuration required for developers after initial setup

---

### 4. User Stories

**As a backend developer,**  
I want to run the Express server locally with auto-restart on file changes,  
So that I can iterate quickly without rebuilding Docker images.

**As a frontend developer,**  
I want to run the Vite dev server with hot module replacement,  
So that I can see my UI changes instantly in the browser.

**As a full-stack developer,**  
I want to run both frontend and backend concurrently with a single command,  
So that I can develop features that span the entire stack efficiently.

**As a new contributor,**  
I want clear documentation on setting up the local development environment,  
So that I can start contributing code within 15 minutes.

---

### 5. Technical Scope

#### 5.1 Backend Development Scripts

**Technology Stack:**
- Node.js with TypeScript
- Express.js server
- Prisma ORM (PostgreSQL adapter)
- BullMQ + Redis for job queues
- MongoDB (Mongoose)

**Required Scripts:**
- \`npm run dev\` - Start backend server with hot-reload using tsx/nodemon
- \`npm run worker:dev\` - Start BullMQ worker with auto-restart
- \`npm run db:migrate\` - Run Prisma migrations
- \`npm run db:seed\` - Seed database with test data
- \`npm run db:studio\` - Open Prisma Studio for database inspection

**Dependencies to Add:**
- \`nodemon\` or \`tsx --watch\` for auto-restart
- \`concurrently\` for running multiple processes

---

#### 5.2 Frontend Development Scripts

**Technology Stack:**
- React 19
- Vite build tool
- Redux Toolkit for state management
- Tailwind CSS

**Existing Scripts (Already Available):**
- \`npm run dev\` - Vite dev server with HMR ✅
- \`npm run build\` - Production build ✅
- \`npm run preview\` - Preview production build ✅

**Status:** Frontend scripts are already configured properly.

---

#### 5.3 Root-Level Development Scripts

**Required Scripts (in root package.json):**
- \`npm run dev\` - Start both frontend and backend concurrently
- \`npm run dev:backend\` - Start only backend services
- \`npm run dev:frontend\` - Start only frontend
- \`npm run dev:worker\` - Start only the analysis worker
- \`npm run setup\` - Install all dependencies and initialize databases

**Implementation:**
Create a root-level \`package.json\` with workspace configuration or use \`concurrently\` to orchestrate services.

---

### 6. Environment Configuration

#### 6.1 Prerequisites Documentation
Create a \`DEVELOPMENT.md\` file documenting:
- Required software versions:
  - Node.js (v18+)
  - Redis (v7+)
  - PostgreSQL (v14+)
  - MongoDB (v6+)
- Installation instructions for each platform (macOS, Linux, Windows)
- Environment variable setup guide

#### 6.2 Environment Files
- Provide \`.env.example\` files for both backend and root
- Document all required environment variables
- Include sensible defaults for local development

---

### 7. Database Setup

#### 7.1 PostgreSQL (Prisma)
- Scripts to create local database
- Automatic migration on first run
- Seed script with sample data

#### 7.2 MongoDB
- Connection string configuration
- Optional: Local MongoDB setup guide or MongoDB Atlas free tier

#### 7.3 Redis
- Local Redis server or Redis Cloud free tier
- Connection configuration
- Health check before starting services

---

### 8. Implementation Plan

#### Phase 1: Backend Scripts (Priority: High)
- [ ] Add \`tsx\` or \`nodemon\` to backend devDependencies
- [ ] Create \`backend/package.json\` scripts:
  - \`dev\`: Start server with hot-reload
  - \`worker:dev\`: Start worker with hot-reload
  - \`db:migrate\`: Run Prisma migrations
  - \`db:seed\`: Seed database
- [ ] Test each script individually

#### Phase 2: Root-Level Orchestration (Priority: High)
- [ ] Create root \`package.json\` with workspaces
- [ ] Add \`concurrently\` dependency
- [ ] Create orchestration scripts:
  - \`dev\`: Run frontend + backend + worker
  - \`dev:backend\`: Backend only
  - \`dev:frontend\`: Frontend only
- [ ] Test concurrent execution

#### Phase 3: Documentation (Priority: Medium)
- [ ] Create \`DEVELOPMENT.md\` with:
  - Prerequisites installation
  - Environment setup
  - Database initialization
  - Running in development mode
  - Troubleshooting guide
- [ ] Update main \`README.md\` with development section
- [ ] Add \`.env.example\` files

#### Phase 4: Developer Experience Enhancements (Priority: Low)
- [ ] Add health check scripts
- [ ] Create setup automation script
- [ ] Add VS Code launch configurations
- [ ] Add debugging documentation

---

### 9. Acceptance Criteria

✅ **Must Have:**
- [ ] Backend runs locally with \`npm run dev\` and auto-restarts on file changes
- [ ] Frontend runs locally with \`npm run dev\` with HMR
- [ ] Worker runs locally with \`npm run worker:dev\`
- [ ] Single command (\`npm run dev\` from root) starts entire stack
- [ ] \`DEVELOPMENT.md\` clearly documents setup process
- [ ] All environment variables documented in \`.env.example\`

🎯 **Should Have:**
- [ ] Database migration scripts included
- [ ] Seed data available for testing
- [ ] Health check before starting services
- [ ] Clear error messages when prerequisites are missing

🌟 **Nice to Have:**
- [ ] Automated setup script that installs dependencies
- [ ] VS Code debugging configuration
- [ ] Git hooks for pre-commit checks

---

### 10. Technical Considerations

#### 10.1 Port Configuration
- Backend: \`3000\` (configurable via env)
- Frontend: \`5173\` (Vite default, configurable)
- Worker: No port (background process)

#### 10.2 Cross-Platform Compatibility
- Scripts must work on macOS, Linux, and Windows
- Use cross-platform tools (\`cross-env\`, \`concurrently\`)
- Document platform-specific quirks

#### 10.3 Backward Compatibility
- Docker Compose workflow must remain fully functional
- No breaking changes to existing environment variables
- CI/CD pipelines should not be affected

---

### 11. Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Database connection issues | High | Add connection health checks and clear error messages |
| Redis not running locally | High | Document Redis installation; provide fallback queue mechanism |
| Port conflicts | Medium | Make all ports configurable via environment variables |
| Platform-specific issues | Medium | Test on macOS, Linux, Windows; document known issues |
| Dependency version mismatches | Low | Lock versions in package.json; provide version checks |

---

### 12. Out of Scope

The following are explicitly **NOT** part of this feature:
- ❌ Replacing Docker Compose for production deployments
- ❌ Creating a GUI for managing development environment
- ❌ Auto-installation of system dependencies (PostgreSQL, Redis, etc.)
- ❌ Integration with other IDEs beyond VS Code
- ❌ Performance optimizations for Docker-based development

---

### 13. References

- [Backend README](./backend/readme.md)
- [Frontend README](./frontend/README.md)
- [Docker Compose Configuration](./docker-compose.yaml)
- Backend package.json (Express + Prisma + BullMQ stack)
- Frontend package.json (React + Vite stack)

---

### 14. Timeline

**Estimated Effort:** 8-12 hours  
**Proposed Timeline:**
- Phase 1 (Backend Scripts): 3-4 hours
- Phase 2 (Root Orchestration): 2-3 hours
- Phase 3 (Documentation): 2-3 hours
- Phase 4 (Enhancements): 1-2 hours

**Target Completion:** Within 1 sprint

---

### 15. Questions & Decisions Needed

- [ ] Should we use \`tsx --watch\` or \`nodemon\` for backend hot-reload?
- [ ] Do we need a local setup script or just documentation?
- [ ] Should Redis and PostgreSQL be run via Docker or installed locally?
- [ ] What seed data should be included for development?

---

**Created by:** `@yb175`  
**Last Updated:** $(date +%Y-%m-%d)"

Length of output: 44

---

@yb175 I've successfully created a comprehensive PRD and added it to the description of issue #43!

📋 PRD Summary

The PRD covers the implementation of development mode scripts for running PullShark AI locally without Docker. Here's what's included:

Key Sections:

• Problem Statement: Addresses slow iteration, resource intensity, and debugging difficulties with Docker-only development
• Goals & Success Metrics: < 30s startup time, < 3s hot reload, 100% feature parity
• Technical Scope:
  • Backend scripts (Node.js/Express with hot-reload)
  • Frontend scripts (already configured with Vite)
  • Root-level orchestration with concurrently
• Implementation Plan: 4 phases from backend scripts to documentation
• Acceptance Criteria: Clear must-have, should-have, and nice-to-have items
• Timeline: 8-12 hours estimated effort over 1 sprint

Technology Stack Identified:

• Backend: Node.js + TypeScript, Express, Prisma (PostgreSQL), BullMQ + Redis, MongoDB
• Frontend: React 19, Vite, Redux Toolkit, Tailwind CSS

The PRD includes a detailed implementation roadmap, risk mitigation strategies, and open questions for technical decisions. You can now use this as a blueprint for implementing the development mode scripts! 🚀