docs: improve and restructure README for better clarity by unnatii14 · Pull Request #12 · keploy/ecommerce_sample_app

unnatii14 · 2026-02-25T19:24:46Z

Summary

Fixes #9

Rewrote the README from scratch to improve onboarding experience for new contributors and users running the project locally.

Changes Made

Services table — ports and responsibilities at a glance
Quick Start — 3-command setup with health check, logs, and teardown
API Reference — endpoint tables per service + working curl auth example
Architecture — plain-text diagram showing API Gateway, all services, databases, and SQS flow
Key behaviours — idempotency, JWT flow, stock reservation, SQS events explained
Testing — Keploy AI vs manual test suites documented with run commands
Project Layout — annotated directory tree
Configuration — all environment variables documented with production notes
Contributing — fork → branch → test → commit → PR workflow with Conventional Commits

Type of Change

Documentation only (no functional changes)

Testing

No code was changed. README was validated for:

Zero non-ASCII / garbled characters
All commands verified against actual docker-compose.yml and service code
Encoding checked clean (0 non-ASCII characters)

Related Issue

Closes #9

- Add services table with ports and responsibilities - Add quick start with health check, logs, and teardown commands - Add API reference table with auth token curl example - Add plain-text architecture diagram showing Gateway + services + SQS - Add testing section documenting Keploy AI and manual test suites - Add project layout, configuration, and contributing guide - Remove MIT license section (not applicable) - Fix all encoding issues (zero non-ASCII characters) Closes keploy#9 Signed-off-by: Unnati <unnatitank14@gmail.com>

Copilot

Pull request overview

Rewrites and restructures the root README to improve onboarding and make local setup, architecture, API usage, testing, and contribution workflow easier to understand.

Changes:

Adds a services/ports/responsibilities table and a streamlined local Quick Start flow.
Documents gateway-based API usage with auth curl example plus endpoint tables.
Expands architecture/testing/project layout/configuration/contributing sections.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-25T19:32:46Z

README.md

+All requests go through the gateway at `http://localhost:8083`. Every endpoint except `/api/v1/login` and `/health` requires `Authorization: Bearer <token>`.
+


This sentence excludes /health from auth, but /health isn’t currently implemented by the gateway/services. Either remove /health here or add the endpoint so the auth guidance matches reality.

Copilot · 2026-02-25T19:32:46Z

README.md

+Client --> API Gateway (:8083)
+            |-- /users/*    --> User Service (:8082)    --> mysql-users (:3307)
+            |-- /products/* --> Product Service (:8081) --> mysql-products (:3308)
+            |-- /orders/*   --> Order Service (:8080)   --> mysql-orders (:3309)


The architecture diagram paths (/users/*, /products/*, /orders/*) don’t match the actual gateway routes (/api/v1/users/*, etc.). Consider updating the diagram to include the /api/v1 prefix to avoid confusion when trying the curl examples.

Copilot · 2026-02-25T19:32:47Z

README.md

+- `POST /orders` validates the user, reserves product stock, persists the order, then emits an `ORDER_CREATED` event to SQS.
+- Supports `Idempotency-Key` header on order creation to prevent duplicates.
+- Cancelling an order releases reserved stock and emits `ORDER_CANCELLED`.


These ‘Key behaviours’ bullets don’t match the implementation: the order endpoint is /api/v1/orders (not /orders), and the SQS event types emitted by order_service are order_created / order_cancelled (lowercase), not ORDER_CREATED / ORDER_CANCELLED. Align the README wording with the actual routes/event payloads.

Suggested change

- `POST /orders` validates the user, reserves product stock, persists the order, then emits an `ORDER_CREATED` event to SQS.

- Supports `Idempotency-Key` header on order creation to prevent duplicates.

- Cancelling an order releases reserved stock and emits `ORDER_CANCELLED`.

- `POST /api/v1/orders` validates the user, reserves product stock, persists the order, then emits an `order_created` event to SQS.

- Supports `Idempotency-Key` header on order creation to prevent duplicates.

- Cancelling an order releases reserved stock and emits `order_cancelled`.

Copilot · 2026-02-25T19:32:47Z

README.md

+
+**Key behaviours:**
+- `POST /orders` validates the user, reserves product stock, persists the order, then emits an `ORDER_CREATED` event to SQS.
+- Supports `Idempotency-Key` header on order creation to prevent duplicates.


The README claims idempotency “prevents duplicates”, but the current behavior is enforced via a DB unique constraint on idempotency_key; duplicate submissions will fail the insert and the API returns a 500 rather than returning the original order. Either document that behavior, or implement true idempotency by looking up and returning the existing order when the same Idempotency-Key is reused.

Suggested change

- Supports `Idempotency-Key` header on order creation to prevent duplicates.

- `POST /orders` accepts an `Idempotency-Key` header; this is stored with a DB unique constraint on `idempotency_key`, so reusing the same key currently triggers a 500 error from the unique-constraint violation rather than returning the original order.

Copilot · 2026-02-25T19:32:47Z

README.md

 ```

-Key behaviors
+Coverage reports are written to `coverage/` during test runs.


“Coverage reports are written to coverage/” is incomplete/misleading: the coverage data files are written under the top-level coverage/ volume, but the HTML output is generated under each service’s */coverage/htmlcov/ directory. Consider clarifying where to find the HTML report.

Suggested change

Coverage reports are written to `coverage/` during test runs.

Coverage data is written to the shared `coverage/` volume during test runs, while per-service HTML reports are generated under each service’s `*/coverage/htmlcov/` directory (for example, `order_service/coverage/htmlcov/index.html`).

Copilot · 2026-02-25T19:32:48Z

README.md

+Set in `docker-compose.yml`. Key variables:
+
+| Variable | Default | Note |
+|---|---|---|
+| `JWT_SECRET` | `dev-secret-change-me` | **Must change in production** |
+| `DB_HOST / DB_USER / DB_PASSWORD / DB_NAME` | per-service | Each service owns its own DB |
+| `AWS_ENDPOINT` | `http://localstack:4566` | Routes SQS traffic to LocalStack |
+| `ADMIN_PASSWORD` | `admin123` | Seeded admin credentials |


This section says variables are “Set in docker-compose.yml”, but JWT_SECRET is not actually set in docker-compose.yml (services fall back to the in-code default), and the seeded admin password comes from the SQL migration (hard-coded admin/admin123), not the ADMIN_PASSWORD env var. Update the table/wording to reflect the real defaults and which env vars are actually consumed.

Suggested change

Set in `docker-compose.yml`. Key variables:

| Variable | Default | Note |

|---|---|---|

| `JWT_SECRET` | `dev-secret-change-me` | **Must change in production** |

| `DB_HOST / DB_USER / DB_PASSWORD / DB_NAME` | per-service | Each service owns its own DB |

| `AWS_ENDPOINT` | `http://localstack:4566` | Routes SQS traffic to LocalStack |

| `ADMIN_PASSWORD` | `admin123` | Seeded admin credentials |

Configuration & defaults (from env, code, and migrations):

| Variable | Default | Note |

|---|---|---|

| `JWT_SECRET` | `dev-secret-change-me` (in-code) | Used by the User Service for JWT signing; override via `JWT_SECRET` env var (**must change in production**) |

| `DB_HOST / DB_USER / DB_PASSWORD / DB_NAME` | per-service | Each service owns its own DB; values typically set via `docker-compose.yml` |

| `AWS_ENDPOINT` | `http://localstack:4566` | Routes SQS traffic to LocalStack (e.g. `http://localstack:4566` in Docker) |

| Admin credentials | `admin / admin123` (SQL migration) | Initial admin user is seeded by migration; current seeding does not read `ADMIN_PASSWORD` env var |

Copilot · 2026-02-25T19:32:48Z

README.md

+**Health check:**
+```bash
+curl http://localhost:8083/health


curl http://localhost:8083/health won’t work as written: the API gateway implementation doesn’t expose a /health route (and none of the Flask apps define it). Update the README to point to an actual unauthenticated endpoint (e.g. POST /api/v1/login) or add /health handlers in code (and keep docs consistent).

Suggested change

**Health check:**

```bash

curl http://localhost:8083/health

**Quick auth check (via API Gateway):**

```bash

curl -X POST http://localhost:8083/api/v1/login \

-H "Content-Type: application/json" \

-d '{"username": "admin", "password": "admin123"}'

Copilot AI review requested due to automatic review settings February 25, 2026 19:24

unnatii14 requested a review from charankamarapu as a code owner February 25, 2026 19:24

Copilot started reviewing on behalf of unnatii14 February 25, 2026 19:25 View session

unnatii14 force-pushed the docs/improve-readme branch from 045cf83 to e34fb81 Compare February 25, 2026 19:26

Copilot AI reviewed Feb 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: improve and restructure README for better clarity#12

docs: improve and restructure README for better clarity#12
unnatii14 wants to merge 1 commit intokeploy:mainfrom
unnatii14:docs/improve-readme

unnatii14 commented Feb 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Copilot AI Feb 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		All requests go through the gateway at `http://localhost:8083`. Every endpoint except `/api/v1/login` and `/health` requires `Authorization: Bearer <token>`.

	- Supports `Idempotency-Key` header on order creation to prevent duplicates.
	- `POST /orders` accepts an `Idempotency-Key` header; this is stored with a DB unique constraint on `idempotency_key`, so reusing the same key currently triggers a 500 error from the unique-constraint violation rather than returning the original order.

	Coverage reports are written to `coverage/` during test runs.
	Coverage data is written to the shared `coverage/` volume during test runs, while per-service HTML reports are generated under each service’s `*/coverage/htmlcov/` directory (for example, `order_service/coverage/htmlcov/index.html`).

-**Health check:**
-```bash
-curl http://localhost:8083/health
+**Quick auth check (via API Gateway):**
+```bash
+curl -X POST http://localhost:8083/api/v1/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "admin", "password": "admin123"}'

Uh oh!

Conversation

unnatii14 commented Feb 25, 2026

Summary

Changes Made

Type of Change

Testing

Related Issue

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants