ErrandLink is a full-featured marketplace platform that connects people who need tasks completed with qualified service providers (runners). Built with modern technologies, it offers a seamless experience for posting tasks, applying for jobs, secure escrow payments, and real-time messaging.

# System Architecture

## Backend Architecture
- Framework: Laravel 11 (PHP 8.2+) with Eloquent ORM.
- API Design: RESTful API with versioned endpoints (`/api/v1`).
- Authentication: Laravel Sanctum for token-based authentication.
- Key Decisions: Stateless API, migration-based schema, Service Layer Pattern.

## Frontend Architecture
- Framework: React 19 with Vite, using React Router v7.
- State Management: TanStack Query, SettingsContext for global branding, AuthContext for auth.
- HTTP Client: Axios.
- Styling: Tailwind CSS with custom design system, dynamic primary color support via CSS variables.
- Real-time: Socket.IO for live updates.
- Internationalization (i18n): react-i18next with namespace-based translations (English, Spanish, French). Language resolution: localStorage override ? user preference ? site default ? fallback to English. LanguageSync component applies site default for guests, user preference synced on login/refresh.
- Key Decisions: Component-Based Architecture, Custom Design System, Environment-Aware Configuration, Dark Mode Support, Google OAuth Ready UI, reCAPTCHA Support, Dynamic Branding Context.

## UI/UX Decisions
- Dynamic Branding System: Fully functional across ALL pages, including dynamic application name, tagline, logo upload, site-wide primary color synchronization via CSS variables, dynamic hero templates (Default, Flicker, Gradient, Features, Solid Color), and dynamic favicon updates.
- Profile Page Enhancements: Primary color branding for cover photo placeholders, buttons, and skill tags.
- Admin Settings System: Customizable application name, tagline, primary color, hero style (5 templates), logo, and favicon. Changes reflect immediately via `SettingsContext` and `BrandingSync`.
- Global BrandingSync Component: Runs app-wide from `App.jsx`, updates title, favicon, and CSS color variables.
- Footer Static Pages: 7 public pages with primary color styling (About Us, Careers, Blog, Contact, Privacy Policy, Terms of Service, Safety).

## System Design Choices
- Real-time Communication: Socket.IO with Redis pub/sub for scalable messaging via a Node.js/Express WebSocket gateway.
- Data Storage: PostgreSQL for relational data, JSON columns, geospatial queries, and KYC data.
- Authentication & Authorization: Laravel Sanctum for token-based API authentication. Role-based access control (task_owner, runner, admin, escrow_manager) with middleware protection and optional KYC verification.
- Admin Support Messages: Role-based targeting (all users, task owners, runners, admins), message types (support, notification, alert), priority levels, and multi-channel delivery (email and/or in-app). Full CRUD operations.
- Announcements Management: Site-wide banner system with creation, editing, publishing, and deletion of announcements, audience targeting, and multiple display formats.
- Escrow Split Payment System: Automatic Stripe payment capture, platform fee calculation (configurable commission rate), fee breakdown modal, Stripe Connect Payouts, Paystack Transfer Recipients, and payout readiness validation.
- Payment History Page: Comprehensive transaction history with stats summary, status filters, transaction details, and dispute indicators.
- Dispute Resolution & Refund System: Allows task owners/runners to initiate disputes, notifies admins, processes actual refunds via Stripe/Paystack, and notifies both parties.
- Support Ticket System: Ticket-based support with categories, FAQ section, statuses (open, in_progress, resolved, closed), admin management, threaded replies, user/admin status notifications, closed ticket message blocking (admin can reopen), and real-time notification broadcasts when admin replies.
- KYC System: A 4-step wizard for Personal Info, Identity Verification, Address Verification, and Review, with progress tracking and secure document upload (PDF, JPG, JPEG, PNG, max 5MB).
- Registration Flow: Integrates KYC wizard if enabled, includes email verification, password validation, and age check (min 13 years old).
- Email Verification System: Token-based verification with `VerifyEmail.jsx` frontend component and backend validation.
- Maintenance Mode: `Maintenance.jsx` component with admin bypass, integrated into `App.jsx` via `MaintenanceCheck` wrapper.
- Admin Platform Payouts: Dashboard for managing platform fees, balance overview, Stripe integration, transaction history, and payout settings.
- Feature Toggles: Admin controls for KYC Verification, Google Sign-up/Sign-in, Google reCAPTCHA, Email Verification, New User Registrations, Maintenance Mode, Task Approval, and Default Language.
- Multi-Language Support: i18n with 8 namespaces (common, auth, tasks, notifications, support, admin, profile, payments) for English, Spanish, and French. User language preference stored in database (`users.language` column) and synced with frontend via API.
- Deployment Architecture: Leverages Replit's native environment (PHP 8.2, Node.js 20, PostgreSQL, Vite) for development and Replit deployment options for production.

# External Dependencies

## Payment Processing
- Stripe: For credit card payments (Stripe PHP SDK, Stripe.js, React Stripe Elements).
- Paystack: Alternative payment gateway, primarily for African markets.

## Mapping & Geolocation
- Google Maps API: For location services, map visualization, place autocomplete, and distance calculations (React Google Maps library).

## Authentication & OAuth
- Google OAuth: For sign-in/sign-up.
- Google reCAPTCHA: v3 integration for bot protection.

## Third-Party Services
- Redis: For caching and real-time messaging.
- Socket.IO: For WebSocket communication.

## HTTP Client Libraries
- Guzzle: PHP backend.
- Axios: JavaScript frontend.

## UI Component Libraries
- React Icons: For a consistent icon system.
- Tailwind CSS: For styling.

## Key Features

### For Task Owners
- Post Tasks - Create detailed task listings with location, budget, and requirements
- Review Applications - Browse runner profiles, ratings, and proposed prices
- Secure Payments - Escrow system protects both parties
- Real-time Messaging - Communicate directly with runners
- Track Progress - Monitor task status from start to completion

### For Runners
- Task Discovery - Find nearby tasks with location-based filtering
- Apply & Negotiate - Submit applications with custom pricing
- Build Reputation - Earn ratings and reviews
- Secure Payouts - Receive payments via Stripe Connect or Paystack
- Skill Matching - Get matched with tasks that fit your expertise

### For Administrators
- Dashboard Analytics - Track platform metrics and growth
- User Management - Manage users, roles, and suspensions
- Task Moderation - Approve/reject tasks before publication
- KYC Verification - Review identity verification documents
- Payment Management - Monitor escrow transactions and disputes
- Announcements - Broadcast site-wide notifications
- Support Tickets - Handle user support requests
- Platform Settings - Configure branding, features, and integrations

### Platform Features
- Multi-language Support - English, Spanish, French (i18n ready)
- Dark Mode - Full dark/light theme support
- Two-Factor Authentication - Google Authenticator 2FA
- Google OAuth - Sign in with Google
- reCAPTCHA v3 - Bot protection
- Email Verification - Secure registration flow
- Maintenance Mode - Admin-controlled downtime
- Dynamic Branding - Customize colors, logo, and tagline

### Docker Deployment (Recommended)
- Docker 20.10+
- Docker Compose 2.0+

### Manual Deployment
- PHP 8.2+
- Node.js 20+
- PostgreSQL 14+
- Redis 7+
- Composer 2.x
- NPM or Yarn

Ensure to update your .env files with corresponding information.