Get Started with ReViewPoint¶

**Fresh Windows mac💡**Docker Note**: Docker Desktop requires manual installation but isn't required for basic development (SQLite mode works without it).

🔍 What Tools Get Installed? (Complete Transparency)¶

The automated installer is completely transparent about what it installs:

Core Tools Installed via Chocolatey:¶

Package Managers Installed via Native Tools:¶

Manual Installation Required:¶

🛡️ Security & Privacy:¶

• All tools are official: Downloaded from official sources (chocolatey.org, nodejs.org, python.org)
• No data collection: The installer only installs tools, no telemetry
• PATH modifications: Tools are added to Windows PATH for command-line access
• Admin privileges: Some installations may require administrator rights

📋 Before Installation Checklist:¶

Before running the automated installer, you'll see a complete list of what will be installed:

📦 TOOLS THAT WILL BE INSTALLED:
  1. Chocolatey - Package manager for Windows
  2. Git - Version control system
  3. Node.js 18+ - JavaScript runtime
  4. pnpm - Fast package manager (via npm)
  5. Python 3.11+ - Backend runtime
  6. pipx - Python application installer
  7. Hatch - Python environment manager (via pipx)

⚠️  Docker Desktop - Requires MANUAL installation (guidance provided)

You must confirm before any installation begins!

🔒 VS Code Task Safety System¶

All VS Code development tasks now check prerequisites first:

Tasks with Prerequisite Checks:¶

Error Message Examples:¶

If you try to run a task without prerequisites:

❌ pnpm not found! Run "Setup Fresh Windows Machine" task first
💡 Or run: .\scripts\install-prerequisites.ps1

Success Message Examples:¶

When prerequisites are found:

✅ Prerequisites OK, starting frontend...

This ensures you can never accidentally run a task that will fail due to missing tools!

🛠️ Manual Installation (If Automatic Fails)¶

**⏱️ Expected time: 15-20 minutes**et ReViewPoint running in just 3 steps!**

🚀 Quick Start for Fresh Windows Machines¶

⏱️ Total time: 5-10 minutes (fully automated)

Method 1: Automatic Setup (Recommended)¶

Perfect for fresh Windows machines or professor grading scenarios:

1. Download the project:

git clone https://github.com/filip-herceg/ReViewPoint.git
cd ReViewPoint

1. Run the automated installer:

powershell -ExecutionPolicy Bypass -File scripts/install-prerequisites.ps1

1. Start development:

pnpm run dev

That's it! The script automatically installs Git, Node.js, Python, pnpm, hatch, and provides Docker guidance.

Method 2: VS Code Tasks (If VS Code is available)¶

1. Open the project in VS Code
2. Press Ctrl+Shift+P → Type "Tasks: Run Task"
3. Select "ReViewPoint: Setup Fresh Windows Machine"
4. Wait for automatic installation to complete
5. Run "ReViewPoint: Start Both (Backend + Frontend) - SQLite"

🛠️ What Gets Installed Automatically¶

The automated installer handles all prerequisites:

💡 Docker Note: Docker Desktop requires manual installation but isn't required for basic development (SQLite mode works without it).

� Manual Installation (If Automatic Fails)¶

⏱️ Expected time: 15-20 minutes

Install these tools in order. Don't skip any steps!

🚨 Critical Windows Notes:¶

• Python: ✅ Check "Add Python to PATH" during installation
• Docker Desktop: ✅ Must be running (started) before proceeding
• PowerShell: ✅ Run commands in PowerShell (not Command Prompt)

🔍 Step 2: Verify Installation¶

Run this VS Code task to check everything:

1. Open VS Code in the project folder
2. Run task: "ReViewPoint: Check PostgreSQL Prerequisites"

Or manually verify with:

# Check all tools are installed
git --version
node --version
pnpm --version
python --version
hatch --version
docker --version

# Critical: Check Docker is RUNNING
docker info

❌ If any command fails, go back to Step 1 and reinstall that tool.

⚡ Step 3: Super Quick Start (2 minutes)¶

Once prerequisites are verified, get everything running:

git clone https://github.com/filip-herceg/ReViewPoint.git
cd ReViewPoint
pnpm run dev:postgres

🎉 That's it! Your ReViewPoint development environment is now running!

🌐 Access Your Application:¶

• 📱 Main Application: http://localhost:5173 ← Start here!
• 📚 This Documentation: http://127.0.0.1:8001/ReViewPoint/
• 🔧 Backend API: http://localhost:8000
• 📖 API Documentation: http://localhost:8000/docs

� Alternative Installation Methods¶

Method 1: VS Code Tasks (Recommended for beginners)¶

Step-by-step using VS Code interface:

1. Install Dependencies:
2. Run task: "ReViewPoint: Install Dependencies"

3. ✅ Installs all project dependencies automatically

4. Choose Database & Start:

5. PostgreSQL (production-like): Run "ReViewPoint: Start Both (Backend + Frontend) - PostgreSQL"
6. SQLite (simpler): Run "ReViewPoint: Start Both (Backend + Frontend) - SQLite"

Method 2: Manual Commands¶

# 1. Clone and navigate
git clone https://github.com/filip-herceg/ReViewPoint.git
cd ReViewPoint

# 2. Install dependencies
pnpm install                    # Root dependencies
cd backend && hatch env create  # Backend Python environment
cd ../frontend && pnpm install  # Frontend dependencies
cd ..

# 3. Choose your setup:

# Option A: PostgreSQL (recommended)
pnpm run dev:postgres

# Option B: SQLite (simpler)
pnpm run dev

Method 3: Individual Components¶

If you want to start backend and frontend separately:

# Terminal 1: Start Backend
pnpm run postgres:start  # Start PostgreSQL container
# Then run VS Code task: "ReViewPoint: Start Backend"

# Terminal 2: Start Frontend
# Run VS Code task: "ReViewPoint: Start Frontend"

📋 Available VS Code Tasks¶

Essential tasks for development:

🚀 Development Tasks¶

🧪 Testing Tasks¶

🔧 Utility Tasks¶

🗄️ Database Tasks¶

✅ Verification Steps¶

After installation, verify everything works:

1. Check Services are Running¶

# Frontend should be accessible
curl http://localhost:5173

# Backend should respond
curl http://localhost:8000/health

# API docs should load
# Visit: http://localhost:8000/docs

2. Run Quick Tests¶

# Run a quick test to verify setup
# Use VS Code task: "ReViewPoint: Run Fast Backend Tests"
# Use VS Code task: "ReViewPoint: Run Frontend Tests"

3. Check Database Connection¶

• Backend logs should show successful database connection
• No error messages in terminal outputs

🐛 Common Issues & Solutions¶

Docker Issues¶

# Problem: "docker: command not found"
# Solution: Install Docker Desktop and ensure it's running

# Problem: "Cannot connect to the Docker daemon"
# Solution: Start Docker Desktop application

# Problem: "docker info" fails
# Solution: Restart Docker Desktop, wait for it to fully start

Python/Hatch Issues¶

# Problem: "hatch: command not found"
# Solution:
pipx install hatch
# Then restart terminal

# Problem: "Python version not found"
# Solution: Reinstall Python, check "Add to PATH"

Node.js/pnpm Issues¶

# Problem: "pnpm: command not found"
# Solution:
npm install -g pnpm

# Problem: Permission errors on Windows
# Solution: Run PowerShell as Administrator

Port Conflicts¶

# Problem: Port 5173 or 8000 already in use
# Solution: Kill existing processes:
npx kill-port 5173
npx kill-port 8000

🎯 Next Steps¶

After successful installation:

1. Explore the API: Visit http://localhost:8000/docs
2. Check Documentation: Browse to the Developer Documentation
3. Run Tests: Execute tests to ensure everything works
4. Start Developing: Read Development Guidelines

Ready to contribute? See our Contributing Guide.

📞 Need Help?¶

If you encounter issues:

1. Check Prerequisites: Run the "Check PostgreSQL Prerequisites" task
2. Review Logs: Look at terminal output for error messages
3. Clean & Retry: Run "Clean All" task and restart
4. Ask for Help: Create an issue on GitHub with your error message

Most issues are caused by missing prerequisites or Docker not running!

### **Option 2: Simple SQLite Setup**

**Best for**: Quick testing, no Docker needed

```bash
# Simpler setup with SQLite database
pnpm run dev

Option 3: Manual Step-by-Step¶

Best for: Understanding the setup process

# 1. Install dependencies
pnpm run install

# 2. Choose your database option:

# Option A: PostgreSQL (production-like)
pnpm run postgres:start  # Starts PostgreSQL container
pnpm run db:migrate     # Runs database migrations

# Option B: SQLite (simple)
# Nothing needed - SQLite file created automatically

# 3. Start the development servers
pnpm run backend &      # Start FastAPI backend
pnpm run frontend       # Start Vite frontend

✅ Verify Installation¶

Check that everything is working correctly:

1. 📱 Main App: http://localhost:5173 shows the ReViewPoint login page
2. 📚 Documentation: http://127.0.0.1:8001/ReViewPoint/ shows this documentation site
3. 🔧 Backend API: http://localhost:8000/docs shows Swagger documentation
4. 💚 Health Check: http://localhost:8000/api/v1/health returns {"status": "healthy"}

🛠️ VS Code Integration (Recommended)¶

ReViewPoint includes 24 VS Code tasks for streamlined development:

1. Open ReViewPoint in VS Code
2. Press Ctrl+Shift+P (Cmd+Shift+P on Mac)
3. Type "Tasks: Run Task"
4. Choose from available tasks:

🎯 Next Steps¶

Now that you're up and running:

1. 📖 Read the Developer Documentation - Understand the architecture
2. 🧪 Run the tests: pnpm run test:all - Verify everything works
3. 🎨 Explore the code - Check out backend/src/ and frontend/src/
4. 🚀 Make your first change - Follow the Contributing Guide

🆘 Troubleshooting¶

Common Issues¶

Port conflicts:

# Check what's using the ports
lsof -i :8000  # Backend port
lsof -i :5173  # Frontend port
lsof -i :5432  # PostgreSQL port

# Kill processes if needed
kill -9 <PID>

Database connection issues:

# Reset PostgreSQL
pnpm run postgres:stop
pnpm run postgres:start

# Or switch to SQLite
pnpm run db:sqlite

Dependency issues:

# Clean and reinstall everything
pnpm run clean
pnpm run install

Python environment issues:

# Reset Python environment
cd backend
rm -rf .hatch
hatch env create

Still having issues?¶

1. Check the FAQ - Common problems and solutions
2. Search GitHub Issues - See if others had the same problem
3. Create a new issue - We're here to help!

🎉 You're Ready!¶

Congratulations! You now have a fully functional ReViewPoint development environment.

What's running:

• ✅ Backend: FastAPI server with hot reload
• ✅ Frontend: React app with Vite hot reload
• ✅ Database: PostgreSQL or SQLite
• ✅ Tests: Full test suite ready to run

Start developing: Check out the Developer Documentation to learn the codebase!

# Clone the repository
git clone https://github.com/filip-herceg/ReViewPoint.git
cd ReViewPoint

# Install dependencies
pnpm run install

# Start with PostgreSQL (auto-setup)
pnpm run dev:postgres

This will:

• Check for Docker availability
• Start PostgreSQL container automatically
• Run database migrations
• Start both backend and frontend services

Manual Setup¶

If you prefer manual control over each step:

1. Install Dependencies¶

# Root dependencies
pnpm install

# Backend dependencies (Python)
cd backend
hatch env create
cd ..

# Frontend dependencies (Node.js)
cd frontend
pnpm install
cd ..

2. Database Setup¶

Option A: SQLite (Simple)¶

# Switch to SQLite mode
pnpm run db:sqlite

# Run migrations
cd backend
hatch run alembic upgrade head
cd ..

Option B: PostgreSQL (Recommended)¶

# Start PostgreSQL container
pnpm run postgres:start

# Run migrations
cd backend
hatch run alembic upgrade head
cd ..

3. Start Services¶

# Terminal 1: Start backend
cd backend
hatch run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 2: Start frontend
cd frontend
pnpm run dev

Environment Configuration¶

Backend Configuration¶

The backend uses environment variables from backend/config/.env:

# Database URL (automatically set by scripts)
REVIEWPOINT_DB_URL=sqlite+aiosqlite:///./reviewpoint_dev.db

# OR for PostgreSQL:
# REVIEWPOINT_DB_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/reviewpoint

# Other settings
SECRET_KEY=your-secret-key
DEBUG=true

Frontend Configuration¶

The frontend automatically connects to the backend API. No configuration needed for development.

Verification¶

Once everything is running, verify the installation:

1. Backend API: Visit http://localhost:8000/docs for the FastAPI Swagger UI
2. Frontend App: Visit http://localhost:3000 for the React application
3. Health Check: The frontend should successfully connect to the backend

Common Issues¶

Docker Not Found¶

If you see "Docker not found" but want to use PostgreSQL:

1. Install Docker Desktop
2. Ensure Docker is running
3. Run pnpm run postgres:check to verify

Port Conflicts¶

Default ports:

• Backend: 8000
• Frontend: 3000
• PostgreSQL: 5432

If these ports are busy, modify the configuration or stop conflicting services.

Permission Issues¶

On Linux/macOS, you might need to run Docker commands with sudo or add your user to the Docker group.

Development Workflow¶

Running Tests¶

# Backend tests
pnpm run test:backend

# Frontend tests
pnpm run test:frontend

# All tests
pnpm run test

Code Quality¶

# Lint and format backend
pnpm run lint:backend
pnpm run format:backend

# Lint and format frontend
pnpm run lint:frontend
pnpm run format:frontend

Database Migrations¶

# Create new migration
cd backend
hatch run alembic revision --autogenerate -m "Description"

# Apply migrations
hatch run alembic upgrade head

Next Steps¶

• Read the Developer Overview for architecture details
• Explore the Backend Documentation for API details
• Check out the Frontend Documentation for UI components
• Review Contributing Guidelines to start contributing

Getting Help¶

• Documentation: Browse this documentation for detailed guides
• Issues: Report problems on GitHub Issues
• Discussions: Ask questions in GitHub Discussions