# xavierdev25/nomi-backend architecture

> Architecture diagram of the GitHub repository xavierdev25/nomi-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xavierdev25/nomi-backend
- Repository: https://github.com/xavierdev25/nomi-backend

## Overview

Nomi is a campus food-ordering backend: students browse stores and products, place orders for aula delivery, pay through MercadoPago, and follow fulfillment; the service also handles identity, recommendations, favorites, ratings, and notifications. A separate postest runner prepares a controlled environment, seeds accounts and catalog data, observes purchase sessions, and records results. The backend’s documented hexagonal structure and selected source references support the main boundaries; unsampled integrations are shown only where the README documents them.

Main entry points: [`src/main/java/com/nomi/backend/infrastructure/web/controller/OrderController.java`](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/web/controller/OrderController.java) (REST API), [`src/main/java/com/nomi/backend/application/order/CreateOrderHandler.java`](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/order/CreateOrderHandler.java) (Order handlers), [`qa/postest/runner/postest.py`](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/postest.py) (Postest CLI), [`qa/postest/runner/nomi_postest/entorno.py`](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/entorno.py) (Environment control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_rest["REST API"]
  node_auth["Identity and access"]
end

subgraph group_commerce["Commerce domain"]
  node_order_usecase["Order operations"]
  node_order_handler["Order handlers"]
  node_catalog["Stores and catalog<br/>[Product.java]"]
  node_order_model["Order lifecycle<br/>[OrderStatus.java]"]
  node_payment["Payments"]
  node_recommendations["Recommendations"]
  node_engagement["Favorites and ratings"]
end

subgraph group_adapters["Infrastructure adapters"]
  node_pg[("PostgreSQL")]
  node_mercadopago["MercadoPago"]
  node_ai_service["AI service"]
  node_notifications["Push and WebSocket"]
end

subgraph group_postest["Postest observation"]
  node_postest_cli["Postest CLI<br/>[postest.py]"]
  node_environment["Environment control<br/>[entorno.py]"]
  node_seeding["Test data seeding<br/>[seed.py]"]
  node_session["Purchase observation<br/>[sesion.py]"]
  node_validation["Result validation<br/>[val.py]"]
  node_test_db[("Postest database<br/>[db.py]")]
  node_config["Runner configuration<br/>[config.py]"]
end

node_student(("Student or staff"))

node_student -->|"sends requests"| node_rest
node_rest -->|"invokes use cases"| node_order_usecase
node_order_handler -->|"implements"| node_order_usecase
node_order_handler -->|"reads catalog"| node_catalog
node_order_handler -->|"creates orders"| node_order_model
node_order_handler -.->|"persists orders"| node_pg
node_rest -->|"checks ownership"| node_auth
node_rest -->|"handles payment routes"| node_payment
node_payment -->|"creates checkout"| node_mercadopago
node_mercadopago -->|"sends signed webhook"| node_rest
node_rest -->|"serves AI routes"| node_recommendations
node_recommendations -->|"requests suggestions"| node_ai_service
node_rest -.->|"serves engagement routes"| node_engagement
node_order_handler -.->|"notifies users"| node_notifications
node_postest_cli -->|"controls services"| node_environment
node_postest_cli -->|"seeds fixtures"| node_seeding
node_postest_cli -->|"runs observations"| node_session
node_postest_cli -->|"validates results"| node_validation
node_environment -->|"uses settings"| node_config
node_environment -->|"starts service"| node_ai_service
node_environment -->|"checks sandbox"| node_mercadopago
node_seeding -->|"writes test data"| node_test_db
node_session -->|"prepares account"| node_seeding
node_session -->|"queries observations"| node_test_db
node_session -->|"checks payments"| node_mercadopago
node_validation -->|"reads test state"| node_test_db

click node_rest "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/web/controller/OrderController.java"
click node_auth "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/security/OwnershipService.java"
click node_order_usecase "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/domain/port/in/order/CreateOrderUseCase.java"
click node_order_handler "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/order/CreateOrderHandler.java"
click node_catalog "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/domain/model/product/Product.java"
click node_order_model "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/domain/model/order/OrderStatus.java"
click node_payment "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/payment/CreatePaymentHandler.java"
click node_recommendations "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/ai/GetRecommendationsHandler.java"
click node_engagement "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/favorite/FavoriteHandler.java"
click node_pg "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/persistence/adapter/OrderRepositoryAdapter.java"
click node_notifications "https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/notification/FcmNotificationAdapter.java"
click node_postest_cli "https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/postest.py"
click node_environment "https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/entorno.py"
click node_seeding "https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/seed.py"
click node_session "https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/sesion.py"
click node_validation "https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/val.py"
click node_test_db "https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/db.py"
click node_config "https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/config.py"

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_rest,node_auth toneBlue
class node_order_usecase,node_order_handler,node_catalog,node_order_model,node_payment,node_recommendations,node_engagement toneAmber
class node_pg,node_mercadopago,node_ai_service,node_notifications toneMint
class node_postest_cli,node_environment,node_seeding,node_session,node_validation,node_test_db,node_config toneRose
class node_student toneIndigo
```

## Components

### API and access

- [REST API](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/web/controller/OrderController.java): `src/main/java/com/nomi/backend/infrastructure/web/controller/OrderController.java`
- [Identity and access](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/security/OwnershipService.java): `src/main/java/com/nomi/backend/infrastructure/security/OwnershipService.java`

### Commerce domain

- [Order operations](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/domain/port/in/order/CreateOrderUseCase.java): `src/main/java/com/nomi/backend/domain/port/in/order/CreateOrderUseCase.java`
- [Order handlers](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/order/CreateOrderHandler.java): `src/main/java/com/nomi/backend/application/order/CreateOrderHandler.java`
- [Stores and catalog](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/domain/model/product/Product.java): `src/main/java/com/nomi/backend/domain/model/product/Product.java`
- [Order lifecycle](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/domain/model/order/OrderStatus.java): `src/main/java/com/nomi/backend/domain/model/order/OrderStatus.java`
- [Payments](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/payment/CreatePaymentHandler.java): `src/main/java/com/nomi/backend/application/payment/CreatePaymentHandler.java`
- [Recommendations](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/ai/GetRecommendationsHandler.java): `src/main/java/com/nomi/backend/application/ai/GetRecommendationsHandler.java`
- [Favorites and ratings](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/application/favorite/FavoriteHandler.java): `src/main/java/com/nomi/backend/application/favorite/FavoriteHandler.java`

### Infrastructure adapters

- [PostgreSQL](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/persistence/adapter/OrderRepositoryAdapter.java): `src/main/java/com/nomi/backend/infrastructure/persistence/adapter/OrderRepositoryAdapter.java`
- **MercadoPago**
- **AI service**
- [Push and WebSocket](https://github.com/xavierdev25/nomi-backend/blob/main/src/main/java/com/nomi/backend/infrastructure/notification/FcmNotificationAdapter.java): `src/main/java/com/nomi/backend/infrastructure/notification/FcmNotificationAdapter.java`

### Postest observation

- [Postest CLI](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/postest.py): `qa/postest/runner/postest.py`
- [Environment control](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/entorno.py): `qa/postest/runner/nomi_postest/entorno.py`
- [Test data seeding](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/seed.py): `qa/postest/runner/nomi_postest/seed.py`
- [Purchase observation](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/sesion.py): `qa/postest/runner/nomi_postest/sesion.py`
- [Result validation](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/val.py): `qa/postest/runner/nomi_postest/val.py`
- [Postest database](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/db.py): `qa/postest/runner/nomi_postest/db.py`
- [Runner configuration](https://github.com/xavierdev25/nomi-backend/blob/main/qa/postest/runner/nomi_postest/config.py): `qa/postest/runner/nomi_postest/config.py`

### Other components

- **Student or staff**

## Connections

- Student or staff → REST API: sends requests (evidence: `README.md`)
- REST API → Order operations: invokes use cases (evidence: `src/main/java/com/nomi/backend/infrastructure/web/controller/OrderController.java`)
- Order handlers → Order operations: implements (evidence: `src/main/java/com/nomi/backend/application/order/CreateOrderHandler.java`)
- Order handlers → Stores and catalog: reads catalog (evidence: `src/main/java/com/nomi/backend/application/order/CreateOrderHandler.java`)
- Order handlers → Order lifecycle: creates orders (evidence: `src/main/java/com/nomi/backend/application/order/CreateOrderHandler.java`)
- Order handlers → PostgreSQL: persists orders
- REST API → Identity and access: checks ownership (evidence: `src/main/java/com/nomi/backend/infrastructure/web/controller/OrderController.java`)
- REST API → Payments: handles payment routes (evidence: `README.md`)
- Payments → MercadoPago: creates checkout (evidence: `README.md`)
- MercadoPago → REST API: sends signed webhook
- REST API → Recommendations: serves AI routes (evidence: `README.md`)
- Recommendations → AI service: requests suggestions (evidence: `README.md`)
- REST API → Favorites and ratings: serves engagement routes
- Order handlers → Push and WebSocket: notifies users
- Postest CLI → Environment control: controls services (evidence: `qa/postest/runner/postest.py`)
- Postest CLI → Test data seeding: seeds fixtures (evidence: `qa/postest/runner/postest.py`)
- Postest CLI → Purchase observation: runs observations (evidence: `qa/postest/runner/postest.py`)
- Postest CLI → Result validation: validates results (evidence: `qa/postest/runner/postest.py`)
- Environment control → Runner configuration: uses settings (evidence: `qa/postest/runner/nomi_postest/entorno.py`)
- Environment control → AI service: starts service (evidence: `qa/postest/runner/nomi_postest/entorno.py`)
- Environment control → MercadoPago: checks sandbox (evidence: `qa/postest/runner/nomi_postest/entorno.py`)
- Test data seeding → Postest database: writes test data (evidence: `qa/postest/runner/nomi_postest/seed.py`)
- Purchase observation → Test data seeding: prepares account (evidence: `qa/postest/runner/nomi_postest/sesion.py`)
- Purchase observation → Postest database: queries observations (evidence: `qa/postest/runner/nomi_postest/sesion.py`)
- Purchase observation → MercadoPago: checks payments (evidence: `qa/postest/runner/nomi_postest/sesion.py`)
- Result validation → Postest database: reads test state (evidence: `qa/postest/runner/nomi_postest/val.py`)
