feat: add comprehensive styling and AI agent guidelines
- Add Bootstrap CSS and custom styles to frontend (index.css, App.css) - Create comprehensive AGENTS.md with instructions for all AI models - Include Gemini AI agent usage guidelines and commands - Add complete project documentation and development workflow - Ensure proper styling for React components using Bootstrap classes 🤖 Generated with [AI Assistant] Co-Authored-By: AI Assistant <noreply@ai-assistant.com>
This commit is contained in:
William Valentin
252
AGENTS.md
252
AGENTS.md
@@ -1,8 +1,82 @@
|
||||
# Agent Guidelines for Adopt-a-Street
|
||||
|
||||
This file provides comprehensive guidance for all AI models (Claude, Gemini, and others) 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 && npm test
|
||||
|
||||
# Frontend
|
||||
cd frontend && npm 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 [AI Assistant]
|
||||
|
||||
Co-Authored-By: AI Assistant <noreply@ai-assistant.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
|
||||
|
||||
## Commands
|
||||
**Backend** (from `/backend`): `npm test` (no tests configured yet), `npx eslint .` (lint)
|
||||
**Frontend** (from `/frontend`): `npm test` (run all tests), `npm test -- --testNamePattern="test name"` (single test), `npm run build` (build), `npm start` (dev server)
|
||||
|
||||
### Backend (from `/backend`)
|
||||
- `npm test` - Run all tests
|
||||
- `npx eslint .` - Run linter
|
||||
- `node server.js` - Start development server
|
||||
|
||||
### Frontend (from `/frontend`)
|
||||
- `npm test` - Run all tests in watch mode
|
||||
- `npm test -- --testNamePattern="test name"` - Run single test
|
||||
- `npm run build` - Production build
|
||||
- `npm start` - Start development server
|
||||
|
||||
## Code Style
|
||||
|
||||
@@ -23,3 +97,177 @@
|
||||
### General
|
||||
- **Types**: No TypeScript configured; use JSDoc comments for complex functions if needed
|
||||
- **ESLint**: Follows eslint config in backend; "no-unused-vars" and "no-undef" set to warn
|
||||
|
||||
## 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.
|
||||
|
||||
## 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 v6, 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
|
||||
npm test # Run all tests
|
||||
npm run test:coverage # Run with coverage report
|
||||
npm run test:watch # Run in watch mode
|
||||
```
|
||||
|
||||
Frontend:
|
||||
```bash
|
||||
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](TESTING.md) for detailed testing documentation.
|
||||
|
||||
## Gemini AI Agents
|
||||
|
||||
Gemini LLM can be used to spawn AI agents for various tasks. There are two models available:
|
||||
|
||||
- **gemini-2.5-flash**: Quick responses that don't require thinking mode
|
||||
- **gemini-2.5-pro**: Thinking model for more demanding tasks
|
||||
|
||||
### Usage Commands
|
||||
```bash
|
||||
gemini --model gemini-2.5-flash -p "<PROMPT>"
|
||||
gemini --model gemini-2.5-pro -p "<PROMPT>"
|
||||
```
|
||||
|
||||
Use flash for simple, quick tasks and pro for complex reasoning, analysis, or creative tasks that require deeper thinking.
|
||||
|
||||
## AI Assistant Guidelines
|
||||
|
||||
### For All AI Models
|
||||
1. **Always read existing code** before making changes to understand patterns and conventions
|
||||
2. **Follow the established code style** and architectural patterns
|
||||
3. **Test your changes** before committing
|
||||
4. **Commit frequently** with descriptive messages following the conventional commit format
|
||||
5. **Ask for clarification** if requirements are unclear
|
||||
6. **Document complex decisions** in code comments or commit messages
|
||||
7. **Consider performance implications** of changes, especially for the Raspberry Pi deployment
|
||||
8. **Maintain backward compatibility** where possible, but remember breaking changes are allowed in development
|
||||
|
||||
### Task Prioritization
|
||||
1. **High Priority**: Security fixes, critical bugs, deployment blockers
|
||||
2. **Medium Priority**: New features, performance improvements, test coverage
|
||||
3. **Low Priority**: Code refactoring, documentation updates, minor UI improvements
|
||||
|
||||
### Communication
|
||||
- Be clear and concise in commit messages and code comments
|
||||
- Explain the "why" behind complex changes
|
||||
- Flag any potential breaking changes or security concerns
|
||||
- Suggest follow-up tasks or improvements when relevant
|
||||
|
||||
### Quality Assurance
|
||||
- Run linting and tests before committing
|
||||
- Ensure code follows established patterns
|
||||
- Verify functionality works end-to-end
|
||||
- Check for potential security vulnerabilities
|
||||
- Consider edge cases and error handling
|
||||
|
||||
Remember: This is a collaborative development environment. Your contributions help build a robust community platform for street adoption and maintenance.
|
||||
Reference in New Issue
Block a user