Delivery System

A complete order management system for delivery services, developed as a study project focused on best practices in software architecture and design.

Table of Contents

• Overview
• Features
• Technologies
• Prerequisites
• Installation and Setup
• Running the Project
• Project Structure
• API Endpoints
• Design Patterns
• Tests
• CI/CD
• Status

---

Overview

The Delivery System is a complete web platform for managing delivery orders with support for multiple restaurants, clients, and payment methods. The project combines a robust Java/Spring Boot backend with an intuitive web frontend, implementing advanced software architecture concepts such as Domain-Driven Design (DDD) and Clean Architecture.

This is an educational and non-commercial project, developed to study and practice best practices in software development, system architecture, and design pattern implementation.

---

Features

Order Management

• Order creation in draft state
• Add menu items to orders
• Remove items from orders
• Decrease item quantities
• Cancel orders
• List orders by client
• Track order status (Draft -> Paid -> Confirmed -> Delivered)

Restaurant and Menu Management

• Restaurant registration
• Menu and menu items management
• Support for multiple currencies (BRL, USD, CAD)

Accounts and Clients

• User account management
• Support for multiple roles (Client, Restaurant Owner)
• Account activity tracking

Payments

• Payment processing
• Payment status tracking

Web Interface (In Development)

---

Technologies

Backend

• Java 17 - Programming language
• Spring Boot 3.2.4 - Web framework
• Spring JDBC - Data access
• PostgreSQL - Relational database
• JUnit 5 - Testing framework
• Spring Boot Test & MockMvc - Integration testing
• Maven - Dependency manager

Frontend (In Development)

DevOps

• Docker & Docker Compose - Containerization
• GitHub Actions - CI/CD Pipeline
• Nginx - Web server (reverse proxy)

---

Prerequisites

Local Development

• Java 17 or higher
• Maven 3.6+
• Node.js 18+ (for frontend)
• PostgreSQL 13+ (if running locally without Docker)

Using Docker

• Docker 20.10+
• Docker Compose 2.0+

---

Installation and Setup

Option 1: With Docker Compose (Recommended)

1. Clone the repository

git clone https://github.com/Smeltier/delivery-system.git
cd delivery-system

2. Start the containers

docker-compose up -d

This will:

• Start a PostgreSQL container
• Apply database migrations
• Start the backend server on port 8080
• Start the frontend server on port 3000 (when implemented)

3. Access the application

• API Backend: http://localhost:8080
• Frontend Web: http://localhost:3000 (in development)
• Database: localhost:5432

---

Option 2: Manual Execution (Without Docker)

1. Clone the repository

git clone https://github.com/Smeltier/delivery-system.git
cd delivery-system

2. Configure PostgreSQL

Create a database:

CREATE DATABASE delivery_system;

3. Configure environment variables

Create a .env file in the project root:

# Database
DATABASE_URL=jdbc:postgresql://localhost:5432/delivery_system
DATABASE_USER=postgres
DATABASE_PASSWORD=your_password

# Server
SERVER_PORT=8080

4. Execute migrations

psql -U postgres -d delivery_system -f schema.sql

5. Compile and run the backend

cd backend

# Build the project
mvn clean package

# Run the application
mvn spring-boot:run

The API will be available at http://localhost:8080

6. Run the frontend (When implemented)

cd frontend

npm install
npm start

The frontend will be available at http://localhost:3000

---

Project Structure

delivery-system/
├── backend/
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/br/com/delivery/
│   │   │   │   ├── domain/                      # Domain Layer
│   │   │   │   │   ├── account/                 # User accounts
│   │   │   │   │   ├── order/                   # Orders
│   │   │   │   │   ├── restaurant/              # Restaurants
│   │   │   │   │   ├── payment/                 # Payments
│   │   │   │   │   ├── shared/                  # Shared value objects
│   │   │   │   │   └── repositories/            # Repository interfaces
│   │   │   │   ├── application/                 # Application Layer
│   │   │   │   │   ├── usecases/                # Use cases
│   │   │   │   │   ├── dto/                     # Data transfer objects
│   │   │   │   │   └── mappers/                 # Entity mappers
│   │   │   │   ├── infrastructure/              # Infrastructure Layer
│   │   │   │   │   ├── web/                     # REST controllers
│   │   │   │   │   ├── persistence/             # JDBC implementation
│   │   │   │   │   ├── config/                  # Spring configuration
│   │   │   │   │   └── exception/               # Global exception handling
│   │   │   │   └── DeliveryApplication.java     # Main class
│   │   │   └── resources/
│   │   │       └── application.properties       # Application configuration
│   │   └── test/                                # Tests (Unit and Integration)
│   │       ├── java/br/com/delivery/domain/     # Domain tests
│   │       ├── java/br/com/delivery/application/ # Use case tests
│   │       └── java/br/com/delivery/infrastructure/ # Integration tests
│   ├── pom.xml                                  # Maven dependencies
│   └── Dockerfile                               # Backend dockerfile
│
├── frontend/                                     # (In development)
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── services/
│   │   └── App.tsx
│   ├── package.json
│   └── Dockerfile
│
├── documentation/
│   ├── decisions.md                             # Architecture Decision Records
│   ├── class_diagram.plantuml                   # UML Class Diagram
│   └── api_documentation.md                     # API Documentation
│
├── schema.sql                                   # PostgreSQL schema
├── compose.yml                                  # Docker Compose configuration
├── .env.example                                 # Environment variables example
├── .gitignore
├── .github/
│   └── workflows/
│       └── maven.yml                            # CI/CD Pipeline
└── README.md

---

API Endpoints

All endpoints return JSON and are documented below.

Order Management

Add item to order

POST /orders/items
Content-Type: application/json

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "restaurantId": "660e8400-e29b-41d4-a716-446655440000",
  "menuItemId": "770e8400-e29b-41d4-a716-446655440000",
  "quantity": 2
}

Responses:

• 201 Created - Item successfully added
• 400 Bad Request - Validation failed (invalid quantity, restaurant not found, etc)
• 404 Not Found - Account, restaurant or item not found

---

Remove item from order

DELETE /orders/{orderId}/items/{menuItemId}

Parameters:

• orderId (UUID) - Order ID
• menuItemId (UUID) - Menu item ID

Responses:

• 204 No Content - Item successfully removed
• 404 Not Found - Order or item not found

---

Decrease item quantity

PATCH /orders/{orderId}/items/{menuItemId}/decrease?quantity=1

Parameters:

• orderId (UUID) - Order ID
• menuItemId (UUID) - Menu item ID
• quantity (int) - Quantity to decrease

Responses:

• 200 OK - Quantity successfully decreased
• 400 Bad Request - Invalid quantity
• 404 Not Found - Order or item not found

---

Cancel order

DELETE /orders/{orderId}

Parameters:

• orderId (UUID) - Order ID

Responses:

• 204 No Content - Order successfully cancelled
• 404 Not Found - Order not found
• 400 Bad Request - Order in state that cannot be cancelled

---

List client orders

GET /clients/{accountId}/orders

Parameters:

• accountId (UUID) - Client account ID

Response (200 OK):

{
  "orders": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "CONFIRMED",
      "totalAmount": 89.90,
      "currency": "BRL",
      "createdAt": "2024-08-27T10:30:00Z",
      "items": [
        {
          "menuItemId": "770e8400-e29b-41d4-a716-446655440000",
          "name": "Margherita Pizza",
          "quantity": 2,
          "unitPrice": 35.00,
          "subtotal": 70.00
        }
      ]
    }
  ]
}

---

Error Handling

The API returns structured JSON errors:

Standard format:

{
  "message": "Error description",
  "status": 400,
  "timestamp": "2024-08-27T10:30:00Z"
}

Common HTTP codes:

Code	Description
400 Bad Request	Validation failed, invalid data or business error
404 Not Found	Resource not found
500 Internal Server Error	Server error

Business error examples:

• "Quantity must be positive."
• "Restaurant not found"
• "Order cannot be cancelled in this state"
• "Incompatible currencies"

---

Design Patterns

Domain-Driven Design (DDD)

The project implements fundamental DDD principles:

Entities

Objects with unique identity that change over time:

• Order - Represents an order
• Client - Represents a client
• Restaurant - Represents a restaurant
• Account - Represents a user account

Value Objects

Objects without identity that are immutable:

• Money - Represents monetary values with currency validation
• OrderId, AccountId, MenuItemId, RestaurantId - Typed identifiers
• Address - Delivery address
• OrderItem - Order item

Aggregates

Clusters of entities functioning as a unit:

• Order Aggregate - Contains Order (root) + OrderItems + Payment

Repositories

Abstraction for data persistence:

• IOrderRepository - Contract for order persistence
• IAccountRepository - Contract for account persistence
• IRestaurantRepository - Contract for restaurant persistence

Use Cases (Application Services)

Orchestrate business logic:

• AddItemToOrderUseCase
• RemoveItemFromOrderUseCase
• DecreaseItemQuantityFromOrderUseCase
• CancelOrderUseCase
• FindClientOrdersUseCase

---

Clean Architecture

Responsibilities are clearly separated into layers:

Domain Layer (Core)

• Responsibility: Pure business logic
• Independence: No framework, database or web dependencies
• Examples: Entities, value objects, domain rules, repository interfaces
• Importance: Heart of the system

Application Layer

• Responsibility: Use case orchestration
• Function: Coordinate domain and repositories
• Examples: Use cases, DTOs, mappers
• Flow: Receive input (DTO) -> call repositories and domain -> return output (DTO)

Infrastructure Layer

• Responsibility: Technical implementation details
• Examples: Web controllers, JDBC repositories, Spring configuration
• Easy to change: Can replace PostgreSQL with MongoDB without affecting domain/application
• Should not: Contain business logic

---

Order State Transitions

The Order follows a well-defined flow with business rules:

+---------+     +------+     +-----------+     +----------+
|  DRAFT  | --> | PAID | --> | CONFIRMED | --> | DELIVERED|
+---------+     +------+     +-----------+     +----------+
      |            |              |                 
      +------------+--------------+                 
              CANCELLED                          

Rules:

• An order starts in DRAFT
• Can only be paid once
• Can only be confirmed after payment
• Can be cancelled in any state except DELIVERED
• Must have address before changing to CONFIRMED

---

Tests

The project has robust test coverage across multiple layers, ensuring quality and reliability.

Run all tests

cd backend
mvn test

Run specific tests

Domain tests:

mvn test -Dtest=*Test

Use case tests:

mvn test -Dtest=*UseCaseTest

Integration tests:

mvn test -Dtest=*IntegrationTest

---

Test Structure

Domain Tests

Location: src/test/java/br/com/delivery/domain/

Test business rules and entity behavior:

• OrderTest - Tests:

  • Order creation and validations
  • State transitions
  • Adding and removing items
  • Total calculations
  • Currency validations

• MoneyTest - Tests:

  • Arithmetic operations with Money
  • Currency validation
  • Comparisons and equality

Application Tests

Location: src/test/java/br/com/delivery/application/

Test use cases with fake repositories:

• AddItemToOrderUseCaseTest - Tests:

  • Adding items to order
  • Automatic draft order creation
  • Account, restaurant and item validations
  • Quantity validation

• RemoveItemFromOrderUseCaseTest - Tests:

  • Item removal
  • Existence validation

• DecreaseItemQuantityFromOrderUseCaseTest - Tests:

  • Quantity decrease
  • Quantity validations

• FindClientOrdersUseCaseTest - Tests:

  • List orders by client
  • Filters and sorting

Integration Tests

Location: src/test/java/br/com/delivery/infrastructure/

Test complete HTTP flows with MockMvc:

• OrderControllerIntegrationTest - Tests:
  • API endpoints
  • JSON serialization/deserialization
  • Correct HTTP status codes
  • End-to-end flows

---

Test Coverage

To generate coverage report:

mvn test jacoco:report

Report will be generated at target/site/jacoco/index.html

---

CI/CD

The project uses GitHub Actions for test automation and build.

Pipeline Workflow

Location: .github/workflows/maven.yml

What happens on each push:

1. Checkout - Code clone
2. Setup Java - Configure Java 17
3. Start PostgreSQL - Start PostgreSQL container for tests
4. Apply Database Schema - Execute migrations
5. Run Tests - Execute test suite with Maven
6. Build Package - Compile and generate JAR executable

Build Status:

The badge at the top of the README shows current status:

---

Class Diagram

See the complete UML diagram in documentation/class_diagram.plantuml

To visualize, use tools such as:

• PlantUML Online Editor
• VS Code Extension: PlantUML

---

Additional Documentation

• documentation/decisions.md - Architecture Decision Records

  • Why DDD?
  • Why Clean Architecture?
  • Persistence patterns
  • Separation of concerns

• documentation/api_documentation.md - Detailed API documentation

  • All endpoints
  • Request/response formats
  • Practical examples

---

Contact & Support

Developer: Smeltier

If you have questions, suggestions or find bugs:

• Open an Issue

---

License

This project is educational and non-commercial. Feel free to use it as study material.

---

Developed as a learning project in software architecture