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:

   # Backend
   cd backend && bun test
   
   # Frontend
   cd frontend && bun run build
   

2. Create a git commit with a descriptive message:

   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:

   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

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

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:

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

Frontend:

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 for detailed testing documentation.