15-Phase Comprehensive Wiki & Documentation Plan

This plan outlines the creation of a high-fidelity, diagram-rich documentation site that acts as the "Source of Truth" for the Itinera platform. It is designed to be far more detailed than standard README files, utilizing Mermaid.js to provide visual architectures, sequence flows, and system maps.

Phase 1: Architecture & Data Flow (The Big Picture)

Goal: Establish the high-level relationship between the React frontend, Laravel backend, MySQL database, and third-party APIs (Paymob, AI providers).

Deliverables: High-level System Context Diagram, network boundaries, and technology stack breakdown.

Phase 2: Commerce & Checkout Engine

Goal: Document the exact step-by-step flow of a user initiating a checkout.

Deliverables: Sequence diagrams mapping CheckoutController -> CheckoutService -> OrderRepository -> PaymobGateway. Deep dive into the idempotency_key logic and reusable payment intents.

Phase 3: Webhooks & Asynchronous Fulfillment

Goal: Explain the non-blocking architecture for payment confirmation.

Deliverables: Flowcharts showing Paymob callbacks hitting WebhookController, HMAC SHA-512 validation, and the FulfillOrderListener idempotency guards preventing duplicate subscriptions.

Phase 4: Security Perimeter & Authentication

Goal: Map the defense layers (as shown in the showcase).

Deliverables: Diagrams of the JWT lifecycle (issuance, rotation, blacklisting), Spatie RBAC permission matrices, and Email Verification gates.

Phase 5: Database Schema & Entity Relationships

Goal: Visualize the data model.

Deliverables: Comprehensive Mermaid ERD (Entity-Relationship Diagram) linking Users, Orders, Payments, Subscriptions, and AI logs.

Phase 6: AI Quota & Telemetry Subsystems

Goal: Document the economics of AI consumption.

Deliverables: State machine diagrams for AiUsageService, detailing Cache::lock() concurrency guards, MD5 hashing, and the fallback mechanisms.

Phase 7: API Route Matrix & FormRequests

Goal: Detail the API surface area.

Deliverables: A visual tree of the 106 reconciled operations, mapping routes to their respective FormRequest validation envelopes and controllers.

Phase 8: Global Exception & Error Handling

Goal: Standardize the contract for failure.

Deliverables: Flow diagrams showing how bootstrap/app.php intercepts errors and forces them into the { success, message, data } format, including 422 field bags.

Phase 9: Frontend Ecosystem & State Management

Goal: Map the React SPA architecture.

Deliverables: Component trees, React Router v6 layouts, context providers, and data fetching lifecycles.

Phase 10: Design System & Component Library

Goal: Document the visual language.

Deliverables: Token definitions (--bp-wrap, --color-panel), typography scales, and responsive breakpoint strategies.

Phase 11: Interactive GSAP Animations

Goal: Deconstruct the showcase magic.

Deliverables: Logic maps of the scroll-scrubbed lifecycle engine, pinning mechanics, 3D CSS flip-cards, and headless/reduced-motion fallbacks.

Phase 12: Deployment & CI/CD Pipeline

Goal: Detail the path to production.

Deliverables: CI/CD pipeline diagrams showing GitHub Actions, static analysis, test runs, and Railway deployment steps.

Phase 13: Testing Strategies

Goal: Prove the platform's reliability.

Deliverables: Documentation of PHPUnit/Pest coverage, Vitest environments, mock structures for Paymob, and CI rate-limit tests.

Phase 14: Performance & Optimization

Goal: Highlight the speed characteristics.

Deliverables: Caching strategies (Redis), lazy loading techniques, SVG optimization, and DB indexing plans.

Phase 15: Developer Onboarding & Runbooks

Goal: Provide actionable guides for new contributors.

Deliverables: Local setup scripts, Laravel Tinker snippets, queue worker management, and standard troubleshooting logs.

15-Phase Comprehensive Wiki &amp; Documentation Plan

Phase 1: Architecture & Data Flow (The Big Picture)#

Phase 2: Commerce & Checkout Engine#

Phase 3: Webhooks & Asynchronous Fulfillment#

Phase 4: Security Perimeter & Authentication#

Phase 5: Database Schema & Entity Relationships#

Phase 6: AI Quota & Telemetry Subsystems#

Phase 7: API Route Matrix & FormRequests#

Phase 8: Global Exception & Error Handling#

Phase 9: Frontend Ecosystem & State Management#

Phase 10: Design System & Component Library#

Phase 11: Interactive GSAP Animations#

Phase 12: Deployment & CI/CD Pipeline#

Phase 13: Testing Strategies#

Phase 14: Performance & Optimization#

Phase 15: Developer Onboarding & Runbooks#