From f8f1d51154e787c74aa21003325ff855d8aaa5c3 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sat, 1 Nov 2025 11:44:41 -0700 Subject: [PATCH] feat: add comprehensive styling and AI agent guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- AGENTS.md | 252 ++++++++++++++++++++++++++++++++++++++++- frontend/src/App.css | 123 ++++++++++++++++++++ frontend/src/index.css | 72 ++++++++++++ 3 files changed, 445 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 50b218a..f44310a 100644 --- a/AGENTS.md +++ b/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 + git commit -m "feat/fix/docs: descriptive message + + Detailed explanation of changes... + + 🤖 Generated with [AI Assistant] + + Co-Authored-By: AI Assistant " + ``` + +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 "" +gemini --model gemini-2.5-pro -p "" +``` + +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. \ No newline at end of file diff --git a/frontend/src/App.css b/frontend/src/App.css index e69de29..723ee54 100644 --- a/frontend/src/App.css +++ b/frontend/src/App.css @@ -0,0 +1,123 @@ +/* App-specific styles */ +.container { + max-width: 1200px; + margin: 0 auto; + padding: 0 15px; +} + +/* Navigation */ +.navbar { + box-shadow: 0 2px 4px rgba(0,0,0,0.1); +} + +.navbar-brand { + font-weight: bold; + font-size: 1.5rem; +} + +.nav-link { + cursor: pointer; + transition: color 0.3s ease; +} + +.nav-link:hover { + color: #007bff !important; +} + +/* Form styles */ +.form-group { + margin-bottom: 1rem; +} + +.form-control { + display: block; + width: 100%; + padding: 0.375rem 0.75rem; + font-size: 1rem; + line-height: 1.5; + color: #495057; + background-color: #fff; + background-clip: padding-box; + border: 1px solid #ced4da; + border-radius: 0.25rem; + transition: border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out; +} + +.form-control:focus { + color: #495057; + background-color: #fff; + border-color: #80bdff; + outline: 0; + box-shadow: 0 0 0 0.2rem rgba(0, 123, 255, 0.25); +} + +/* Button styles */ +.btn { + display: inline-block; + font-weight: 400; + text-align: center; + white-space: nowrap; + vertical-align: middle; + user-select: none; + border: 1px solid transparent; + padding: 0.375rem 0.75rem; + font-size: 1rem; + line-height: 1.5; + border-radius: 0.25rem; + transition: color 0.15s ease-in-out, background-color 0.15s ease-in-out, border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out; + cursor: pointer; + text-decoration: none; +} + +.btn-primary { + color: #fff; + background-color: #007bff; + border-color: #007bff; +} + +.btn-primary:hover { + color: #fff; + background-color: #0069d9; + border-color: #0062cc; +} + +.btn-primary:disabled { + color: #fff; + background-color: #6c757d; + border-color: #6c757d; + cursor: not-allowed; +} + +/* Card styles */ +.card { + position: relative; + display: flex; + flex-direction: column; + min-width: 0; + word-wrap: break-word; + background-color: #fff; + background-clip: border-box; + border: 1px solid rgba(0, 0, 0, 0.125); + border-radius: 0.25rem; + box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075); +} + +.card-body { + flex: 1 1 auto; + padding: 1.25rem; +} + +/* Responsive adjustments */ +@media (max-width: 768px) { + .container { + padding: 0 10px; + } + + .navbar-nav { + flex-direction: column; + } + + .nav-item { + margin-bottom: 0.5rem; + } +} \ No newline at end of file diff --git a/frontend/src/index.css b/frontend/src/index.css index e69de29..295c648 100644 --- a/frontend/src/index.css +++ b/frontend/src/index.css @@ -0,0 +1,72 @@ +/* Bootstrap CSS */ +@import url('https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css'); + +/* Global styles */ +body { + margin: 0; + font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', + 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', + sans-serif; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + background-color: #f8f9fa; +} + +code { + font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', + monospace; +} + +/* Custom utility classes */ +.text-center { + text-align: center; +} + +.mt-5 { + margin-top: 3rem; +} + +.mb-4 { + margin-bottom: 1.5rem; +} + +.btn-block { + display: block; + width: 100%; +} + +/* Loading spinner */ +.spinner-border { + display: inline-block; + width: 2rem; + height: 2rem; + vertical-align: text-bottom; + border: 0.25em solid currentColor; + border-right-color: transparent; + border-radius: 50%; + animation: spinner-border 0.75s linear infinite; +} + +.spinner-border-sm { + width: 1rem; + height: 1rem; + border-width: 0.125em; +} + +.sr-only { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} + +@keyframes spinner-border { + to { + transform: rotate(360deg); + } +} \ No newline at end of file