# dcatanzaro/cafecito architecture

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

- Interactive diagram: https://gitdiagram.com/dcatanzaro/cafecito
- Repository: https://github.com/dcatanzaro/cafecito

## Overview

##### Project type and purpose
- This is a full-stack donation platform (“Cafecito”) built with Next.js (React SSR/SSG) on the frontend, an Express.js server for API and business logic, and MongoDB as the persistence layer. It also integrates with MercadoPago for payments, uses a Telegram Bot for notifications, and leverages Socket.io for real-time updates.

##### File structure
- Top-level config and scripts:
- Dockerfile, docker-compose.yml → containerization
- nodemon.json, package.json, next.config.js
- Frontend (Next.js):
- pages/ → routing and SSR components
- components/ → reusable UI pieces (QR, coffee list, modal, header, inputText, etc.)
- public/ → static assets (fonts, images)
- styles/ → global and SCSS variable definitions
- Backend (Express + services):
- server.js, routes.js → express app initialization and HTTP routes
- server/config/share.html → static view
- server/controllers/ → controllers per domain (CoffeeController, MercadoPagoController)
- server/services/ → service layer including CoffeeService, MercadoPagoService, SocketService
- server/models/coffee.js → Mongoose model
- Environment and deployment:
- .env.development / .env → environment variables (MongoDB connection, Telegram IDs, MercadoPago key, admin password)
- docker-compose.yml → defines services (app + MongoDB)

##### README for additional insights
- Describes prerequisites (NodeJS, MongoDB), environment variables, development vs. production commands, and how to enable admin mode via query parameters.
- Mentions Docker deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Docker Compose Network
    subgraph "Docker Compose Network"
        direction TB
        subgraph "Cafecito App Container"
            direction TB

            %% Frontend Layer
            subgraph "Frontend Layer"
                direction TB
                Browser["Browser"]:::external
                NextJS["Next.js Server\n(SSR/SSG)"]:::internal
                UIComps["Reusable UI Components"]:::frontend
                StylesAssets["Global Styles & Assets"]:::frontend
            end

            %% API Layer
            subgraph "Express API Layer"
                direction TB
                Router["routes.js"]:::internal
                CoffeeCtrl["CoffeeController"]:::internal
                MercadoCtrl["MercadoPagoController"]:::internal
                CoffeeSvc["CoffeeService"]:::internal
                MercadoSvc["MercadoPagoService"]:::internal
                SocketSvc["SocketService"]:::internal
                CoffeeModel["Coffee Model"]:::db
                ShareView["share.html"]:::internal
            end
        end

        MongoDB["MongoDB"]:::db
    end

    %% External Services
    MercadoPago["MercadoPago API"]:::external
    Telegram["Telegram Bot API"]:::external

    %% Data Flows
    Browser -->|"HTTP/SSR & API Fetch"| NextJS
    NextJS -->|"Render Pages & Assets"| Browser

    Browser -->|"AJAX/Fetch"| Router
    Router --> CoffeeCtrl
    Router --> MercadoCtrl

    CoffeeCtrl --> CoffeeSvc
    MercadoCtrl --> MercadoSvc

    CoffeeSvc --> CoffeeModel
    CoffeeSvc -->|Triggers| SocketSvc
    SocketSvc -.->|"WebSocket Update"| Browser

    CoffeeSvc --> Telegram
    MercadoSvc --> MercadoPago

    %% Click Events
    click NextJS "https://github.com/dcatanzaro/cafecito/tree/master/pages/"
    click UIComps "https://github.com/dcatanzaro/cafecito/tree/master/components/"
    click StylesAssets "https://github.com/dcatanzaro/cafecito/tree/master/styles/"
    click StylesAssets "https://github.com/dcatanzaro/cafecito/tree/master/public/"
    click Router "https://github.com/dcatanzaro/cafecito/blob/master/routes.js"
    click CoffeeCtrl "https://github.com/dcatanzaro/cafecito/blob/master/server/controllers/CoffeeController.js"
    click MercadoCtrl "https://github.com/dcatanzaro/cafecito/blob/master/server/controllers/MercadoPagoController.js"
    click CoffeeSvc "https://github.com/dcatanzaro/cafecito/blob/master/server/services/CoffeeService.js"
    click MercadoSvc "https://github.com/dcatanzaro/cafecito/blob/master/server/services/MercadoPagoService.js"
    click SocketSvc "https://github.com/dcatanzaro/cafecito/blob/master/server/services/SocketService.js"
    click CoffeeModel "https://github.com/dcatanzaro/cafecito/blob/master/server/models/coffee.js"
    click ShareView "https://github.com/dcatanzaro/cafecito/blob/master/server/config/share.html"
    click .env "https://github.com/dcatanzaro/cafecito/blob/master/.env"
    click .env "https://github.com/dcatanzaro/cafecito/blob/master/.env.development"
    click NextJS "https://github.com/dcatanzaro/cafecito/blob/master/next.config.js"
    click NextJS "https://github.com/dcatanzaro/cafecito/blob/master/nodemon.json"
    click Dockerfile "https://github.com/dcatanzaro/cafecito/tree/master/Dockerfile"
    click docker-compose "https://github.com/dcatanzaro/cafecito/blob/master/docker-compose.yml"
    click package "https://github.com/dcatanzaro/cafecito/blob/master/package.json"

    %% Styles
    classDef internal fill:#CEE7FF,stroke:#2C7BE5,color:#0A214A,stroke-width:1px
    classDef frontend fill:#E3F7DF,stroke:#28A745,color:#084C09,stroke-width:1px
    classDef external fill:#E8F6FF,stroke:#17A2B8,color:#0C2D3E,stroke-width:1px
    classDef db fill:#FFF3CD,stroke:#FFC107,color:#664D03,stroke-width:1px
```
