# Boricua Artesanal — Full Application Codebase & Technical Architecture Analysis
> **System Document for Google NotebookLM, Gemini, Google Colab & AI Code Analysis Engines**
> **Repository ID**: `5a54257f-0ea0-4ce6-ac7e-56c9c651b1de`
> **Application Version**: 1.0.0
> **Target Platform**: Node.js / React 19 / Cloud Run / Firebase Firestore

---

## 1. Executive Summary & Domain Scope

**Boricua Artesanal** is a digital e-commerce marketplace dedicated to authentic Puerto Rican handcrafts ("artesanias boricuas"), connecting local artisans from Arecibo, San Juan, Ponce, and the wider Puerto Rican archipelago with local buyers and the global diaspora.

### Core Objectives & Capabilities
1. **Curated Handcraft Catalog**: Showcases authentic handmade crafts including Wooden Santos, Vejigante masks, Mundillo lace, handcrafted ceramics, jewelry, hammocks, and gourmet coffee.
2. **Interactive 360° Product Viewer**: Allows buyers to inspect 3D/rotational handcrafted details in real time.
3. **Multi-Channel Payment Gateways**:
   - **ATH Móvil**: Popular Puerto Rican instant mobile transfer method with manual phone verification and reference tracking.
   - **PayPal Express Checkout**: Full server-side OAuth2 authentication and payment capture via Express proxy endpoints (`/api/orders`, `/api/orders/:orderId/capture`).
   - **Stripe Credit Card**: Credit & debit card processing.
4. **Satellite Order Tracking Logbook**: Real-time USPS/Postal tracking timeline simulation with checkpoint logs, tracking numbers, and local workshop pickup options.
5. **Bilingual i18n Architecture**: Native Spanish and English language context (`LanguageContext.tsx`) covering UI labels, search categories, email summaries, PDF receipts, and breadcrumb navigation.
6. **PDF Receipt & Print Engine**: High-fidelity client-side PDF document generation using jsPDF (`pdfGenerator.ts`) and custom printer CSS layouts (`printHelper.ts`).
7. **Cloud Firestore Sync**: Real-time order persistence, stock inventory adjustments, customer product review creation, and administrative role assignment.
8. **Admin Operations Panel**: Real-time dashboard for managing product inventory, updating order statuses, viewing sales analytics with Recharts, and role management.
9. **AI Assistant Floating Chatbot**: Natural language shopping assistant ("Boricua Assistant") guiding users through product selections and artisan heritage.

---

## 2. Technology Stack Matrix

| Layer | Technology / Library | Purpose |
| :--- | :--- | :--- |
| **Frontend Framework** | React 19, TypeScript 5.8 | Component architecture and type safety |
| **Build Tooling** | Vite 6, tsx, esbuild | Hot development server and CommonJS production bundle compilation |
| **Styling** | Tailwind CSS v4, Lucide React | Modern utility styling and icon set |
| **Animations** | Motion (`motion/react`) | Fluid route transitions and UI component micro-interactions |
| **Database & Auth** | Firebase 12 (Cloud Firestore & Auth) | User accounts, Google SSO, persistent real-time database |
| **Server Engine** | Express 4 (Node.js 22) | Full-stack API proxy, static asset server, dynamic sitemap generation |
| **Charts & Analytics** | Recharts 3 | Admin dashboard financial & inventory data visualization |
| **PDF Generation** | jsPDF 4 | Vector PDF purchase receipt compiler |
| **Localization** | Custom React Context (`useLanguage`) | Zero-dependency runtime Spanish/English i18n switcher |

---

## 3. Project File Tree & Component Directory

```
├── server.ts                             # Express full-stack server & PayPal OAuth/Capture API routes
├── package.json                          # Dependencies and build scripts
├── vite.config.ts                        # Vite configuration with Tailwind CSS plugin
├── metadata.json                         # Platform frame permissions and capabilities
├── public/
│   ├── llms.txt                          # AI system summary index
│   ├── llms-full.txt                     # Exhaustive codebase documentation (this file)
│   ├── codebase-analysis.md              # Google NotebookLM direct ingestion markdown source
│   ├── robots.txt                        # Search engine and AI crawler directives
│   ├── sitemap.xml                       # Dynamic catalog XML sitemap
│   └── firebase-messaging-sw.js          # Service worker for push notifications
├── src/
│   ├── main.tsx                          # React DOM entry point
│   ├── App.tsx                           # Root application component & view router state
│   ├── index.css                         # Tailwind CSS global import rules
│   ├── types.ts                          # Centralized TypeScript interfaces and enums
│   ├── firebase.ts                       # Firebase app initialization & auth exports
│   ├── firebase-applet-config.json       # Project-specific Firestore project credentials
│   ├── components/
│   │   ├── AdminPanel.tsx                # Inventory, order management, sales charts, role manager
│   │   ├── Breadcrumbs.tsx               # Dynamic schema-structured breadcrumb navigation
│   │   ├── CartView.tsx                  # Shopping cart overview, quantity controls & checkout trigger
│   │   ├── FloatingChat.tsx              # Gemini AI shopping assistant modal
│   │   ├── NewsletterForm.tsx            # Diaspora newsletter & discount subscriber
│   │   ├── OrderEmailModal.tsx           # Printable/copyable confirmation email preview
│   │   ├── OrderHistory.tsx              # User order history with PDF export and tracking buttons
│   │   ├── OrderTracker.tsx              # Satellite tracking timeline & status update simulator
│   │   ├── PayPalDiagnosticPanel.tsx     # OAuth/API diagnostic widget for PayPal integration
│   │   ├── Product360Viewer.tsx          # Interactive 3D rotational canvas for handcrafted goods
│   │   ├── ProductCard.tsx               # Product card with wishlisting, rating stars, & quick add
│   │   ├── ProductReviewsSection.tsx     # Rating submission form & verified buyer reviews
│   │   ├── Recommendations.tsx           # Related artisan products recommendation bar
│   │   ├── RouteMetadata.tsx             # Helmet dynamic head title and canonical SEO updater
│   │   └── WishlistView.tsx              # Saved favorite items gallery
│   ├── context/
│   │   └── LanguageContext.tsx           # Bilingual translation dictionary and language hook
│   ├── data/
│   │   └── products.ts                   # Initial seed inventory dataset with artisan details
│   ├── services/
│   │   ├── db.ts                         # Cloud Firestore CRUD operations (orders, products, reviews)
│   │   ├── emailService.ts               # Simulated confirmation email delivery dispatch
│   │   └── messaging.ts                  # Push notification service helper
│   └── utils/
│       ├── crypto.ts                     # Local data encryption helper
│       ├── pdfGenerator.ts               # jsPDF vector document compiler for purchase receipts
│       ├── printHelper.ts                # Printer-friendly HTML invoice window builder
│       ├── seo.ts                        # SEO helper utilities
│       └── translationHelper.ts          # Tracking checkpoint description translator
```

---

## 4. Complete Data Schemas & TypeScript Definitions (`src/types.ts`)

```typescript
export enum OrderStatus {
  PLACED = "Entregado a Taller",
  PROCESSING = "En Confección / Empaque",
  SHIPPED = "Despachado / En Tránsito",
  DELIVERED = "Entregado",
  CANCELLED = "Cancelado"
}

export interface TrackingCheckpoint {
  status: OrderStatus;
  timestamp: string;
  description: string;
  location?: string;
}

export interface ProductReview {
  id: string;
  productId: string;
  userId: string;
  userName: string;
  rating: number; // 1 to 5
  comment: string;
  createdAt: string;
}

export interface Product {
  id: string;
  name: string;
  price: number;
  category: string;
  description: string;
  artisan: string;
  region: string;
  rating: number;
  reviewsCount: number;
  images: string[];
  stock: number;
  active?: boolean;
  featured?: boolean;
  dimensions?: string;
  materials?: string[];
  has360View?: boolean;
}

export interface CartItem {
  product: Product;
  quantity: number;
  selectedSize?: string;
  selectedColor?: string;
}

export interface Order {
  id: string;
  userId?: string;
  userEmail: string;
  items: CartItem[];
  totalAmount: number;
  paymentMethod: "athmovil" | "paypal" | "stripe";
  paymentStatus: "pending" | "completed" | "failed";
  shippingAddress: {
    name: string;
    street: string;
    city: string;
    zipCode: string;
    phone: string;
  };
  shippingMethod?: "postal" | "pickup";
  trackingNumber: string;
  orderStatus: OrderStatus;
  trackingHistory: TrackingCheckpoint[];
  createdAt: string;
  updatedAt?: string;
}

export interface UserProfile {
  uid: string;
  email: string;
  displayName?: string;
  role: "customer" | "admin" | "artisan";
  createdAt: string;
}
```

---

## 5. Backend Server & Express API Architecture (`server.ts`)

The backend is built as a full-stack Express server that serves both runtime API proxies and static assets.

### Key Server Endpoints:
1. `GET /api/config/paypal`:
   - Returns client-safe PayPal Client ID and configured environment mode (`live` vs `sandbox`).
2. `POST /api/orders`:
   - Authenticates server-to-server with PayPal OAuth2 token endpoint (`/v1/oauth2/token`) using Client ID & Client Secret.
   - Creates a checkout order via PayPal REST API v2 (`/v2/checkout/orders`).
3. `POST /api/orders/:orderId/capture`:
   - Captures authorized payment for the specified order ID (`/v2/checkout/orders/:id/capture`).
4. `GET /sitemap.xml`:
   - Queries Cloud Firestore REST API dynamically for active product catalog IDs and renders a valid XML sitemap.
5. `GET /llms.txt`, `GET /llms-full.txt`, `GET /codebase-analysis.md`:
   - Direct text/markdown endpoints for Google NotebookLM, Gemini, and search crawlers.
6. `GET /api/notebook-export`:
   - Returns full JSON representation of system architecture, product count, available languages, and database schemas for programmatic notebook analysis in Python / Google Colab.

---

## 6. Key Frontend Features & Subsystems

### A. Dual Language i18n Architecture (`LanguageContext.tsx`)
- Provides `useLanguage()` hook returning current `language` ("es" | "en"), `setLanguage`, and translation helper `t(key)`.
- Over 200 localized key-value pairs covering cart totals, checkout modals, tracking statuses, email summaries, and admin controls.
- Automatic fallback mechanisms ensuring smooth UI rendering regardless of selected locale.

### B. High-Fidelity PDF Receipt Generation (`src/utils/pdfGenerator.ts`)
- Uses `jsPDF` to compile clean vector-graphic PDF receipts.
- Includes merchant header ("BORICUA ARTESANAL - Arecibo, Puerto Rico"), order ID, timestamp, itemized breakdown table, IVU tax (11.5% Puerto Rico Sales Tax), shipping totals, payment method, and cultural appreciation footer.
- Fully respects current selected language (Spanish or English) when building document labels.

### C. Real-Time Order Tracking & Logbook (`src/components/OrderTracker.tsx`)
- Renders an interactive satellite logbook tracking USPS postal transit or local workshop pickup.
- Provides status badges, timestamped checkpoint timeline, and administrative simulation triggers.

### D. Cloud Firestore Database Operations (`src/services/db.ts`)
- Synchronizes orders, stock levels, reviews, and user profiles directly with Cloud Firestore.
- Handles real-time collection queries, document updates, and fallback local state persistence when offline.

---

## 7. Instructions for Google NotebookLM Ingestion

To analyze this codebase in **Google NotebookLM**:
1. Open [NotebookLM](https://notebooklm.google.com/).
2. Create a new notebook titled **"Boricua Artesanal Architecture Analysis"**.
3. Under **Sources**, select **Website URL** and paste:
   `https://<your-app-domain>/llms-full.txt` or `https://<your-app-domain>/codebase-analysis.md`
   *(Or click "Upload Document" and upload `public/codebase-analysis.md` directly)*.
4. Ask NotebookLM questions such as:
   - *"Explain how payment flows work across ATH Movil, PayPal, and Stripe."*
   - *"Summarize the internationalization (i18n) setup in LanguageContext.tsx."*
   - *"Analyze the Cloud Firestore data model for Orders and Products."*
   - *"Draft a technical audit report of the PDF receipt generator and print helper."*

---
*Generated automatically by Boricua Artesanal Architecture Engine.*