# jjulian10/porto-esfirra architecture

> Architecture diagram of the GitHub repository jjulian10/porto-esfirra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jjulian10/porto-esfirra
- Repository: https://github.com/jjulian10/porto-esfirra

## Overview

Porto Esfirras is an online menu and order-management site. Customers browse the database-backed catalog, configure pickup or delivery, and submit orders; the server validates items and recalculates totals before persisting the order and, for Pix, creating a Mercado Pago order. Administrators manage orders, menu items, delivery zones, and store/payment settings. The README and sampled routes establish these API relationships; the storefront implementation and some storage internals were not sampled, so their wiring is shown only where documented.

Main entry points: [`db/index.ts`](https://github.com/jjulian10/porto-esfirra/blob/main/db/index.ts) (D1 database access), [`app/page.tsx`](https://github.com/jjulian10/porto-esfirra/blob/main/app/page.tsx) (Storefront), [`app/api/admin/catalog/route.ts`](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/admin/catalog/route.ts) (Menu management API), [`app/api/admin/settings/route.ts`](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/admin/settings/route.ts) (Store settings API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shop["Customer ordering"]
  node_storefront["Storefront<br/>[page.tsx]"]
end

subgraph group_operations["Store operations"]
  node_admin["Admin panel<br/>[page.tsx]"]
  node_admin_catalog["Menu management API<br/>[route.ts]"]
  node_admin_orders["Order management API<br/>[route.ts]"]
  node_admin_settings["Store settings API<br/>[route.ts]"]
  node_auth["Admin authorization<br/>[admin.ts]"]
end

subgraph group_backend["Order and catalog services"]
  node_catalog_api["Public catalog API<br/>[route.ts]"]
  node_order_api["Order checkout API<br/>[route.ts]"]
  node_status_api["Order status API<br/>[route.ts]"]
  node_store["Store data loader<br/>[store.ts]"]
  node_catalog_logic["Catalog utilities<br/>[catalog.ts]"]
end

subgraph group_persistence["Persistent data"]
  node_db_access["D1 database access<br/>[index.ts]"]
  node_schema["Data schema<br/>[schema.ts]"]
  node_database[("D1 database")]
end

subgraph group_payments["Pix payments"]
  node_payment_state["Payment state logic<br/>[payment-state.ts]"]
  node_mp_client["Mercado Pago client<br/>[mercado-pago.ts]"]
  node_webhook["Payment webhook<br/>[route.ts]"]
end

node_customer(("Customer"))
node_provider["Mercado Pago"]

node_customer -->|"browses and submits"| node_storefront
node_storefront -->|"loads catalog"| node_catalog_api
node_catalog_api -->|"loads store data"| node_store
node_storefront -->|"submits checkout"| node_order_api
node_storefront -->|"checks status"| node_status_api
node_admin -->|"loads and updates"| node_admin_orders
node_admin -->|"loads and edits"| node_admin_catalog
node_admin -->|"loads and saves"| node_admin_settings
node_admin_orders -->|"checks access"| node_auth
node_admin_catalog -->|"checks access"| node_auth
node_admin_settings -->|"checks access"| node_auth
node_admin_catalog -->|"loads catalog"| node_store
node_admin_settings -->|"loads settings"| node_store
node_order_api -->|"loads catalog and settings"| node_store
node_order_api -.->|"creates Pix order"| node_mp_client
node_webhook -->|"verifies and fetches"| node_mp_client
node_webhook -->|"calculates payment state"| node_payment_state
node_order_api -->|"reads and writes orders"| node_db_access
node_status_api -->|"reads order status"| node_db_access
node_admin_orders -->|"reads and updates orders"| node_db_access
node_admin_catalog -->|"writes products"| node_db_access
node_admin_settings -->|"writes settings and zones"| node_db_access
node_webhook -->|"reads and updates payment"| node_db_access
node_db_access -->|"queries"| node_database
node_schema -->|"defines tables"| node_db_access
node_mp_client -.->|"creates and queries orders"| node_provider
node_provider -.->|"sends notifications"| node_webhook

click node_storefront "https://github.com/jjulian10/porto-esfirra/blob/main/app/page.tsx"
click node_catalog_api "https://github.com/jjulian10/porto-esfirra/blob/main/app/api/catalog/route.ts"
click node_order_api "https://github.com/jjulian10/porto-esfirra/blob/main/app/api/orders/route.ts"
click node_status_api "https://github.com/jjulian10/porto-esfirra/blob/main/app/api/orders/status/route.ts"
click node_admin "https://github.com/jjulian10/porto-esfirra/blob/main/app/admin/page.tsx"
click node_admin_catalog "https://github.com/jjulian10/porto-esfirra/blob/main/app/api/admin/catalog/route.ts"
click node_admin_orders "https://github.com/jjulian10/porto-esfirra/blob/main/app/api/admin/orders/route.ts"
click node_admin_settings "https://github.com/jjulian10/porto-esfirra/blob/main/app/api/admin/settings/route.ts"
click node_auth "https://github.com/jjulian10/porto-esfirra/blob/main/lib/admin.ts"
click node_store "https://github.com/jjulian10/porto-esfirra/blob/main/lib/store.ts"
click node_catalog_logic "https://github.com/jjulian10/porto-esfirra/blob/main/lib/catalog.ts"
click node_payment_state "https://github.com/jjulian10/porto-esfirra/blob/main/lib/payment-state.ts"
click node_mp_client "https://github.com/jjulian10/porto-esfirra/blob/main/lib/mercado-pago.ts"
click node_webhook "https://github.com/jjulian10/porto-esfirra/blob/main/app/api/webhooks/mercado-pago/route.ts"
click node_db_access "https://github.com/jjulian10/porto-esfirra/blob/main/db/index.ts"
click node_schema "https://github.com/jjulian10/porto-esfirra/blob/main/db/schema.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_storefront toneBlue
class node_admin,node_admin_catalog,node_admin_orders,node_admin_settings,node_auth toneAmber
class node_catalog_api,node_order_api,node_status_api,node_store,node_catalog_logic toneMint
class node_db_access,node_schema,node_database toneRose
class node_payment_state,node_mp_client,node_webhook,node_customer,node_provider toneIndigo
```

## Components

### Customer ordering

- [Storefront](https://github.com/jjulian10/porto-esfirra/blob/main/app/page.tsx): `app/page.tsx`

### Store operations

- [Admin panel](https://github.com/jjulian10/porto-esfirra/blob/main/app/admin/page.tsx): `app/admin/page.tsx`
- [Menu management API](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/admin/catalog/route.ts): `app/api/admin/catalog/route.ts`
- [Order management API](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/admin/orders/route.ts): `app/api/admin/orders/route.ts`
- [Store settings API](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/admin/settings/route.ts): `app/api/admin/settings/route.ts`
- [Admin authorization](https://github.com/jjulian10/porto-esfirra/blob/main/lib/admin.ts): `lib/admin.ts`

### Order and catalog services

- [Public catalog API](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/catalog/route.ts): `app/api/catalog/route.ts`
- [Order checkout API](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/orders/route.ts): `app/api/orders/route.ts`
- [Order status API](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/orders/status/route.ts): `app/api/orders/status/route.ts`
- [Store data loader](https://github.com/jjulian10/porto-esfirra/blob/main/lib/store.ts): `lib/store.ts`
- [Catalog utilities](https://github.com/jjulian10/porto-esfirra/blob/main/lib/catalog.ts): `lib/catalog.ts`

### Persistent data

- [D1 database access](https://github.com/jjulian10/porto-esfirra/blob/main/db/index.ts): `db/index.ts`
- [Data schema](https://github.com/jjulian10/porto-esfirra/blob/main/db/schema.ts): `db/schema.ts`
- **D1 database**

### Pix payments

- [Payment state logic](https://github.com/jjulian10/porto-esfirra/blob/main/lib/payment-state.ts): `lib/payment-state.ts`
- [Mercado Pago client](https://github.com/jjulian10/porto-esfirra/blob/main/lib/mercado-pago.ts): `lib/mercado-pago.ts`
- [Payment webhook](https://github.com/jjulian10/porto-esfirra/blob/main/app/api/webhooks/mercado-pago/route.ts): `app/api/webhooks/mercado-pago/route.ts`

### Other components

- **Customer**
- **Mercado Pago**

## Connections

- Customer → Storefront: browses and submits
- Storefront → Public catalog API: loads catalog
- Public catalog API → Store data loader: loads store data
- Storefront → Order checkout API: submits checkout
- Storefront → Order status API: checks status
- Admin panel → Order management API: loads and updates
- Admin panel → Menu management API: loads and edits
- Admin panel → Store settings API: loads and saves
- Order management API → Admin authorization: checks access
- Menu management API → Admin authorization: checks access
- Store settings API → Admin authorization: checks access
- Menu management API → Store data loader: loads catalog
- Store settings API → Store data loader: loads settings
- Order checkout API → Store data loader: loads catalog and settings
- Order checkout API → Mercado Pago client: creates Pix order
- Payment webhook → Mercado Pago client: verifies and fetches
- Payment webhook → Payment state logic: calculates payment state
- Order checkout API → D1 database access: reads and writes orders
- Order status API → D1 database access: reads order status
- Order management API → D1 database access: reads and updates orders
- Menu management API → D1 database access: writes products
- Store settings API → D1 database access: writes settings and zones
- Payment webhook → D1 database access: reads and updates payment
- D1 database access → D1 database: queries
- Data schema → D1 database access: defines tables
- Mercado Pago client → Mercado Pago: creates and queries orders
- Mercado Pago → Payment webhook: sends notifications