# Community Gas Stations - Integration Guide

Quick reference for integrating the community gas stations feature into MotoVaultPro.

## 1. Add Routes to App.tsx

Add these imports at the top of your main App.tsx or routing file:

```typescript
import { CommunityStationsPage } from './features/stations/pages/CommunityStationsPage';
import { CommunityStationsMobileScreen } from './features/stations/mobile/CommunityStationsMobileScreen';
import { AdminCommunityStationsPage } from './features/admin/pages/AdminCommunityStationsPage';
import { AdminCommunityStationsMobileScreen } from './features/admin/mobile/AdminCommunityStationsMobileScreen';
```

Add these routes in your route configuration:

```typescript
// User routes
<Route path="/stations/community" element={<CommunityStationsPage />} />
<Route path="/mobile/stations/community" element={<CommunityStationsMobileScreen />} />

// Admin routes
<Route path="/admin/community-stations" element={<AdminCommunityStationsPage />} />
<Route path="/mobile/admin/community-stations" element={<AdminCommunityStationsMobileScreen />} />
```

## 2. Update Navigation

### User Navigation
Add link to Community Stations:
```tsx
<NavLink to="/stations/community">
  Community Stations
</NavLink>
```

### Admin Navigation
Add link to Admin Community Stations:
```tsx
<NavLink to="/admin/community-stations">
  Community Station Reviews
</NavLink>
```

## 3. Backend API Implementation

### Required Endpoints

Implement these endpoints in your backend API:

#### User Endpoints
```
POST /api/stations/community/submit
  Body: SubmitStationData
  Response: CommunityStation

GET /api/stations/community/mine
  Response: CommunityStation[]

DELETE /api/stations/community/:id
  Response: 204 No Content

GET /api/stations/community/approved?page=0&limit=50
  Response: { stations: CommunityStation[], total: number, page: number, limit: number }

POST /api/stations/community/nearby
  Body: { latitude, longitude, radiusMeters }
  Response: CommunityStation[]
```

#### Admin Endpoints
```
GET /api/stations/community/admin/submissions?status=&page=0&limit=50
  Response: CommunityStationsListResponse

GET /api/stations/community/admin/pending?page=0&limit=50
  Response: CommunityStationsListResponse

PATCH /api/stations/community/admin/:id/review
  Body: { status: 'approved' | 'rejected', rejectionReason?: string }
  Response: CommunityStation

POST /api/stations/community/admin/bulk-review
  Body: { ids: string[], status: 'approved' | 'rejected', rejectionReason?: string }
  Response: CommunityStation[]
```

### Database Schema

The backend should have migrations for the `community_stations` table:

```sql
CREATE TABLE community_stations (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  submitted_by VARCHAR(255) NOT NULL,
  name VARCHAR(200) NOT NULL,
  address TEXT NOT NULL,
  city VARCHAR(100),
  state VARCHAR(50),
  zip_code VARCHAR(20),
  latitude DECIMAL(10, 8) NOT NULL,
  longitude DECIMAL(11, 8) NOT NULL,
  brand VARCHAR(100),
  has_93_octane BOOLEAN DEFAULT true,
  has_93_octane_ethanol_free BOOLEAN DEFAULT false,
  price_93 DECIMAL(5, 3),
  notes TEXT,
  status VARCHAR(20) DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected')),
  reviewed_by VARCHAR(255),
  reviewed_at TIMESTAMP WITH TIME ZONE,
  rejection_reason TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_community_stations_status ON community_stations(status);
CREATE INDEX idx_community_stations_submitted_by ON community_stations(submitted_by);
CREATE INDEX idx_community_stations_location ON community_stations(latitude, longitude);
CREATE INDEX idx_community_stations_created_at ON community_stations(created_at DESC);
```

## 4. Environment Variables

No additional environment variables required. The API client uses the existing `VITE_API_BASE_URL`.

## 5. Testing

### Run Component Tests
```bash
npm test -- features/stations/community
npm test -- features/admin/community
```

### Test Mobile Viewport
```bash
# Open DevTools and set viewport to 375x667 (mobile)
# Test on: Browse, Submit, My Submissions tabs
# Verify: Form submission, withdrawal, pagination
```

### Test Desktop Viewport
```bash
# Open on 1920x1080 (desktop)
# Test on: Browse All, My Submissions, Near Me tabs
# Verify: Submit dialog, status filtering, nearby stations
```

## 6. Manual Testing Checklist

### User Features
- [ ] Navigate to /stations/community
- [ ] Submit new station with geolocation
- [ ] Submit station with manual coordinates
- [ ] Submit station with all optional fields
- [ ] View approved stations
- [ ] View personal submissions
- [ ] Withdraw pending submission
- [ ] View rejected submission with reason
- [ ] Browse nearby approved stations
- [ ] Test pagination
- [ ] Test form validation (missing fields)
- [ ] Test location permission denied
- [ ] Test on mobile viewport
- [ ] Test on desktop viewport
- [ ] Test tab switching

### Admin Features
- [ ] Navigate to /admin/community-stations
- [ ] View pending submissions
- [ ] Approve submission
- [ ] Reject submission with reason
- [ ] Filter submissions by status
- [ ] View all submissions
- [ ] View approval statistics
- [ ] Test pagination
- [ ] Test on mobile viewport
- [ ] Test on desktop viewport
- [ ] Test tab switching
- [ ] Verify admin-only access

## 7. Deployment

### Prerequisites
1. Backend API endpoints implemented
2. Database migrations applied
3. Admin role configured in authentication
4. Test on staging environment

### Deployment Steps
1. Merge to main branch
2. Run full test suite
3. Build and deploy frontend
4. Verify routes are accessible
5. Monitor logs for errors
6. Test on mobile and desktop

## 8. Monitoring

### Key Metrics
- Form submission success rate
- Approval/rejection ratio
- Pending submissions count
- Error rate on API endpoints
- Mobile vs desktop usage

### Common Issues

**Form submission fails**
- Check backend API endpoints are implemented
- Verify JWT authentication is working
- Check CORS settings

**Geolocation not working**
- Check browser permissions
- Test on HTTPS only (required for geolocation)
- Verify GPS access on mobile device

**Admin endpoints return 403**
- Verify user has admin role
- Check authentication token is valid
- Check admin authorization middleware

**Images/photos not loading**
- Verify station photo API endpoints
- Check CloudFront/CDN cache
- Check CORS headers

## 9. Performance Optimization

### Implemented
- React Query caching
- Lazy loading of routes
- Code splitting
- Image optimization

### Optional Enhancements
- Implement infinite scroll for stations list
- Add offline support with service workers
- Implement map tile caching
- Add predictive prefetching

## 10. Security Considerations

### Already Implemented
- JWT authentication on all endpoints
- User-scoped data isolation
- Admin role-based access control
- Form validation (Zod)
- Input sanitization via axios

### Verify
- SQL injection prevention (parameterized queries)
- XSS prevention (React's built-in escaping)
- CSRF token validation
- Rate limiting on API endpoints
- Admin operations audit logging

## Quick Troubleshooting

### Components not rendering
1. Check routes are added to App.tsx
2. Verify imports are correct
3. Check browser console for errors
4. Verify React Query is initialized

### API calls failing
1. Check backend endpoints are implemented
2. Verify base URL is correct (VITE_API_BASE_URL)
3. Check authentication token is included
4. Verify CORS headers

### Tests failing
1. Mock API responses correctly
2. Use React Query's test utilities
3. Check for missing wait() calls
4. Verify Zod schema matches types

### Mobile layout broken
1. Check viewport settings
2. Verify MUI breakpoints are used
3. Check responsive classes
4. Test on actual mobile device

## Support

For detailed documentation, see:
- `/frontend/src/features/stations/COMMUNITY-STATIONS-README.md`
- `/COMMUNITY-STATIONS-IMPLEMENTATION.md`
- `/COMMUNITY-STATIONS-FILES.md`

## File References

All absolute paths to files:

### User Features
- Desktop Page: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/pages/CommunityStationsPage.tsx`
- Mobile Screen: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/mobile/CommunityStationsMobileScreen.tsx`
- Submit Form: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/components/SubmitStationForm.tsx`
- Station Card: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/components/CommunityStationCard.tsx`
- Hooks: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/hooks/useCommunityStations.ts`

### Admin Features
- Desktop Page: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/admin/pages/AdminCommunityStationsPage.tsx`
- Mobile Screen: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/admin/mobile/AdminCommunityStationsMobileScreen.tsx`
- Review Card: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/admin/components/CommunityStationReviewCard.tsx`

### API & Types
- API Client: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/api/community-stations.api.ts`
- Types: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/types/community-stations.types.ts`
