From 34e5bb29d2b1e7109687b7418923cea4b6bc544e Mon Sep 17 00:00:00 2001
From: Abhee Vasava <101612447+Jerry-145@users.noreply.github.com>
Date: Tue, 24 Feb 2026 10:11:34 +0530
Subject: [PATCH] Improve README with complete architecture, setup
 instructions, and testing documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous README lacked clarity around project structure, service responsibilities, infrastructure setup, and testing workflows. This update introduces a fully structured README that improves onboarding for new contributors and simplifies understanding of how services interact.

Key Improvements
1. Architecture Clarity

Added a structured overview of all services.

Documented infrastructure components including MySQL, Docker Compose, and LocalStack SQS.

Added reference to architecture documentation.

2. Project Structure

Provided a complete directory tree.

Clearly separated services and infrastructure folders.

Documented migrations, testing folders, and coverage files.

3. Setup Instructions

Added Docker Compose commands for:

Starting services

Viewing logs

Stopping services

4. Service Responsibilities

Detailed responsibilities added for:

API Gateway

Order Service

Product Service

User Service

Including order lifecycle and idempotency handling.

5. Database Documentation

Explained migration flow.

Clarified DB ownership per service.

6. Messaging Flow

Documented LocalStack SQS usage.

Added queue setup script references.

7. Testing Documentation

Documented Keploy usage.

Added explanation of AI-generated tests (test1.yaml → test36.yaml).

Included coverage of test scenarios:

Order lifecycle

Product management

User validation

Gateway routing

Edge cases

8. Contribution Workflow

Added contributor steps.

Clarified development workflow.
---
 README.md | 499 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 397 insertions(+), 102 deletions(-)

diff --git a/README.md b/README.md
index 37686c5..e434f7b 100644
--- a/README.md
+++ b/README.md
@@ -1,105 +1,400 @@
-# E-commerce Microservices (Python, Flask, MySQL, SQS)
-
-Services
-
-- order_service (A): REST + MySQL + publishes SQS order events
-- product_service (B): REST + MySQL (catalog)
-- user_service (C): REST + MySQL (users)
-
-Infra
-
-- 3x MySQL containers
-- LocalStack (SQS)
-- Docker Compose to orchestrate
-
-Quick start
-
-- docker compose up -d --build
-- docker compose logs -f order_service product_service user_service
-- docker compose down -v
-
-APIs
-
-- OpenAPI specs in each service under openapi.yaml
-
-# E-commerce Microservices Architecture
-
-This repo contains three Python (Flask) microservices orchestrated with Docker Compose, each with its own MySQL database, plus LocalStack SQS for messaging.
-
-## Architecture (single diagram)
-
-```mermaid
-flowchart LR
-  client([Client / Postman])
-
-  subgraph "Order Service :8080"
-    order_svc([Order Service])
-    o1["POST /api/v1/orders"]
-    o2["GET /api/v1/orders"]
-    o3["GET /api/v1/orders/{id}"]
-    o4["GET /api/v1/orders/{id}/details"]
-    o5["POST /api/v1/orders/{id}/pay"]
-    o6["POST /api/v1/orders/{id}/cancel"]
-    o7["GET /health"]
-    order_svc --- o1
-    order_svc --- o2
-    order_svc --- o3
-    order_svc --- o4
-    order_svc --- o5
-    order_svc --- o6
-    order_svc --- o7
-  end
-
-  subgraph "Product Service :8081"
-    product_svc([Product Service])
-    p1["CRUD /api/v1/products"]
-    p2["POST /api/v1/products/{id}/reserve"]
-    p3["POST /api/v1/products/{id}/release"]
-    p4["GET /api/v1/products/search"]
-    p5["GET /health"]
-    product_svc --- p1
-    product_svc --- p2
-    product_svc --- p3
-    product_svc --- p4
-    product_svc --- p5
-  end
-
-  subgraph "User Service :8082"
-    user_svc([User Service])
-    u1["POST /api/v1/users"]
-    u2["GET /api/v1/users/{id}"]
-    u3["POST /api/v1/login"]
-    u4["GET /health"]
-    user_svc --- u1
-    user_svc --- u2
-    user_svc --- u3
-    user_svc --- u4
-  end
-
-  subgraph Datastores
-    dborders[(MySQL order_db)]
-    dbproducts[(MySQL product_db)]
-    dbusers[(MySQL user_db)]
-  end
-
-  sqs[(LocalStack SQS: order-events)]
-
-  client --> order_svc
-  client --> product_svc
-  client --> user_svc
-
-  order_svc --> dborders
-  product_svc --> dbproducts
-  user_svc --> dbusers
-
-  order_svc --> user_svc
-  order_svc --> product_svc
-
-  order_svc --> sqs
+make this perfect
+
+# 📦 E-commerce Microservices
+
+**Tech Stack:** Python • Flask • MySQL • Docker • LocalStack (SQS) • Keploy
+
+This repository implements a **microservices-based e-commerce backend** built using **Flask**.  
+Each service runs independently with its own database and communicates via **REST APIs** and **AWS SQS (LocalStack)** for event-driven workflows.
+
+---
+
+## 🏗️ Architecture Overview
+
+### Services
+
+| Service | Responsibility |
+|---|---|
+| API Gateway | Entry point & request routing |
+| Order Service | Order lifecycle management |
+| Product Service | Product catalog & inventory |
+| User Service | User management |
+
+### Infrastructure
+
+- **MySQL** → Separate database per service  
+- **LocalStack SQS** → Messaging queue simulation  
+- **Docker Compose** → Service orchestration  
+
+Architecture documentation:
+
+
+docs/architecture.md
+
+
+---
+
+## 📁 Project Structure
+
+
+apigateway/
+
+├── app.py
+
+├── entrypoint.sh
+
+└── openapi.yaml
+
+
+order_service/
+
+├── app.py
+
+├── db.sql
+
+├── entrypoint.sh
+
+├── keploy.yml
+
+├── migrate.py
+
+├── openapi.yaml
+
+├── requirements.txt
+
+├── migrations/
+
+│ ├── 0001_init.sql
+
+│ └── 0002_shipping_address_id.sql
+
+└── keploy/
+
+├── ai/tests/test1.yaml → test36.yaml
+
+└── manual/tests/
+
+
+product_service/
+
+├── app.py
+
+├── db.sql
+
+├── entrypoint.sh
+
+├── keploy.yml
+
+├── migrate.py
+
+├── openapi.yaml
+
+├── requirements.txt
+
+├── migrations/
+
+│ ├── 0001_init.sql
+
+│ └── 0002_shipping_address_id.sql
+
+└── keploy/
+
+├── ai/tests/test1.yaml → test36.yaml
+
+└── manual/tests/
+
+user_service/
+├── app.py
+
+├── db.sql
+
+├── entrypoint.sh
+
+├── keploy.yml
+
+├── migrate.py
+
+├── openapi.yaml
+
+├── requirements.txt
+
+├── migrations/
+
+│ ├── 0001_init.sql
+
+│ └── 0002_shipping_address_id.sql
+
+└── keploy/
+
+├── ai/tests/test1.yaml → test36.yaml
+
+└── manual/tests/
+
+localstack/
+
+├── 01-create-queues.sh
+
+└── 01-queues.sh
+
+postman/
+
+├── collection.gateway.json
+
+├── collection.microservices.json
+
+└── environment/local.json
+
+
+coverage/
+
+├── .coverage.apigateway.combined
+
+├── .coverage.order_service.combined
+
+├── .coverage.product_service.combined
+
+└── .coverage.user_service.combined
+
+
+
+---
+
+## 🚀 Quick Start
+
+### 1️⃣ Start Services
+```bash
+docker compose up -d --build
 ```
+**2️⃣ View Logs**
+```bash
+docker compose logs -f apigateway order_service product_service user_service
+```
+**3️⃣ Stop Services**
+```bash
+docker compose down -v
+```
+**🔌 Services Description**
+
+API Gateway
+
+Location: apigateway/
+
+**Responsibilities:**
+
+- Routes external requests to services
+
+- Aggregates responses when required
+
+- Provides OpenAPI documentation
+
+**Order Service**
+
+Location: order_service/
+
+**Responsibilities:**
+
+- Create orders
+
+- Validate users via user_service
+
+- Validate products via product_service
+
+- Reserve/release stock
+
+**Persist orders**
+
+- Publish SQS events
+
+- Order Status Flow
+- PENDING → PAID
+- PENDING → CANCELLED (releases stock)
+- Idempotency
+
+**Uses header:**
+
+- Idempotency-Key
+
+- Prevents duplicate order creation.
+
+- Product Service
+
+**Location**: product_service/
+
+Responsibilities:
+
+- Product CRUD
+
+- Stock management
+
+- Stock reservation for orders
+
+- User Service
+
+- Location: user_service/
+
+**Responsibilities:**
+- User CRUD
+
+- User validation for orders
+
+**🗄️ Database**
+
+Each service has:
+
+- db.sql
+- migrations/
+- migrate.py
+
+Migrations run automatically via container entrypoint.
+
+**📨 Messaging (SQS via LocalStack)**
+
+Setup scripts:
+
+localstack/01-create-queues.sh
+localstack/01-queues.sh
+
+Used for:
+
+- Order events
+
+- Async processing
+
+**🧪 Testing (Keploy)**
+
+Each service includes:
+
+keploy/
+  ai/tests/
+  manual/tests/
+Test Cases
+
+**AI-generated tests:**
+
+- test1.yaml
+- Coverage Includes
+- Order Service Tests
+
+- Create order success
+
+- Duplicate order prevention
+
+- Invalid user
+
+- Invalid product
+
+- Stock unavailable
+
+- Order cancellation
+
+- Order payment
+
+- Idempotency validation
+
+- Product Service Tests
+
+- Create product
+
+- Update product
+
+- Delete product
+
+- Stock updates
+
+- Reserve stock
+
+- Release stock
+
+**User Service Tests**
+
+- Create user
+
+- Update user
+
+- Delete user
+
+- Fetch user
+
+- Invalid user scenarios
+
+**Gateway Tests**
+
+- Routing validation
+
+- Aggregated responses
+
+- Error propagation
+
+- Edge Cases
+
+- Invalid payload
+
+- Missing headers
+
+- Service unavailable
+
+- Database failures
+
+**📬 API Documentation**
+
+Each service exposes:
+
+- openapi.yaml
+
+**Postman collections:**
+
+postman/
+Environment:
+environment/local.json
+**📊 Coverage Reports**
+
+Coverage stored in:
+coverage/
+- Contains combined coverage per service.
+
+**🛠️ Development Workflow**
+- Adding a New Endpoint
+
+- Update app.py
+
+- Update openapi.yaml
+
+- Add DB migration if needed
+
+- Add Keploy tests
+
+- Update Postman collection
+
+- Run services locally
+
+- Submit PR
+
+**🤝 Contributing**
+
+- Fork repository
+
+- Create feature branch
+
+- Commit changes
+
+- Add/update tests (test1 → test36 style)
+
+- Ensure services run
+
+- Create Pull Request
+
+**⚡ Order Creation Flow**
+
+Validate user
+
+Validate products
+
+Reserve stock
+
+Save order
+
+Publish SQS event
 
-Key behaviors
+**📜 License**
 
-- Order creation validates user and products, reserves stock, persists order + items, emits SQS event.
-- Idempotency: POST /orders supports Idempotency-Key to avoid duplicate orders.
-- Status transitions: PENDING → PAID or CANCELLED (cancel releases stock).
+Open source — follow repository license.