FixHoumti - Community Issue Reporting Platform

A modern, open-source platform for community-driven issue reporting and resolution. Built for Morocco with full Arabic support and RTL layout.

Demo: https://fixhoumti.vercel.app/

📸 Screenshots

Report an issue

Create Report - Step 1	Create Report - Step 2

Report Report details

Create Report - Step 3	View Report - Desktop

Interactive Map & Browse Views

Desktop view - Home	Mobile View - Home

Moderation Dashboard & Categories

Mobile View - Explore reports	Mobile View - Report details

🌟 Features

Core Functionality

• 📝 Anonymous Reporting: Report issues without creating an account
• 🗺️ Interactive Map: Visualize reports on an interactive Leaflet map
• 🔍 Advanced Filtering: Filter by category, status, location, and time period
• 👍 Community Support: Upvote, downvote, and corroborate reports
• 💡 Proposed Solutions: Community can propose and vote on solutions
• 🚩 Moderation System: Flag inappropriate content for review
• 🌐 Bilingual: Full support for English and Arabic with RTL layout

Technical Features

• 🔐 Security: Cloudflare Turnstile verification, rate limiting, RLS policies
• 📱 Responsive: Mobile-first design with optimized layouts
• ⚡ Performance: Optimized database queries, caching, and infinite scroll
• 🎨 Modern UI: Built with Tailwind CSS and Shadcn/ui components
• 🌍 Geospatial: PostGIS for location-based queries and spatial indexing
• 🔄 Real-time: Live updates and dynamic status calculations
• ♿ Accessible: WCAG compliant with proper semantic HTML

🚀 Tech Stack

• Framework: Next.js 15 with App Router
• Database: Supabase (PostgreSQL with PostGIS)
• Authentication: Supabase Auth
• Storage: Supabase Storage (S3-backed)
• Styling: Tailwind CSS
• UI Components: Shadcn/ui
• Maps: Leaflet.js
• i18n: next-intl
• Security: Cloudflare Turnstile
• Deployment: Vercel

📋 Prerequisites

• Node.js 18+ and npm/yarn/pnpm
• Supabase account and project
• Cloudflare Turnstile site key (for bot protection)
• Vercel account (for deployment)

🛠️ Installation

1. Clone the Repository

git clone https://github.com/anasbelmadani/fixhoumti.git
cd fixhoumti

2. Install Dependencies

npm install
# or
yarn install
# or
pnpm install

3. Set Up Supabase

1. Create a new Supabase project at supabase.com

2. Run all SQL migrations in the sql/ directory in order:

   • init-schema.sql - Core database schema
   • add-rls-policies.sql - Row Level Security policies
   • add-indexes.sql - Performance indexes
   • add-functions.sql - Database functions
   • Additional migration files as needed

3. Enable PostGIS extension in Supabase:

   CREATE EXTENSION IF NOT EXISTS postgis;

4. Set up Supabase Storage bucket:

   • Create a bucket named report-media
   • Configure policies (see sql/storage-policies.sql)

4. Configure Environment Variables

Create a .env.local file in the root directory:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Cloudflare Turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_turnstile_site_key
TURNSTILE_SECRET_KEY=your_turnstile_secret_key

# Security
IP_HASH_SECRET=your_random_secret_for_ip_hashing

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development

5. Run Database Migrations

# Run each SQL file in Supabase SQL Editor in this order:
1. sql/init-schema.sql
2. sql/add-rls-policies.sql
3. sql/add-indexes.sql
4. sql/add-functions.sql
5. sql/add-filtered-reports-function.sql
6. sql/add-nearby-reports-function.sql
7. sql/add-paginated-reports-function.sql
8. sql/storage-policies.sql

6. Run Development Server

npm run dev
# or
yarn dev
# or
pnpm dev

Open http://localhost:3000 in your browser.

📁 Project Structure

with-supabase-app/
├── app/                      # Next.js App Router
│   ├── [locale]/            # Localized routes (en, ar)
│   │   ├── admin/           # Admin dashboard
│   │   ├── auth/            # Authentication pages
│   │   ├── browse/          # Browse reports page
│   │   ├── categories/      # Categories page
│   │   ├── explore/         # Map exploration page
│   │   ├── legal/           # Legal pages (privacy, terms, etc.)
│   │   ├── moderator/       # Moderator dashboard
│   │   ├── report/          # Report pages
│   │   │   └── [id]/        # Individual report details
│   │   └── page.tsx         # Home page
│   └── api/                 # API routes
│       ├── admin/           # Admin APIs
│       ├── moderation/      # Moderation APIs
│       ├── reports/         # Report APIs
│       └── solutions/       # Solutions APIs
├── components/              # React components
│   ├── admin/              # Admin components
│   ├── categories/         # Category components
│   ├── layout/             # Layout components (nav, footer)
│   ├── legal/              # Legal page components
│   ├── map/                # Map components
│   ├── media/              # Media handling components
│   ├── moderation/         # Moderation components
│   ├── reports/            # Report components
│   ├── search/             # Search components
│   ├── security/           # Security components (Turnstile)
│   └── ui/                 # Shadcn/ui components
├── lib/                    # Utility libraries
│   ├── queries/            # Database query functions
│   ├── storage/            # Storage utilities
│   ├── supabase/           # Supabase client setup
│   └── utils/              # Helper utilities
├── messages/               # i18n translation files
│   ├── en.json            # English translations
│   ├── ar.json            # Arabic translations
│   └── ...                # Locale-specific files
├── public/                 # Static assets
│   └── legal/             # Legal page markdown files
├── sql/                    # Database migrations
└── i18n/                   # i18n configuration

🔧 Configuration

Localization

The platform supports English (en) and Arabic (ar) locales. To add a new locale:

1. Add locale to i18n/request.ts
2. Create translation file in messages/[locale].json
3. Add font support in app/[locale]/layout.tsx if needed

Categories

Categories are stored in the categories table. To add new categories:

INSERT INTO categories (name, color, icon) 
VALUES ('Category Name', '#HEX_COLOR', 'icon-name');

Status Thresholds

Automatic status transitions are configured in the status_thresholds table:

-- Example: Move to "acknowledged" after 10 upvotes
INSERT INTO status_thresholds (status, min_upvotes)
VALUES ('acknowledged', 10);

👥 User Roles

The platform supports three user roles:

1. Anonymous: Can report, vote, flag, and propose solutions
2. Moderator: Can review flagged content and edit reports
3. Admin: Full system access, manage users and roles

To assign roles, update the user_roles table in Supabase.

🔒 Security

Authentication

• Email/password authentication via Supabase Auth
• Anonymous users tracked via browser fingerprinting
• Row Level Security (RLS) policies on all tables

Bot Protection

• Cloudflare Turnstile verification required for:
  • Report creation
  • Solution submission
  • Voting actions

Rate Limiting

• IP-based rate limiting for submissions
• Configurable cooldown periods

Content Security

• EXIF data stripped from uploaded images
• File type and size validation
• Moderator review system for flagged content

📊 Database Schema

Key tables:

• reports: Main report data with PostGIS location
• report_support: Upvotes, downvotes, corroborations
• solutions: Community-proposed solutions
• solution_votes: Votes on solutions
• categories: Issue categories
• flags: Content moderation flags
• user_roles: User role assignments
• moderation_actions: Audit log for moderator actions

🚀 Deployment

Vercel Deployment

1. Push code to GitHub
2. Import project in Vercel
3. Add environment variables in Vercel dashboard
4. Deploy

# Or use Vercel CLI
vercel --prod

Environment Setup

• Ensure all environment variables are set in Vercel
• Update NEXT_PUBLIC_APP_URL to your production URL
• Configure custom domain if needed

🧪 Testing

# Run type checking
npm run type-check

# Run linting
npm run lint

# Build for production
npm run build

📝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Code Style

• Use TypeScript for type safety
• Follow existing code patterns
• Add comments for complex logic
• Keep components focused and reusable

📄 License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🙏 Acknowledgments

• Built with Next.js
• Database powered by Supabase
• Maps by Leaflet
• UI components from Shadcn/ui
• Security by Cloudflare Turnstile

📞 Support

For questions, issues, or feature requests, please open an issue on GitHub.

---

Note: This is a community-driven platform designed for civic engagement. It is not an emergency service and should not be used for urgent situations requiring immediate response. Always contact local authorities for emergencies.