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

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
npm install
# Create .env file with MONGO_URI, JWT_SECRET, PORT
node server.js  # Start backend on port 5000
npx eslint .    # Run linter

Frontend

cd frontend
npm install
npm start       # Start dev server on port 3000
npm test        # Run tests in watch mode
npm 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
npm test              # Run all tests
npm run test:coverage # Run with coverage report
npm run test:watch    # Run in watch mode

Frontend:

cd frontend
npm test              # Run in watch mode
npm 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.