PROJECT OVERVIEW:
The application, named 'Mahalle Gözcüsü' (Neighborhood Watcher), aims to address growing public concern over pervasive surveillance technologies like Flock Safety's AI-powered license plate cameras. The core problem is the lack of transparency and citizen control regarding the deployment and data usage of these surveillance systems by municipalities and law enforcement. Mahalle Gözcüsü will provide a centralized platform for citizens to map existing surveillance infrastructure, access information about data privacy practices, engage in community discussions, and stay updated on relevant news and policy changes. The value proposition is empowering citizens with knowledge and community tools to understand, question, and potentially influence the use of surveillance technology in their neighborhoods, fostering greater transparency and protecting privacy rights.
TECH STACK:
- Frontend Framework: React (using Vite for fast development)
- Styling: Tailwind CSS for utility-first styling and rapid UI development
- State Management: Zustand for efficient global state management
- Routing: React Router DOM for client-side navigation
- Mapping Library: Leaflet with `react-leaflet` for interactive maps
- UI Components: Radix UI or similar for accessible and unstyled UI primitives
- Icons: Lucide React or Heroicons
- Data Fetching: React Query (TanStack Query) for managing server state, caching, and asynchronous operations
- Local Storage: Simple use of browser localStorage for user preferences or initial onboarding state
- Potential Backend (for future scaling, not MVP): Node.js/Express or NestJS with PostgreSQL/MongoDB, hosted on platforms like Vercel, Netlify, or AWS.
CORE FEATURES:
1. **Neighborhood Surveillance Map**:
* **User Flow**: User lands on the map view. Map displays pins representing known surveillance devices (e.g., ALPR cameras). Users can filter by device type, city, or date added. Clicking a pin reveals a popup with device details (type, installation date, known provider, reported data sharing status). Users can click an 'Add Device' button to open a modal for submitting new device information, including location (using map coordinates), device type, provider name, and optional notes. Submissions are initially flagged for moderation or appear as unverified until community consensus.
* **Details**: The map should be interactive, allowing zooming and panning. Initial data can be seeded with publicly available information or crowdsourced. Geocoding will be used to translate addresses to coordinates.
2. **Technology Information Hub**:
* **User Flow**: User navigates to the 'Info Hub' section. This section displays a list of surveillance technology providers (e.g., Flock Safety, Ring). Each provider has a dedicated page detailing their technology, reported data privacy policies, known partnerships with law enforcement/ICE, past controversies, and links to official documentation or news articles. Users can submit new information, corrections, or links via a form, which is then subject to a moderation or community approval process.
* **Details**: Content should be well-organized with clear headings, summaries, and source citations. Search functionality will be crucial here.
3. **Community Forum**:
* **User Flow**: User accesses the 'Forum' section. The forum is organized by topics or regions (e.g., 'General Discussion', 'Specific City Concerns', 'Legal Q&A'). Users can create new posts, reply to existing threads, upvote/downvote comments, and report inappropriate content. Each post/reply is associated with a user profile (can be anonymized).
* **Details**: Basic forum functionality including post creation, replies, threading, and moderation tools. Focus on fostering constructive discussion and organizing community action.
4. **News & Updates Feed**:
* **User Flow**: User visits the 'News' section. This feed aggregates recent news articles, official announcements from cities, and policy updates related to surveillance technology. Articles can be filtered by relevance or region. Each item includes a title, source, publication date, and a brief summary, with a link to the full article.
* **Details**: Requires integration with RSS feeds, news APIs, or manual curation.
UI/UX DESIGN:
- **Layout**: Single Page Application (SPA) layout. A persistent sidebar or top navigation bar for accessing the Map, Info Hub, Forum, and News sections. The main content area dynamically updates based on the selected section. Footer with links to About, Contact, Privacy Policy, Terms of Service.
- **Color Palette**: Primary: A calming, trustworthy blue (`#3b82f6`). Secondary: A neutral gray for backgrounds and borders (`#f3f4f6`, `#d1d5db`). Accent: A subtle green for success states or active elements (`#10b981`). Text: Dark gray (`#1f2937`). Use sufficient contrast for accessibility.
- **Typography**: A clean, readable sans-serif font family like Inter or Roboto. Clear hierarchy using font sizes and weights for headings, subheadings, and body text.
- **Responsive Design**: Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Map interactions optimized for touch. Forum and Info Hub content reflows gracefully. Ensure usability across devices (desktop, tablet, mobile).
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up routing and global layout.
- `Navigation.jsx`: Persistent sidebar/navbar component. Manages navigation state.
- `MapComponent.jsx`: Integrates Leaflet map. Displays markers, handles user interactions (click, zoom). Props: `markersData` (array of marker objects), `onMarkerClick` (function), `onAddDeviceClick` (function).
- `MarkerPopup.jsx`: Displays details when a map marker is clicked. Props: `markerData` (object).
- `AddDeviceForm.jsx`: Modal form for submitting new surveillance device information. Props: `onSubmit` (function), `onClose` (function).
- `InfoHub.jsx`: Container component for the technology information. Displays lists of providers or individual provider details.
- `ProviderProfile.jsx`: Displays detailed information about a specific surveillance provider. Props: `providerData` (object).
- `SubmissionForm.jsx`: Generic form for submitting updates to the Info Hub. Props: `onSubmit` (function), `formFields` (array).
- `CommunityForum.jsx`: Main forum component. Displays threads, handles filtering and sorting. Props: `posts` (array).
- `PostThread.jsx`: Displays a single forum post and its replies. Props: `postData` (object).
- `CreatePostForm.jsx`: Form for creating new forum posts. Props: `onSubmit` (function).
- `NewsFeed.jsx`: Displays the aggregated news articles. Props: `articles` (array).
- `NewsItem.jsx`: Displays a single news article summary. Props: `articleData` (object).
- `SearchBar.jsx`: Global search component.
- `FilterComponent.jsx`: For filtering map data or news.
- `LoadingSpinner.jsx`: Reusable loading indicator.
- `ErrorMessage.jsx`: Reusable error display component.
DATA MODEL:
- `Map Marker`: `{ id: string, lat: number, lng: number, type: 'ALPR' | 'CCTV' | 'Other', provider: string, addedBy: string, timestamp: string, notes?: string, verified: boolean }`
- `Surveillance Provider`: `{ id: string, name: string, description: string, privacyPolicyUrl?: string, dataSharingAgreements?: string, controversies?: string, newsLinks?: string[], submissionNotes?: string }`
- `Forum Post`: `{ id: string, title: string, content: string, authorId: string, timestamp: string, replies: ForumReply[], upvotes: number, downvotes: number, reported: boolean }`
- `Forum Reply`: `{ id: string, postId: string, content: string, authorId: string, timestamp: string, upvotes: number, downvotes: number, reported: boolean }`
- `News Article`: `{ id: string, title: string, url: string, source: string, publishedAt: string, summary: string }`
- `User (simplified)`: `{ id: string, username: string, role: 'user' | 'moderator' | 'admin' }`
State Management (Zustand Stores):
- `mapStore`: `markers: MapMarker[], filter: object, isLoading: boolean`
- `infoHubStore`: `providers: SurveillanceProvider[], currentProvider: SurveillanceProvider | null, isLoading: boolean`
- `forumStore`: `posts: ForumPost[], isLoading: boolean`
- `newsStore`: `articles: NewsArticle[], isLoading: boolean`
- `userStore`: `currentUser: User | null`
Mock Data Formats (Examples):
```json
// Map Marker Example
{
"id": "mkr_abc123",
"lat": 45.5152,
"lng": -122.6784,
"type": "ALPR",
"provider": "Flock Safety",
"addedBy": "user_xyz789",
"timestamp": "2024-05-10T14:30:00Z",
"notes": "Installed on corner of Oak St and Maple Ave.",
"verified": true
}
// Surveillance Provider Example
{
"id": "prov_flock",
"name": "Flock Safety",
"description": "Provides AI-powered license plate reading cameras for neighborhood and city surveillance.",
"privacyPolicyUrl": "https://www.flocksafety.com/privacy",
"dataSharingAgreements": "Law enforcement agencies can share data. Reports indicate potential backdoor access for federal agencies like ICE.",
"controversies": "Scrutiny over data privacy, data sharing with ICE, potential for mass surveillance.",
"newsLinks": ["link_to_article1", "link_to_article2"]
}
// Forum Post Example
{
"id": "post_def456",
"title": "Concerns about new cameras on Elm Street",
"content": "I noticed new cameras installed yesterday. Does anyone know who installed them and what their purpose is? Worried about privacy.",
"authorId": "user_abc123",
"timestamp": "2024-05-11T09:00:00Z",
"replies": [ /* array of ForumReply objects */ ],
"upvotes": 15,
"downvotes": 2,
"reported": false
}
// News Article Example
{
"id": "news_ghi789",
"title": "City Council votes to review ALPR contract with Flock Safety",
"url": "http://example.com/news/city_review",
"source": "Local Times",
"publishedAt": "2024-05-09T10:00:00Z",
"summary": "The City Council has decided to hold public hearings regarding the ongoing contract with Flock Safety due to citizen concerns."
}
```
ANIMATIONS & INTERACTIONS:
- **Map Markers**: Subtle pulse animation for unverified markers. Hover effect: slight scale increase and shadow on marker.
- **Buttons**: Smooth hover states (slight color change or scale). Click feedback (slight press down effect).
- **Forms**: Smooth transitions when modals appear/disappear. Input field focus states.
- **Loading States**: Use `LoadingSpinner` component with a subtle fade-in/out animation when data is being fetched. Skeleton loaders for list items (forum posts, news articles) before data arrives.
- **Page Transitions**: Smooth fade transitions between different sections/pages using React Router's `CSSTransition` or a similar library.
- **Micro-interactions**: Subtle animations on upvote/downvote buttons in the forum. Feedback on successful form submission (e.g., a temporary checkmark animation).
EDGE CASES:
- **Empty States**: For the map, info hub, forum, and news feed, display user-friendly messages and potentially calls to action (e.g., 'Be the first to add a device in your area', 'No news yet, check back later').
- **Error Handling**: Global error handling for API requests. Display user-friendly error messages via `ErrorMessage` component. Specific error messages for form validation failures.
- **Validation**: Client-side validation for all user input forms (map submissions, forum posts, info hub submissions). Required fields, valid data types (e.g., latitude/longitude for map coordinates), length limits.
- **Moderation**: Implement a system for reporting content (forum posts, map markers, info hub entries). Moderation queue for reviewing reported items and user submissions. Consider rate limiting for submissions to prevent abuse.
- **Accessibility (a11y)**: Ensure proper ARIA attributes, keyboard navigability (tab focus order), sufficient color contrast, and semantic HTML structure. `alt` text for relevant images.
- **Offline Support (Future Consideration)**: Basic offline access to previously viewed data or ability to queue submissions for when connectivity is restored.
DEPLOYMENT NOTES:
- **Build Tool**: Vite is recommended for its speed and ease of configuration.
- **Environment Variables**: Use `.env` files for API keys (e.g., map tile service, potential future backend URLs), feature flags. Prefix variables with `VITE_` for Vite.
- **Performance Optimizations**: Code splitting for different routes/sections. Lazy loading for components, especially map-related ones. Image optimization. Memoization (React.memo, useMemo, useCallback) to prevent unnecessary re-renders.
- **HTTPS**: Ensure the application is served over HTTPS.
- **CORS**: Configure backend CORS policies appropriately if a separate backend is implemented.
- **Robots.txt & Sitemap**: Standard SEO practices for discoverability.
- **Testing**: Implement unit tests (e.g., Vitest) and integration tests for core components and user flows.