# andremelzc/ecommerce architecture

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

- Interactive diagram: https://gitdiagram.com/andremelzc/ecommerce
- Repository: https://github.com/andremelzc/ecommerce

## Overview

##### Project type and purpose
- This is a full-stack e-commerce web application built with Next.js (App Router).
- It serves two main user interfaces: a public client storefront under `app/(client)` and an admin dashboard under `app/(admin)`.
- It implements its backend using Next.js serverless API routes (`app/api/*`), integrates with a database via `lib/db.ts`, and connects to external services such as MercadoPago for payments and NextAuth for authentication.

##### File structure
- Top-level UI layers:
- `app/(client)/…` — pages, layouts, and components for shoppers (product browsing, cart, checkout, profile).
- `app/(admin)/…` — pages, layouts, and components for staff (product management, promotions).
- API layer:
- `app/api/*` — each folder (e.g. `productos`, `cart`, `auth`, `mercado-pago`) maps to a serverless route (`route.ts`) handling CRUD and business logic.
- Shared presentation:
- `app/components` — reusable React UI elements (auth forms, product cards, navbars, drawers).
- `app/context` — React Contexts managing global state (cart, checkout, products, promotions).
- `app/hooks` and `app/utils` — custom hooks and utility functions for data fetching, formatting, side-effects.
- Data access & business logic:
- `lib/` — modules for database connectivity (`db.ts`), PDF or receipt generation (`pdf.ts`, `boleta.ts`), and category/product helpers.
- Configuration & assets:
- `next.config.ts`, `tsconfig.json`, CSS, public assets, lint/build configs.

##### README
- Confirms Next.js App Router usage and basic CLI commands.

##### Detail, not over-complication
– Partition the UI into client vs admin; group shared components.
– Group API routes by domain.
– Clearly show the DB abstraction (lib/db) vs PDF/receipt generator.
– Show state management (Contexts) feeding into UI components.
– Avoid showing every single file; instead, group by logical module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["User's Browser"]
    Browser -->|"loads assets"| CDN["Public Assets (CDN)"]:::external
    Browser -->|"loads styles"| Styles["Global Styles"]:::external
    Browser -->|"navigates"| ClientUI
    Browser -->|"navigates"| AdminUI

    subgraph "UI Layer"
        direction TB
        ClientUI["Client Storefront"]:::frontend
        click ClientUI "https://github.com/andremelzc/ecommerce/tree/main/app/(client)"
        AuthPages["Auth Pages (Login/Register)"]:::frontend
        click AuthPages "https://github.com/andremelzc/ecommerce/blob/main/app/auth/login/page.tsx"
        click AuthPages "https://github.com/andremelzc/ecommerce/blob/main/app/auth/register/page.tsx"
        AdminUI["Admin Dashboard"]:::frontend
        click AdminUI "https://github.com/andremelzc/ecommerce/tree/main/app/(admin)"
        SharedComp["Shared Components"]:::frontend
        click SharedComp "https://github.com/andremelzc/ecommerce/tree/main/app/components"
        Contexts["React Contexts"]:::frontend
        click Contexts "https://github.com/andremelzc/ecommerce/tree/main/app/context"
        Hooks["Custom Hooks"]:::frontend
        click Hooks "https://github.com/andremelzc/ecommerce/tree/main/app/hooks"
        Utils["Utility Functions"]:::frontend
        click Utils "https://github.com/andremelzc/ecommerce/tree/main/app/utils"
    end

    ClientUI -->|"uses"| SharedComp
    ClientUI -->|"uses"| Contexts
    ClientUI -->|"uses"| Hooks
    ClientUI -->|"uses"| Utils
    AdminUI -->|"uses"| SharedComp
    AdminUI -->|"uses"| Contexts
    AdminUI -->|"uses"| Hooks
    AdminUI -->|"uses"| Utils

    subgraph "Next.js API Layer"
        direction TB
        Productos["Productos API"]:::api
        click Productos "https://github.com/andremelzc/ecommerce/tree/main/app/api/productos"
        Cart["Cart API"]:::api
        click Cart "https://github.com/andremelzc/ecommerce/tree/main/app/api/cart"
        AuthAPI["NextAuth API"]:::api
        click AuthAPI "https://github.com/andremelzc/ecommerce/blob/main/app/api/auth/[...nextauth]/route.ts"
        Pago["MercadoPago API"]:::api
        click Pago "https://github.com/andremelzc/ecommerce/blob/main/app/api/mercado-pago/route.ts"
    end

    ClientUI -->|"API calls"| Productos
    ClientUI -->|"API calls"| Cart
    ClientUI -->|"API calls"| AuthAPI
    ClientUI -->|"API calls"| Pago
    AdminUI -->|"API calls"| Productos
    AdminUI -->|"API calls"| Cart
    AdminUI -->|"API calls"| AuthAPI

    Productos -->|"queries"| DBModule
    Cart -->|"queries"| DBModule
    AuthAPI -->|"queries"| DBModule
    Pago -->|"queries"| DBModule
    Pago -->|"generates receipt via"| PDFGen

    subgraph "Business Logic & Data Access"
        direction TB
        DBModule["Database Module"]:::data
        click DBModule "https://github.com/andremelzc/ecommerce/blob/main/lib/db.ts"
        PDFGen["PDF/Receipt Generator"]:::data
        click PDFGen "https://github.com/andremelzc/ecommerce/blob/main/lib/pdf.ts"
        click PDFGen "https://github.com/andremelzc/ecommerce/blob/main/lib/boleta.ts"
    end

    DBModule -->|"connects to"| DB["Database"]:::database

    subgraph "External Services"
        direction TB
        AuthSvc["Auth Provider"]:::external
        MercadoSvc["MercadoPago"]:::external
    end

    AuthAPI -->|"auth flow"| AuthSvc
    Pago -->|"payment processing"| MercadoSvc

    classDef frontend fill:#e3f2fd,stroke:#2196f3,color:#0d47a1;
    classDef api fill:#e8f5e9,stroke:#4caf50,color:#1b5e20;
    classDef data fill:#fff3e0,stroke:#fb8c00,color:#e65100;
    classDef database fill:#ffe0b2,stroke:#ef6c00,color:#bf360c,stroke-dasharray: 5 5;
    classDef external fill:#f3e5f5,stroke:#9c27b0,color:#4a148c;
```
