# ProfitPDF - Full Technical Architecture Sheet

This document is a comprehensive, machine-readable guide designed for AI agents and developer scrapers. It covers the full technical specs, backend API endpoints, database structures, and prompt flows of the ProfitPDF platform.

---

## 1. Core System Architecture

ProfitPDF runs a hybrid server-client architecture optimized for high performance, server-side secret management, and fluid client-side rendering.

```
       +---------------------------------------------+
       |             Client-Side (React)             |
       |  - WYSIWYG Editor    - Local State (Zustand)|
       |  - Canvas Preview    - Document (jspdf)     |
       +---------------------------------------------+
                              |
                     REST APIs (JSON)
                              |
                              v
       +---------------------------------------------+
       |         Custom Express Node.js Server       |
       |  - Gemini Wrapper    - PayPal Gateway       |
       |  - Etsy Scraper      - SMTP Support Ticket  |
       +---------------------------------------------+
                              |
                +-------------+-------------+
                |                           |
                v                           v
       +-----------------+         +-----------------+
       |  Google Gemini  |         |    Firestore    |
       |   (AI Engine)   |         |   (DB Store)    |
       +-----------------+         +-----------------+
```

---

## 2. API Contract & Endpoints

### CONTACT & SUPPORT TICKET DISPATCH
- **Path**: `POST /api/support`
- **Payload**:
  ```json
  {
    "name": "string (optional)",
    "email": "string (required)",
    "subject": "string (optional)",
    "message": "string (required)"
  }
  ```
- **Response**:
  ```json
  {
    "success": true,
    "message": "Your message has been successfully received and is being processed in the background!",
    "info": "SMTP email delivery is running in the background."
  }
  ```
- **Behavior**: This endpoint responds immediately to prevent HTTP timeouts. It runs the SMTP connection verification and delivery asynchronously in a background worker pool with strict connection (5s), greeting (5s), and hard execution (10s) timeout safeguards.

### GEMINI WORKBOOK BLUEPRINT GENERATION
- **Path**: `POST /api/generate/workbook`
- **Payload**:
  ```json
  {
    "topic": "string (required)",
    "niche": "string (optional)",
    "style": "string (optional)"
  }
  ```
- **Response**:
  ```json
  {
    "success": true,
    "document": {
      "title": "string",
      "pages": [
        {
          "pageNumber": 1,
          "title": "string",
          "sections": [
            {
              "heading": "string",
              "body": "string",
              "elements": ["string"]
            }
          ]
        }
      ]
    }
  }
  ```

### ETY TRENDS SCANNER
- **Path**: `GET /api/trends`
- **Query Params**: `q=string`
- **Response**:
  ```json
  {
    "success": true,
    "keyword": "string",
    "searchVolume": 12400,
    "competitionLevel": "Medium",
    "suggestedPrice": 12.99,
    "bestsellingProducts": [
      {
        "title": "string",
        "price": 14.99,
        "rating": 4.8,
        "salesEst": 540
      }
    ]
  }
  ```

---

## 3. Database Schema Layout

All user state and token transactions are persisted in Firestore under specific collection references:

### Users Collection (`/users/{uid}`)
```json
{
  "uid": "string",
  "email": "string",
  "displayName": "string",
  "tokens": 60,
  "createdAt": "timestamp",
  "planType": "free | basic | enterprise"
}
```

### Documents Collection (`/documents/{docId}`)
```json
{
  "docId": "string",
  "ownerUid": "string",
  "title": "string",
  "niche": "string",
  "pages": [
    {
      "pageNumber": 1,
      "title": "string",
      "content": "string"
    }
  ],
  "styling": {
    "primaryColor": "string",
    "secondaryColor": "string",
    "headingFont": "string",
    "bodyFont": "string"
  },
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}
```

### Transactions Collection (`/transactions/{txId}`)
```json
{
  "transactionId": "string",
  "uid": "string",
  "amount": "number",
  "currency": "USD",
  "tokenCount": "number",
  "status": "COMPLETED | PENDING | FAILED",
  "paymentProvider": "paypal",
  "timestamp": "timestamp"
}
```

---

## 4. Key Client-Side Workflows

### Standard PDF Generation (jsPDF)
Client pages are designed inside standard DOM nodes, which are then parsed and injected into a client-side document context.
1. The WYSIWYG editor maintains page layout states.
2. `html-to-image` captures custom rendered cover pages or graphics as base64 images.
3. `jspdf` generates high-resolution vector pages.
4. Images and text nodes are dynamically positioned, avoiding overlaps.
5. Outbound export triggers:
   ```javascript
   const doc = new jsPDF({ orientation: "p", unit: "pt", format: "a4" });
   ```

### State Coordination
All active state elements—including user token updates, active templates, generated keywords, and Etsy mockup variables—are synchronized down to the UI components through standard React State hooks and Firestore real-time snapshots.