adopt-a-street/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Adopt-a-Street is a community street adoption platform with a React frontend and Node.js/Express backend. Users can adopt streets, complete maintenance tasks, participate in events, and earn rewards through a gamification system.

## Development Status

**This project is in active development and NOT in production.** Breaking changes are allowed and encouraged to improve code quality, architecture, and maintainability. Feel free to:
- Refactor code structures and patterns
- Change APIs and data models
- Update dependencies and migrate to better solutions
- Restructure the codebase for improved architecture
- Make backward-incompatible changes that enhance the application

## Development Workflow

**IMPORTANT: Commit to Git After Every Feature/Fix/Update**

After implementing any feature, fix, or update, you MUST:

1. **Build and test** the changes:
   ```bash
   # Backend
   cd backend && bun test

   # Frontend
   cd frontend && bun run build
   ```

2. **Create a git commit** with a descriptive message:
   ```bash
   git add <files>
   git commit -m "feat/fix/docs: descriptive message

   Detailed explanation of changes...

   🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude <noreply@anthropic.com>"
   ```

3. **Use conventional commit prefixes**:
   - `feat:` - New features
   - `fix:` - Bug fixes
   - `docs:` - Documentation changes
   - `test:` - Test additions or updates
   - `refactor:` - Code refactoring
   - `chore:` - Maintenance tasks
   - `perf:` - Performance improvements

4. **Commit frequency**: Create commits for each logical unit of work. Don't batch multiple unrelated changes into one commit.

5. **Push regularly**: Push commits to origin after completing features or at end of session:
   ```bash
   git push origin main
   ```

This ensures:
- Clear history of all changes
- Easy rollback if needed
- Better collaboration and code review
- Deployment tracking
- CI/CD pipeline triggers

## Architecture

### Monorepo Structure
- `frontend/`: React application (Create React App)
- `backend/`: Express API server with MongoDB

### Backend Architecture
The backend follows a standard Express MVC pattern:
- `server.js`: Main entry point with Socket.IO for real-time updates
- `routes/`: API route handlers for auth, streets, tasks, posts, events, rewards, reports, ai, payments, users
- `models/`: Mongoose schemas (User, Street, Task, Post, Event, Reward, Report)
- `middleware/auth.js`: JWT authentication middleware using `x-auth-token` header

### Frontend Architecture
React SPA using React Router v6:
- `App.js`: Main router with client-side routing
- `context/AuthContext.js`: Global authentication state management
- `context/SocketContext.js`: Socket.IO real-time connection management
- `components/`: Feature components (MapView, TaskList, SocialFeed, Profile, Events, Rewards, Premium, Login, Register, Navbar, ErrorBoundary)
- Real-time updates via Socket.IO for events, posts, and tasks
- Interactive map with Leaflet for street visualization
- Comprehensive error handling with ErrorBoundary

Authentication flow: JWT tokens stored in localStorage and sent via `x-auth-token` header on all API requests.

Frontend proxies API requests to `http://localhost:5000` in development.

**Note:** This is a true monorepo - both frontend and backend are tracked in the same Git repository for simplified development and deployment.

## Development Commands

### Backend
```bash
cd backend
bun install
# Create .env file with MONGO_URI, JWT_SECRET, PORT
node server.js  # Start backend on port 5000
bunx eslint .    # Run linter
```

### Frontend
```bash
cd frontend
bun install
bun start       # Start dev server on port 3000
bun test        # Run tests in watch mode
bun run build   # Production build
```

## Environment Variables

Backend requires `.env` file:
- `MONGO_URI`: MongoDB connection string
- `JWT_SECRET`: Secret for JWT signing
- `PORT` (optional): Server port (defaults to 5000)

## API Endpoints

- `/api/auth`: Registration, login, and user authentication
- `/api/streets`: Street data and adoption management
- `/api/tasks`: Maintenance task CRUD operations
- `/api/posts`: Social feed posts
- `/api/events`: Community events with Socket.IO real-time updates
- `/api/rewards`: Points and rewards system
- `/api/reports`: Street condition reports
- `/api/ai`: AI-powered suggestions and insights
- `/api/payments`: Premium subscription management (currently mocked)
- `/api/users`: User profile management

## Key Technologies

- Frontend: React 19, React Router v5, Leaflet (mapping), Axios, Socket.IO client, Stripe.js
- Backend: Express, Mongoose (MongoDB), JWT, bcryptjs, Socket.IO, Stripe, Multer (file uploads)
- Testing: React Testing Library, Jest

## Socket.IO Events

Real-time features for events:
- `joinEvent(eventId)`: Join event room
- `eventUpdate`: Broadcast updates to event participants

## Deployment

### Kubernetes Raspberry Pi Cluster

This application is deployed on a Kubernetes cluster running on Raspberry Pi hardware:

**Cluster Configuration:**
- **2x Raspberry Pi 5 (8GB RAM)** - Primary worker nodes for application workloads
- **1x Raspberry Pi 3B+ (1GB RAM)** - Worker node for lightweight services

**Architecture Considerations:**
- ARM64 architecture (Pi 5) and ARMv7 architecture (Pi 3B+)
- Multi-arch Docker images required (linux/arm64, linux/arm/v7)
- Resource-constrained environment - optimize for low memory usage
- Frontend and backend should be containerized separately
- MongoDB should run as a StatefulSet with persistent storage
- Consider resource limits and requests appropriate for Pi hardware

**Deployment Strategy:**
- Use Kubernetes manifests or Helm charts
- Implement horizontal pod autoscaling based on available resources
- Place memory-intensive workloads (backend, MongoDB) on Pi 5 nodes
- Place frontend static serving on any node (lightweight)
- Use NodeAffinity/NodeSelector to control pod placement
- Implement health checks and readiness probes
- Use ConfigMaps for environment variables
- Use Secrets for sensitive data (JWT_SECRET, CLOUDINARY credentials, etc.)

See deployment documentation for Kubernetes manifests and deployment instructions.

## Testing

Comprehensive test infrastructure is in place for both backend and frontend.

### Running Tests

Backend:
```bash
cd backend
bun test              # Run all tests
bun run test:coverage # Run with coverage report
bun run test:watch    # Run in watch mode
```

Frontend:
```bash
cd frontend
bun test              # Run in watch mode
bun run test:coverage # Run with coverage report
```

### Test Coverage

- **Backend**: ~55% coverage (109 passing tests)
  - Route tests for auth, streets, tasks, posts, events, rewards, reports
  - Model tests for User, Street, Task, Post
  - Middleware tests for authentication
  - Using Jest + Supertest + MongoDB Memory Server

- **Frontend**: MSW infrastructure in place
  - Component tests for Login, Register, ErrorBoundary
  - Integration tests for authentication flow
  - Using React Testing Library + Jest + MSW

See [TESTING.md](TESTING.md) for detailed testing documentation.