Bazaar is a full-stack marketplace platform built on a microservices architecture. It enables users to buy and sell products through a mobile application, while administrators manage the ecosystem via a dedicated backoffice panel. The platform handles the complete e-commerce lifecycle — from product listing and discovery, through shopping cart management and secure checkout with Mercado Pago integration, to order tracking, delivery status updates, and review systems.

1. Platform Architecture
2. Repository Map
3. Technology Stack
4. Getting Started
5. Infrastructure & Networking
6. Observability
7. Testing
8. Contributing
9. License

All client traffic flows through a centralized API Gateway (Kong), which handles JWT authentication, CORS, identity header injection, and distributed tracing before routing requests to the appropriate downstream microservice.

graph TD
    Mobile([Mobile App<br>React Native / Expo]) -->|HTTPS| Gateway[API Gateway<br>Kong 3.6]
    Backoffice([🖥️ Admin Backoffice<br>Next.js]) -->|HTTPS| Gateway

    subgraph Backend Microservices
        Gateway -->|X-User-Id / X-User-Role| UserAPI[User API<br>Java · Spring Boot]
        Gateway -->|X-User-Id / X-User-Role| CatalogAPI[Catalog API<br>Python · FastAPI]
        Gateway -->|X-User-Id / X-User-Role| CartAPI[Cart API<br>Kotlin · Spring Boot]
        Gateway -->|X-User-Id / X-User-Role| OrdersAPI[Orders API<br>Java · Spring Boot]
    end

    subgraph Data Stores
        UserAPI --> PG_User[(PostgreSQL)]
        CatalogAPI --> PG_Catalog[(PostgreSQL)]
        CartAPI --> Mongo[(MongoDB)]
        OrdersAPI --> PG_Orders[(PostgreSQL)]
    end

    subgraph External Services
        UserAPI --> Cloudinary[Cloudinary CDN]
        UserAPI --> Google[Google OAuth2]
        UserAPI --> Email[SendGrid / SMTP]
        OrdersAPI --> MercadoPago[Mercado Pago]
    end

    subgraph Messaging
        OrdersAPI --> RabbitMQ[RabbitMQ]
        CartAPI --> RabbitMQ
        CatalogAPI --> RabbitMQ
    end

    subgraph Observability
        Gateway --> OTEL[OpenTelemetry Collector]
        UserAPI --> OTEL
        OrdersAPI --> OTEL
    end

The organization is structured into 8 repositories, each with a clear boundary of responsibility:

Reverse proxy and API Gateway built on Kong 3.6 (db-less/declarative mode). Single entry point for all client requests.

Identity, authentication, and user profile management microservice.

Product catalog management — listing, searching, filtering, and media upload.

Shopping cart lifecycle management — item additions, quantity updates, and cart persistence.

Checkout orchestration, payment processing, order lifecycle tracking, and review system.

Web-based administration panel for platform operators.

Cross-platform mobile marketplace application for buyers and sellers.

Centralized cross-cutting documentation hub.

• Docker & Docker Compose
• Java 21 (JDK) — for User, Cart, and Orders APIs
• Python 3.11+ — for Catalog API
• Node.js — for Mobile App and Admin Backoffice

All microservices communicate over a shared Docker network:

docker network create bazaar-network

# Clone all repositories into a workspace directory
git clone https://github.com/Baza-ar/api-gateway.git
git clone https://github.com/Baza-ar/api-user.git
git clone https://github.com/Baza-ar/Catalog.git api-catalog
git clone https://github.com/Baza-ar/api-cart.git
git clone https://github.com/Baza-ar/api-orders.git
git clone https://github.com/Baza-ar/admin-backoffice.git
git clone https://github.com/Baza-ar/app-mobile.git
git clone https://github.com/Baza-ar/technical-docs.git

Each service requires a .env file. Copy the example templates:

cp api-gateway/.env.example   api-gateway/.env
cp api-user/.env.example       api-user/.env
cp api-catalog/.env.example    api-catalog/.env
cp api-cart/.env.example       api-cart/.env
cp api-orders/.env.example     api-orders/.env

Launch the services in the recommended order:

# 1. Start the API Gateway
cd api-gateway && docker-compose up --build -d && cd ..

# 2. Start the User API
cd api-user && docker-compose up --build -d && cd ..

# 3. Start the Catalog API
cd api-catalog && docker-compose up -d && cd ..

# 4. Start the Cart API
cd api-cart && docker-compose up --build -d && cd ..

# 5. Start the Orders API
cd api-orders && docker-compose up --build -d && cd ..

# 6. Start the Admin Backoffice (development)
cd admin-backoffice && npm install && npm run dev &
cd ..

# 7. Start the Mobile App (development)
cd app-mobile && npm install && npx expo start --clear &

curl http://localhost:8000/health
# Expected: {"status": "UP", "gateway": "Kong"}

All services run in Docker containers connected via the bazaar-network bridge network. Each service has its own docker-compose.yml defining its container, database, and dependency setup.

The platform integrates OpenTelemetry for distributed tracing across the gateway and backend services:

• API Gateway: Exports request-level traces via the Kong OpenTelemetry plugin.
• User API & Orders API: Instrumented with the OpenTelemetry Java Agent for automatic span collection.
• Spring Boot Actuator: Exposes /actuator/health, /livez, and /readyz endpoints for liveness and readiness probes.
• Metrics: Micrometer integration ready for Prometheus/Grafana dashboards.

Load tests are available in the api-gateway/test/k6/scripts/ directory and can be executed via Dockerized k6:

docker run --rm --network bazaar-network \
  -v "$(pwd)/test/k6:/io" -w /io \
  grafana/k6 run scripts/<test_name>.js

Available scripts: login-stress.js, register-stress.js, create-product-stress.js, checkout-stress.js

1. Branch naming: Use feature/<description> or fix/<description>.
2. Pull Requests: All changes require a PR with peer review before merging into main.
3. Documentation: Update the relevant repository README and the technical-docs repo for cross-cutting changes.
4. Code Quality: Run linters and formatters before committing. Each repo has its own ESLint/Prettier or equivalent configuration.

This project is licensed under the MIT License. See the LICENSE files in each repository for details.