Item Detail API — Backend Challenge

Overview

This project implements an item detail API inspired by a marketplace scenario (similar to Mercado Libre), focusing on:

• Aggregating data from multiple sources
• Clean and simple domain modeling
• Conscious architectural decisions
• Avoiding over-engineering while maintaining quality

The main goal is not to build a full e-commerce API, but to properly support the item detail page with product and related data.

---

Architecture

The application follows a simple layered architecture:

Client
   ↓
Endpoints (Routes)
   ↓
Services (orchestration layer)
   ↓
Repositories + Providers
   ↓
SQLite (local data) + simulated external services

Components

Endpoints:

• Handling HTTP requests
• Input validation
• Returning HTTP responses

Services

Contain business logic:

• Orchestrate calls between layers
• Integrate external providers
• Handle rules and exceptions

Repositories

Responsible for:

• Database access
• Query execution
• Data persistence

Providers (simulated external services)

• Sellers

Database

• SQLite (simple and sufficient for this scope)

---

Domain Modeling

Item

• id: str
• title: str
• description: str
• price: Decimal
• currency: str
• category_id: int
• seller_id: str (external reference)
• photos: JSON (list of URLs)
• stock: int
• created_at: datetime

---

Category

• id: str
• name: str (unique, normalized)

---

Review

• id: str
• item_id: str
• rating: Decimal
• comment: str
• author: str
• created_at: datetime

---

Relationships

• Category (1) → (N) Item
• Item (1) → (N) Review

---

API Documentation

The API is documented using:

apidocs.yaml with swagger on /apidocs.

It includes:

• Endpoints
• Request/Response structures
• Data models

GET /items

Responsible for returning a paginated list of items with summarized data.

Query params (optional)

• offset
• limit

Response

{
  "items": [
    {
      "currency": "BRL",
      "id": "b7f92057-18a0-4c12-a4e8-f3ff50e2c101",
      "photos": [
        "https://example.com/notebook-1.jpg",
        "https://example.com/notebook-2.jpg"
      ],
      "price": 4999.9,
      "rating": 4.8,
      "title": "Notebook Gamer"
    }
  ],
  "pagination": {
    "has_next": false,
    "has_prev": false,
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

---

GET /items/{id}

Main endpoint

Responsible for returning complete item details with related items, reviews and seller info

Response

{
  "category": {
    "id": "c3a4d4...d1e888",
    "name": "Eletronicos"
  },
  "item": {
    "category_id": "c3a4d4...d1e888",
    "created_at": "22/04/2026 10:10:00",
    "currency": "BRL",
    "description": "Notebook com 16GB RAM e RTX",
    "id": "b7f92057-18a0-4c12-a4e8-f3ff50e2c101",
    "photos": [
      "https://example.com/notebook-1.jpg",
      "https://example.com/notebook-2.jpg"
    ],
    "price": 4999.90,
    "seller_id": "seller-123",
    "stock": 8,
    "title": "Notebook Gamer",
    "updated_at": "22/04/2026 10:15:00"
  },
  "related_items": [
    {
      "currency": "BRL",
      "id": "f1192...c999",
      "photos": [
        "https://example.com/mouse-1.jpg"
      ],
      "price": 199.9,
      "title": "Mouse Gamer"
    }
  ],
  "reviews": {
    "items": [
      {
        "author": "Taynna",
        "comment": "Muito bom",
        "created_at": "22/04/2026 10:20:00",
        "id": "9de10...d6f1222",
        "item_id": "b7f92...c101",
        "rating": 4.5,
        "updated_at": "22/04/2026 10:20:00"
      }
    ],
    "summary": {
      "average": 4.5,
      "count": 2
    }
  },
  "seller": {
    "id": "seller-123",
    "location": {
      "city": "Sao Paulo",
      "state": "SP"
    },
    "nickname": "Loja Tech Brasil",
    "official_store": true,
    "positive_rating": 4.8,
    "sales_completed": 1543,
    "seller_level": "MercadoLider Gold"
  }
}

---

POST /items

Creates a new item.

Response

{
  "category_id": "c3a4d427-ef4f-49d2-9d9f-3c9306d1e888",
  "created_at": "22/04/2026 10:10:00",
  "currency": "BRL",
  "description": "Notebook com 16GB RAM e RTX",
  "id": "b7f92057-18a0-4c12-a4e8-f3ff50e2c101",
  "photos": [
    "https://example.com/notebook-1.jpg",
    "https://example.com/notebook-2.jpg"
  ],
  "price": 4999.90,
  "seller_id": "seller-123",
  "stock": 8,
  "title": "Notebook Gamer",
  "updated_at": "22/04/2026 10:10:00"
}

---

POST /items/{id}/reviews

Adds a review to an item.

Response

{
  "author": "Taynna",
  "comment": "Muito bom",
  "created_at": "2026-04-22T10:20:00",
  "id": "9de10449-d3d6-4a2a-ae2c-3f6b5d6f1222",
  "item_id": "b7f92057-18a0-4c12-a4e8-f3ff50e2c101",
  "rating": 4.5
}

Additional endpoints, check /apidocs page

---

Design Decisions & Tradeoffs

Seller as an external provider

• Simulates domain separation
• Avoids modeling non-core data
• Represents real-world service integration

Tradeoff: adds orchestration complexity

---

Reviews stored locally

• Enables simple aggregation (average, count)
• Avoids unnecessary external dependencies

Tradeoff: less realistic in distributed systems

---

Item rating calculated at query time

• Prevents data inconsistency
• Simplifies update logic

Tradeoff: additional query cost (acceptable for this scope)

---

Photos stored as JSON

• Avoids creating extra tables and repositories
• No need for querying or indexing images

Tradeoff: not normalized, less flexible for future changes

---

Category as an internal detail

• Simplifies API usage (no need to pass IDs)
• Avoids expanding scope with extra endpoints

Tradeoff: slight internal coupling

---

Recommendations based on category

• Simple approach
• Avoids over-engineering (no ML or external service)

Tradeoff: less sophisticated than real systems

---

How to run the project

Access engine directory

• Install dependencies:

  pip install -r requirements.txt

• Set the env. vars

  Variable	Example	Required	Description
  ENVIRONMENT	development	True	Defines wich environment the app will run. Values are: testing, development and production
  FLASK_APP	app	True	Inform the flask application for Flask framework

• Then start the application with:

  flask run

---

Tests

The project is divided into a multi-level testing strategy:

• Unit Tests (services) → isolated business logic
• Integration Tests (repositories) → real database interaction
• E2E Tests (API) → full request lifecycle

Pros:

• High confidence in system behavior
• Strong regression protection

Trade-off:

• Higher implementation effort

Unit Tests

• Focus on service layer
• Heavy use of mocks
• Validate business rules

Integration Tests

• Focus on repositories
• Use SQLite in memory
• Validate real database queries

E2E Tests

• Test the API via HTTP
• Validate:
  • full request flow
  • database persistence (for write operations)
  • API contract (via JSON Schema)

How to run tests

Env. vars

set ENVIRONMENT as testing and FLASK_APP as engine.app

Then run:

python -m unittest discover -s .\engine\tests\ -t .\engine\tests\

---

Possible Improvements

• Caching for item detail endpoint and external providers.
• Pagination for reviews and related products.
• Async handling for external providers.
• Circuit breaker / retry strategies.
• Dedicated recommendation service.
• Use of presenters.
• API Versioning.
• Filtering in item listing.
• Docker to isolate and execute the application.
• Database versioning

Authentication & Authorization (Future Work)

Authentication was not implemented as it is not required for the scope of this challenge.

In a production environment, this API would include:

• Oauth2/OpenID authentication
• Authorization rules (e.g., only sellers can create items)
• User identity propagation to/from external services

---

Conclusion

This project focuses on:

• Solving the core problem effectively (item detail aggregation)
• Keeping the design simple but robust
• Demonstrating clear architectural decisions
• Avoiding unnecessary complexity

The result is a clean, maintainable, and realistic backend solution aligned with real-world scenarios.