Project Structure

Directory Organization

src/
├── components/       # React components organized by feature
│   ├── auth/        # Authentication components (SignIn, SignUp, ProtectedRoute)
│   ├── layout/      # Layout components (Header, Footer, Navigation)
│   └── map/         # Map components (MapView, MapFilters)
├── pages/           # Page-level components for routing
├── services/        # API clients and external service integrations
├── hooks/           # Custom React hooks
├── utils/           # Utility functions and helpers
├── types/           # TypeScript type definitions
├── App.tsx          # Main application component with routing
├── main.tsx         # Application entry point
└── index.css        # Global styles with Tailwind directives

Component Organization

Components are organized by feature/domain rather than by type:

components/auth/ - All authentication-related components
components/map/ - All mapping-related components
components/layout/ - Shared layout components
Each feature folder includes an index.ts for clean exports

File Naming Conventions

Components: PascalCase (e.g., MapView.tsx, ReportForm.tsx)
Hooks: camelCase with use prefix (e.g., useAuth.ts, useGeolocation.ts)
Services: camelCase (e.g., api.ts, reportService.ts)
Utils: camelCase (e.g., validation.ts, coordinates.ts)
Types: PascalCase for interfaces/types in types/index.ts

Import/Export Patterns

Each feature directory includes an index.ts barrel file for clean exports:

// components/map/index.ts
export { MapView } from './MapView';
export { MapFilters } from './MapFilters';

// Usage elsewhere
import { MapView, MapFilters } from '@/components/map';

Page Structure

Pages in src/pages/ correspond to routes:

HomePage.tsx - Landing page
MapPage.tsx - Interactive map view
ReportFormPage.tsx - Report submission form
EventsPage.tsx - Event listing and management
AnalyticsPage.tsx - Analytics dashboard

All pages are exported through pages/index.ts for centralized route configuration.

Type Definitions

Centralized in src/types/index.ts:

Domain models (Report, Event, User)
DTOs (Data Transfer Objects)
Enums (LitterType, QuantityLevel, VerificationStatus)
API response types

Service Layer

Services in src/services/ handle external communication:

api.ts - Base API client with HTTP methods
reportService.ts - Report-related API calls
eventService.ts - Event-related API calls
analyticsService.ts - Analytics API calls
exifService.ts - EXIF metadata extraction

Hooks

Custom hooks in src/hooks/:

useAuth.ts - Authentication state and methods (Clerk wrapper)
useGeolocation.ts - Device geolocation access
Additional hooks as needed for shared logic

Utilities

Helper functions in src/utils/:

Coordinate validation
Distance calculations
File validation
Date formatting
Other pure utility functions

Styling Approach

Tailwind CSS for component styling
Utility classes directly in JSX
Global styles in index.css (minimal)
No CSS modules or styled-components

Authentication Pattern

Clerk handles all authentication
Use <SignedIn> and <SignedOut> components for conditional rendering
Use <ProtectedRoute> wrapper for authenticated pages
Access user with useUser() hook from Clerk

State Management

Local state: React useState for component-specific state
Server state: React Query for API data fetching/caching
Auth state: Clerk provider
No Redux or other global state libraries

3.7 KiB Raw Blame History