Skip to main content

Quick Setup Guide

Get Rainfall-Learning running on your local machine in minutes with this step-by-step guide.

Project Overview​

Rainfall-Learning is a monorepo containing:

  • Backend: Node.js API with Prisma ORM
  • Frontend: React/Vite application with Material-UI
  • Shared: TypeScript types and utilities shared between packages

Project Structure​

packages/
├── backend/     # Node.js API with Prisma
├── frontend/    # React/Vite application
└── shared/      # Shared types and utilities

Prerequisites​

Before you begin, ensure you have the following installed:

  • Node.js v18.0.0 or higher
  • npm v9.0.0 or higher
  • Docker (for database and services)
  • Git for version control

Verify Prerequisites​

# Check Node.js version
node --version  # Should output v18.0.0 or higher

# Check npm version
npm --version   # Should output 9.0.0 or higher

# Check Docker
docker --version

Quick Start​

1. Clone the Repository​

git clone https://github.com/Aryan0102/Rainfall-Learning.git
cd Rainfall-Learning

2. Install Dependencies​

# Install all dependencies for the monorepo
npm install

# This automatically installs dependencies for:
# - Root workspace
# - packages/backend
# - packages/frontend
# - packages/shared

3. Start Development Environment​

# Start all containers (auto-builds if needed)
npm run docker:start

# This automatically:
# - Builds Docker containers if they don't exist
# - Starts PostgreSQL database with health monitoring
# - Starts backend (waits for healthy database)
# - Starts frontend with shared packages
# - Handles all migrations automatically

Note: The --build flag ensures containers are built if they don't exist, so developers don't need to remember to run docker:build first.

That's it! Your application should now be running:

4. Run Tests​

# Run all tests (backend + frontend)
npm run test

# This runs tests inside Docker containers:
# - Backend tests with database access
# - Frontend tests with DOM environment (jsdom)
# - All shared package imports work correctly
# - Tests are located in packages/*/tests/ directories

Testing Notes:

  • Tests run inside Docker containers for consistency
  • Database is automatically set up when you start Docker
  • No need to rebuild containers for test file changes
  • Tests have access to the same environment as your application
  • Frontend tests are located in packages/frontend/tests/
  • Backend tests are located in packages/backend/tests/
  • Test configuration uses Vitest with proper path mapping for shared packages

Available Scripts​

Docker Development​

CommandDescription
npm run docker:buildBuild all Docker containers
npm run docker:startStart all services (auto-builds)
npm run docker:stopStop all services
npm run docker:logsView logs from all containers
npm run docker:rebuildRebuild containers from scratch

Traditional Development (Alternative)​

CommandDescription
npm run devStart both frontend and backend in development mode
npm run dev:backendStart only the backend server
npm run dev:frontendStart only the frontend application
npm run buildBuild all packages for production

Code Quality​

CommandDescription
npm run lintRun ESLint on all packages
npm run lint:fixAuto-fix ESLint issues
npm run formatFormat code with Prettier
npm run format:checkCheck if code is formatted
npm run typecheckRun TypeScript type checking

Testing​

CommandDescription
npm run testRun all tests (backend + frontend)
npm run test:watchRun backend tests in watch mode
npm run test:backendTest only backend (Docker container)
npm run test:frontendTest only frontend (Docker container)
npm run test:sharedTest shared package (Docker container)
npm run test:coverageGenerate test coverage report
npm run test:coverage:backendBackend coverage only
npm run test:coverage:frontendFrontend coverage only
npm run test:coverage:sharedShared package coverage only

Note: All tests run inside Docker containers for consistency with the development environment.

Documentation​

CommandDescription
npm run docs:buildBuild all documentation
npm run docs:typedocGenerate TypeDoc API docs
npm run docs:swaggerGenerate Swagger API docs

Container Independence​

The Docker setup provides complete container independence:

✅ Automatic Setup​

  • Database: PostgreSQL with persistent storage
  • Backend: Node.js API with Prisma client generation
  • Frontend: React/Vite with shared package building

✅ No Manual Intervention​

  • Dependencies install automatically
  • Database schema resets and migrates automatically
  • Shared packages build automatically
  • Hot reloading works out of the box

✅ Development Workflow​

  1. Start: npm run docker:start
  2. Make changes: Edit files in packages/backend or packages/frontend
  3. See changes: Hot reloading reflects immediately
  4. Test: npm run test (runs inside Docker containers)
  5. Stop: npm run docker:stop

Common Setup Issues​

Docker Not Running​

# Start Docker Desktop
# Then try again:
npm run docker:start

Port Conflicts​

# Check what's using the ports
lsof -i :3000  # Backend
lsof -i :5173  # Frontend
lsof -i :5432  # Database

# Kill processes if needed
kill -9 <PID>

Container Build Issues​

# Clean everything and rebuild
npm run docker:clean
npm run docker:rebuild

Database Connection Issues​

# Check container logs
npm run docker:logs

# Restart containers
npm run docker:restart

Verify Installation​

Run these commands to ensure everything is working:

# Check container status
docker-compose ps

# Check logs
npm run docker:logs

# Test backend API
curl http://localhost:3000/health

## Next Steps

1. **Explore the Documentation**
2. **Understand the Architecture**: Read the [Architecture Guide](/docs/General Important Info/architecture)
3. **Docker Setup**: Read the [Docker Guide](/docs/docker.md) for detailed configuration
4. **Set Up Your IDE**: Install recommended VS Code extensions

## Getting Help

- **Internal Discord**: #general or ping a tech lead
- **Documentation**: Check `/documentation/`
- **Docker Guide**: [Docker Setup Documentation](/docs/docker.md)
- **TypeScript IntelliSense**: Your IDE will provide hints for all shared types