adopt-a-street/README.md

Adopt-a-Street

A community street adoption platform where users can adopt streets, complete maintenance tasks, participate in events, and earn rewards through a gamification system.

🏗️ Architecture

• Frontend: React 19 with React Router v6, Leaflet mapping
• Backend: Node.js/Express with CouchDB database
• Deployment: Kubernetes on Raspberry Pi cluster
• Real-time: Server-Sent Events (SSE) for live updates

🚀 Quick Start

Prerequisites

• Node.js 18+ and Bun runtime
• CouchDB 3.3+ (or Docker)
• Git

Local Development

1. Clone the repository

   git clone <repository-url>
   cd adopt-a-street
   

2. Install dependencies

   # Backend
   cd backend
   bun install
   
   # Frontend
   cd ../frontend
   bun install
   

3. Set up CouchDB

   Option A: Docker (Recommended)

   # From project root
   docker-compose up -d couchdb
   
   # Wait for CouchDB to start
   sleep 10
   
   # Setup database and indexes
   cd backend
   bun run setup:couchdb
   

   Option B: Manual Installation

   # Install CouchDB locally
   # Follow instructions at: https://docs.couchdb.org/en/stable/install/index.html
   
   # Setup database and indexes
   cd backend
   COUCHDB_URL=http://localhost:5984 \
   COUCHDB_USER=admin \
   COUCHDB_PASSWORD=admin \
   bun run setup:couchdb
   

4. Configure environment

   # Backend
   cd backend
   cp .env.example .env
   # Edit .env with your CouchDB credentials and other settings
   
   # Frontend
   cd ../frontend
   cp .env.example .env
   # Edit .env with your API URL
   

5. Seed initial data

   cd backend
   bun run seed:badges
   

6. Start the applications

   # Backend (in one terminal)
   cd backend
   bun run dev
   
   # Frontend (in another terminal)
   cd frontend
   bun start
   

7. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:5000
   • CouchDB Admin: http://localhost:5984/_utils

Docker Development

Use Docker Compose for the complete stack:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

📦 Database Migration

If you're migrating from MongoDB to CouchDB:

# Run migration script
node scripts/migrate-to-couchdb.js

# For production migration
node scripts/migrate-production.js

See COUCHDB_SETUP.md for detailed migration instructions.

🧪 Testing

Backend Tests

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

Frontend Tests

cd frontend
bun test                    # Run in watch mode
bun run test:coverage      # Run with coverage

🚢 Deployment

Kubernetes (Production)

The application is designed for deployment on a Kubernetes cluster, specifically optimized for Raspberry Pi hardware.

1. Build multi-arch Docker images

   docker buildx create --use --name multiarch-builder
   
   docker buildx build --platform linux/arm64,linux/arm/v7 \
     -t your-registry/adopt-a-street-backend:latest \
     --push ./backend
   
   docker buildx build --platform linux/arm64,linux/arm/v7 \
     -t your-registry/adopt-a-street-frontend:latest \
     --push ./frontend
   

2. Deploy to Kubernetes

   # Configure secrets
   cp deploy/k8s/secrets.yaml.example deploy/k8s/secrets.yaml
   # Edit secrets with your values
   
   # Deploy all services
   cd deploy/k8s
   kubectl apply -f namespace.yaml
   kubectl apply -f secrets.yaml
   kubectl apply -f couchdb-configmap.yaml
   kubectl apply -f couchdb-statefulset.yaml
   kubectl apply -f configmap.yaml
   kubectl apply -f backend-deployment.yaml
   kubectl apply -f frontend-deployment.yaml
   kubectl apply -f ingress.yaml
   

See deploy/README.md for detailed deployment instructions.

📁 Project Structure

adopt-a-street/
├── backend/                 # Node.js/Express API
│   ├── models/              # Data models (CouchDB service)
│   ├── routes/              # API routes
│   ├── middleware/          # Express middleware
│   ├── services/            # Business logic
│   ├── scripts/             # Utility scripts
│   └── __tests__/           # Backend tests
├── frontend/                # React application
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── context/         # React Context
│   │   └── __tests__/       # Frontend tests
│   └── public/              # Static assets
├── deploy/                  # Kubernetes manifests
│   └── k8s/                 # Deployment configurations
├── scripts/                 # Migration and setup scripts
├── couchdb/                 # CouchDB configuration
└── docs/                    # Documentation

🔧 Configuration

Environment Variables

Backend (.env)

# CouchDB Configuration
COUCHDB_URL=http://localhost:5984
COUCHDB_DB_NAME=adopt-a-street
COUCHDB_USER=admin
COUCHDB_PASSWORD=admin

# JWT Authentication
JWT_SECRET=your-super-secret-jwt-key

# Server Configuration
PORT=5000
NODE_ENV=development
FRONTEND_URL=http://localhost:3000

# Cloudinary (for image uploads)
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Stripe (for payments)
STRIPE_SECRET_KEY=your_stripe_secret
STRIPE_PUBLISHABLE_KEY=your_stripe_publishable

# OpenAI (for AI features)
OPENAI_API_KEY=your_openai_key

Frontend (.env)

REACT_APP_API_URL=http://localhost:5000

🏛️ API Endpoints

• /api/auth - User authentication
• /api/users - User management
• /api/streets - Street adoption
• /api/tasks - Maintenance tasks
• /api/posts - Social feed
• /api/events - Community events
• /api/rewards - Points and badges
• /api/reports - Issue reporting
• /api/ai - AI-powered features
• /api/payments - Premium subscriptions

🎮 Features

• Street Adoption: Adopt and maintain local streets
• Task Management: Create and complete maintenance tasks
• Social Feed: Share updates and interact with community
• Events: Organize and participate in community events
• Gamification: Earn points, badges, and rewards
• Real-time Updates: Live notifications via Socket.IO
• Interactive Maps: Visualize adopted streets with Leaflet
• Mobile Responsive: Works on all device sizes

🔒 Security

• JWT-based authentication
• Input validation and sanitization
• Rate limiting
• CORS configuration
• Helmet.js security headers
• Environment-based configuration

📊 Monitoring

• CouchDB metrics exporter (Prometheus compatible)
• Health check endpoints
• Application logging
• Error tracking with ErrorBoundary

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Commit your changes with conventional commit messages
7. Push to your fork
8. Create a pull request

📝 License

This project is licensed under the ISC License.

🆘 Support

For issues and questions:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information
4. Join our community discussions

🗺️ Roadmap

• Mobile app development
• Advanced analytics dashboard
• Integration with city services
• Machine learning for task prioritization
• Multi-language support
• Enhanced offline capabilities

---

Built with ❤️ for community engagement and street maintenance