# goncy/next-mercadopago architecture

> Architecture diagram of the GitHub repository goncy/next-mercadopago, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/goncy/next-mercadopago
- Repository: https://github.com/goncy/next-mercadopago

## Overview

##### Project Type and Purpose
- This is a multi‑sample full‑stack Next.js repository demonstrating five different Mercado Pago payment integrations (“Checkout Pro”, “Suscripciones”, “Checkout Bricks”, “Marketplace”, “Checkout API”).
- Each integration lives under `integraciones/<integration‑name>` as its own Next.js App Router project: it contains both the React frontend (pages/components) and the Node.js backend (API routes and local SQLite DB).
- The `configuracion` folder holds developer setup docs (cloning, creating apps in Mercado Pago, test credentials, webhook tunneling).

##### High‑Level Components
- For each integration:
- Browser Client (React pages in `src/app`)
- Next.js Server (App Router handling server components and API routes under `src/app/api/.../route.ts`)
- Local Database (SQLite files in `db/`, e.g. `message.db`, `user.db`)
- External Service (Mercado Pago REST APIs: payment preference endpoints, subscription APIs, Connect/Marketplace)
- Webhook Tunnel (ngrok/localtunnel to expose a public URL for Mercado Pago → Next.js webhook route)

##### Component Interactions (Generic Flow)
a. Client navigates to the React page (`GET /`) and triggers a payment action (e.g. “Pay to add message”).
b. React frontend calls a Next.js server action or API route (`POST /api/create-preference` or similar)
c. Server uses Mercado Pago SDK or HTTP API to create a payment preference / subscription plan / checkout form
d. Client is redirected to Mercado Pago or renders a Bricks widget / Checkout API component
e. User completes payment/subscription on Mercado Pago
f. Mercado Pago sends a webhook notification to the publicly exposed webhook endpoint (`POST /api/mercadopago/route.ts`)
g. Next.js webhook handler verifies the notification, updates the SQLite DB (marks message as paid/persist subscription)
h. Client polls or navigates back to see the updated message list (`GET /api/messages` → SQL query → JSON response)

##### Important Architectural Patterns and Variations
- The “Marketplace” integration adds a second database or schema (e.g. `user.db`) to represent payers vs. wall owners, and uses Mercado Pago Connect to split payments.
- “Suscripciones” uses recurring Webhooks and subscription‑specific endpoints rather than single‑payment preferences.
- “Checkout Bricks” embeds Mercado Pago’s frontend SDK inside your React app; the server still exposes an endpoint to fetch a payment token.
- “Checkout API” uses Mercado Pago’s React component library for fully custom UI; server only provides tokens and receives webhooks.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Developer Workspace"
    DOCS["Developer Documentation"]:::docs
    subgraph "integraciones"
      subgraph "Checkout Pro"
        CP_Client["Browser Client"]:::client
        CP_Server["Next.js Server"]:::server
        CP_DB["SQLite DB"]:::db
        CP_Public["Webhook Tunnel (ngrok)"]:::tunnel
        CP_MP["Mercado Pago Service"]:::external
        CP_Client -->|"GET /"| CP_Client
        CP_Client -->|"POST /api/create-preference"| CP_Server
        CP_Server -->|"HTTPS API"| CP_MP
        CP_Client -->|"Redirect to mpago.com"| CP_MP
        CP_MP -.->|"Webhook POST"| CP_Public
        CP_Public -->|"POST /api/mercadopago/route"| CP_Server
        CP_Server -->|"DB write"| CP_DB
        CP_Client -->|"GET /api/messages"| CP_Server
        CP_Server -->|"SQL query"| CP_DB
      end
      subgraph "Suscripciones"
        SU_Client["Browser Client"]:::client
        SU_Server["Next.js Server"]:::server
        SU_DB["SQLite DB"]:::db
        SU_Public["Webhook Tunnel (ngrok)"]:::tunnel
        SU_MP["Mercado Pago Service"]:::external
        SU_Client -->|"POST /api/create-subscription"| SU_Server
        SU_Server -->|"HTTPS API"| SU_MP
        SU_MP -.->|"Webhook POST"| SU_Public
        SU_Public -->|"POST /api/mercadopago/route"| SU_Server
        SU_Server -->|"DB write"| SU_DB
        SU_Client -->|"GET /api/messages"| SU_Server
        SU_Server -->|"SQL query"| SU_DB
      end
      subgraph "Checkout Bricks"
        CB_Client["Browser Client"]:::client
        CB_Server["Next.js Server"]:::server
        CB_DB["SQLite DB"]:::db
        CB_Public["Webhook Tunnel (ngrok)"]:::tunnel
        CB_MP["Mercado Pago Service"]:::external
        CB_Client -->|"GET token /api/token"| CB_Server
        CB_Server -->|"HTTPS API"| CB_MP
        CB_Client -->|"Bricks widget"| CB_MP
        CB_MP -.->|"Webhook POST"| CB_Public
        CB_Public -->|"POST /api/mercadopago/route"| CB_Server
        CB_Server -->|"DB write"| CB_DB
        CB_Client -->|"GET /api/messages"| CB_Server
        CB_Server -->|"SQL query"| CB_DB
      end
      subgraph "Marketplace"
        MP_Client["Browser Client"]:::client
        MP_Server["Next.js Server"]:::server
        MP_DB1["message.db"]:::db
        MP_DB2["user.db"]:::db
        MP_Public["Webhook Tunnel (ngrok)"]:::tunnel
        MP_Connect["Connect Endpoint"]:::server
        MP_MP["Mercado Pago Service"]:::external
        MP_Client -->|"POST /api/create-preference"| MP_Server
        MP_Server -->|"HTTPS API"| MP_MP
        MP_Client -->|"Redirect to mpago.com"| MP_MP
        MP_MP -.->|"Webhook POST"| MP_Public
        MP_Public -->|"POST /api/mercadopago/route"| MP_Server
        MP_Server -->|"DB write"| MP_DB1
        MP_Server -->|"split payment"| MP_Connect
        MP_Connect -->|"DB write"| MP_DB2
        MP_Client -->|"GET /api/messages"| MP_Server
        MP_Server -->|"SQL query"| MP_DB1
      end
      subgraph "Checkout API"
        CA_Client["Browser Client"]:::client
        CA_Server["Next.js Server"]:::server
        CA_DB["SQLite DB"]:::db
        CA_Public["Webhook Tunnel (ngrok)"]:::tunnel
        CA_MP["Mercado Pago Service"]:::external
        CA_Client -->|"GET token /api/api.ts"| CA_Server
        CA_Server -->|"HTTPS API"| CA_MP
        CA_Client -->|"Checkout API UI"| CA_MP
        CA_MP -.->|"Webhook POST"| CA_Public
        CA_Public -->|"POST /api/webhook"| CA_Server
        CA_Server -->|"DB write"| CA_DB
        CA_Client -->|"GET /api/messages"| CA_Server
        CA_Server -->|"SQL query"| CA_DB
      end
    end
  end

  %% Click Events
  click DOCS "https://github.com/goncy/next-mercadopago/tree/main/configuracion/"
  click CA_Client "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-api/src/app/page.tsx"
  click CA_Server "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-api/src/api.ts"
  click CA_DB "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-api/db/message.db"
  click CB_Client "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-bricks/src/app/page.tsx"
  click CB_Server "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-bricks/src/api.ts"
  click CB_DB "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-bricks/db/message.db"
  click CP_Client "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-pro/src/app/page.tsx"
  click CP_Server "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-pro/src/app/api/mercadopago/route.ts"
  click CP_DB "https://github.com/goncy/next-mercadopago/blob/main/integraciones/checkout-pro/db/message.db"
  click SU_Client "https://github.com/goncy/next-mercadopago/blob/main/integraciones/suscripciones/src/app/page.tsx"
  click SU_Server "https://github.com/goncy/next-mercadopago/blob/main/integraciones/suscripciones/src/app/api/mercadopago/route.ts"
  click SU_DB "https://github.com/goncy/next-mercadopago/blob/main/integraciones/suscripciones/db/message.db"
  click MP_Client "https://github.com/goncy/next-mercadopago/blob/main/integraciones/marketplace/src/app/page.tsx"
  click MP_Server "https://github.com/goncy/next-mercadopago/blob/main/integraciones/marketplace/src/app/api/mercadopago/route.ts"
  click MP_Connect "https://github.com/goncy/next-mercadopago/blob/main/integraciones/marketplace/src/app/api/mercadopago/connect/route.ts"
  click MP_DB1 "https://github.com/goncy/next-mercadopago/blob/main/integraciones/marketplace/db/message.db"
  click MP_DB2 "https://github.com/goncy/next-mercadopago/blob/main/integraciones/marketplace/db/user.db"

  %% Styles
  classDef client fill:#cce5ff,stroke:#3399ff
  classDef server fill:#d5f5e3,stroke:#27ae60
  classDef db fill:#e8daef,stroke:#8e44ad
  classDef external fill:#f9e79f,stroke:#d35400
  classDef tunnel stroke-dasharray: 5 5,stroke:#e67e22
  classDef docs fill:#f0f0f0,stroke:#95a5a6,stroke-dasharray: 2 2
```
