# Boricua Artesanal - E-Commerce Handcrafts Marketplace
> Complete application documentation and system overview optimized for Google NotebookLM, Gemini, and AI Model Analysis.

## Overview
Boricua Artesanal is a full-stack, authentic Puerto Rican handcraft e-commerce platform built with React 19, TypeScript, Express, Vite, and Cloud Firestore. It supports multi-currency/payment workflows (ATH Móvil, PayPal Express Checkout, Stripe), real-time order tracking with satellite checkpoints, bilingual (ES/EN) i18n context, dynamic PDF invoice generation, product 360-degree interactive viewing, custom artisan reviews, and an administrative panel.

## Core Documentation & Product Feeds
- [Full Codebase & Architecture Specification](llms-full.txt): Comprehensive source code breakdown, data models, component trees, and logic rules for NotebookLM ingestion.
- [Notebook Analysis Source Document](codebase-analysis.md): Formatted specifically for direct upload into Google NotebookLM sources.
- [Dynamic XML Sitemap](sitemap.xml): Full catalog and route index for web crawlers.
- [Google Merchant Center CSV Feed](csv/google_merchant_center.csv): Real-time product feed formatted for Google Shopping and Google Merchant Center.
- [Google Sheets Inventory CSV](csv/inventario_google_sheets.csv): Synced inventory table for automated audits and inventory evaluation.
- [Live Catalog JSON](productos.json): Complete machine-readable catalog with prices, stock, artisan credits, and high-resolution photo galleries.

## Key Subsystems & Architecture
- **Frontend Framework**: React 19 + TypeScript + Vite + Tailwind CSS v4.
- **Backend API**: Express server running on Node.js / tsx with esbuild CommonJS compilation for Cloud Run containers.
- **Database**: Firebase Cloud Firestore with REST & Web SDK real-time sync.
- **Authentication**: Firebase Auth with Google Single Sign-On (SSO) and custom email/password authentication modes.
- **Payment Processing**:
  - ATH Móvil (Direct Puerto Rico transfer validation & auto-verification).
  - PayPal Express Checkout (Server-to-Server REST OAuth2 token exchange and capture endpoint proxy).
  - Stripe Credit Card Integration.
- **Order Tracking & Logistics**: Real-time satellite-simulated USPS checkpoint timeline with local workshop pickup options.
- **Internationalization (i18n)**: React Context-driven dual-language dictionary (`LanguageContext.tsx`) supporting instant toggling between Spanish and English for all UI elements, breadcrumbs, receipts, and order statuses.
- **Document & Print Generation**: Client-side jsPDF receipt generator (`pdfGenerator.ts`) and responsive HTML print dialogs (`printHelper.ts`).
- **AI Floating Assistant**: Integrated conversational assistant (`FloatingChat.tsx`) powered by Google Gemini API.

## API Endpoints
- `GET /llms.txt` - System summary for AI models.
- `GET /llms-full.txt` - Full codebase & document for NotebookLM ingestion.
- `GET /codebase-analysis.md` - Dedicated markdown source for NotebookLM upload.
- `GET /sitemap.xml` - Dynamic catalog XML sitemap.
- `GET /api/config/paypal` - Dynamic PayPal client ID & environment configuration.
- `POST /api/orders` - PayPal order creation proxy.
- `POST /api/orders/:orderId/capture` - PayPal order capture proxy.
- `GET /api/notebook-export` - Codebase JSON export for notebooks and data science scripts.