motovaultpro/COMMUNITY-STATIONS-INTEGRATION-GUIDE.md

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:

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:

// 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:

<NavLink to="/stations/community">
  Community Stations
</NavLink>

Admin Navigation

Add link to Admin Community Stations:

<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:

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

npm test -- features/stations/community
npm test -- features/admin/community

Test Mobile Viewport

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

Test Desktop Viewport

# 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