MachaOn-C1 Backend

The MachaOn-C1 Backend is a robust and scalable microservice designed to support core business functionalities for the Machanism ecosystem. It builds on the foundation of FastAPI and integrates with external systems, providing highly modular and secure APIs for managing users, products, orders, and other entities. By adhering to Clean Architecture principles, MachaOn-C1 ensures maintainability, scalability, and flexibility for evolving business needs.

Key Features

1. JWT-Based Authentication:

   • Supports secure user authentication and authorization using JSON Web Tokens (JWT).
   • Protects sensitive endpoints (e.g., user data, order creation) via token verification.

2. RESTful APIs:

   • Provides well-structured, RESTful endpoints for efficient communication with frontend applications.
   • Supports CRUD operations and integration workflows for seamless client interactions.

3. Integration with External Systems:

   • Utilizes adapters for Commercetools or other third-party systems for user registration, product management, and order processing.
   • Ensures modularity by decoupling integrations from core system logic.

4. Configuration Management:

   • Manages environment-specific configurations (e.g., API keys) with a centralized configurator.

Core Functionalities

1. User Management

• User Login:

  • Handles POST /login requests to authenticate users and return a JWT if credentials are valid.
  • Integrates with the Commercetools User Adapter to validate credentials.

• User Registration:

  • Supports POST /registration requests for creating new users.
  • Captures user details and delegates registration logic to the Commercetools backend.

2. Product Management

• View Products:
  • Exposes GET /products to retrieve a list of products.
  • Includes details such as product ID, title, price, and image.

3. Order Processing

• Create Order:
  • Handles POST /order requests to place an order.
  • Verifies the JWT token before creating the order.
  • Mock order ID is generated and provided as a response.

Architecture

Clean Architecture Principles

• Use Cases (Core Business Logic):

  • Handles workflows like user authentication, registration, and product retrieval.

• Adapters:

  • Bridges the gap between core interactors and external systems such as Commercetools or databases.

• Frameworks and Drivers:

  • Provides an abstraction layer for frameworks like FastAPI and external APIs.

Technology Stack

• API Framework: FastAPI
• Authorization: JWT (via PyJWT)
• External Integration: Commercetools Adapter
• Language: Python (>=3.12)

Endpoint Overview

Method	Endpoint	Protected	Description
POST	/login	❌ No	Authenticates a user and returns a JWT token.
POST	/registration	❌ No	Register a new user.
GET	/products	❌ No	Returns a list of available products.
POST	/order	✔ Yes	Places an order based on user credentials.

Integration with Commercetools

The backbone of MachaOn-C1 Backend is its seamless integration with Commercetools, which acts as the primary backend for managing users, products, and orders.

• User Login:

  • Validates user credentials against Commercetools' customer APIs.
  • Relies on the Commercetools User Adapter for implementation.

• User Registration:

  • Registers new customers in the Commercetools backend via the POST /customers API.

• Product Retrieval:

  • Uses mocked or pre-configured product data for simplicity, but production deployment can pull real-time data from Commercetools.

Error Handling

The backend implements robust error handling for all endpoints:

• 401 Unauthorized: For invalid JWT tokens or missing credentials.
• 500 Internal Server Error: For unexpected exceptions or external API failures.

Project Scalability

1. Microservice Ready: Each REST service can function as an independent, loosely coupled microservice.
2. Cloud Native: Designed to deploy on cloud platforms with containerization support (e.g., AWS Lambda, Azure Functions).
3. Extensibility: Easily customizable to integrate with additional systems such as ERP, payment gateways, or customer analytics.

Here’s how you can execute the instructions you provided, along with an enhanced explanation to guide users through cloning, running, and testing the MachaOn-C1 Backend project.

Cloning the MachaOn-C1 Backend Project

To retrieve the source code from the SVN repository, follow these steps:

1. Clone the backend project using git svn clone:

$ git svn clone https://svn.code.sf.net/p/machc/svn/trunk/machaon/containers/machaon-c1/backend

1. Move into the cloned project directory:

$ cd backend

Installing Dependencies

Ensure all required Python libraries are installed before running the project.

1. Check for a requirements.txt file: The requirements.txt file typically lists all required dependencies (e.g., fastapi, uvicorn, pyjwt).

2. Install Dependencies: Run the following command to install the libraries:

PS machaon-c1\backend> python -m venv .venv  
PS machaon-c1\backend> .venv\Scripts\activate

(venv) PS machaon-c1\backend> pip install -r requirements.txt

1. Build Docker Image: Run the following command to build docker image:

PS machaon-c1\backend> docker build --no-cache -t machaon-c1 .
PS machaon-c1\backend> docker run -p 8000:8000 -e CTP_CLIENT_SECRET=$Env:CTP_CLIENT_SECRET machaon-c1

1. Run App: Run the following command to run appliation locally:

(venv) PS machaon-c1\backend> cd src
(venv) PS machaon-c1\backend\src> uvicorn app:app --host 0.0.0.0 --port 8000

Open Swagger UI for API Testing

FastAPI automatically generates an interactive API documentation (Swagger UI). To access it:

1. Open your browser.

2. Navigate to:

   • Swagger UI: http://127.0.0.1:8000/docs
   • ReDoc Documentation: http://127.0.0.1:8000/redoc

Here, you can test all available REST endpoints of the MachaOn-C1 Backend interactively.