Improve and restructure README documentation for better clarity Issue 161

**Overview**

The current README.md lacks detailed documentation about the project architecture, service responsibilities, setup instructions, testing workflow, and contribution guidelines. This can make onboarding difficult for new contributors and users trying to run the project locally.

**Proposed Changes**

Update the README to include:

**1. Architecture Overview**

Clear explanation of all services:

- API Gateway

- Order Service

- Product Service

- User Service

- Infrastructure components:

- MySQL per service

- Docker Compose orchestration

- LocalStack SQS messaging

**2. Project Structure**

- Add a complete directory tree.

Explain purpose of key folders:

- services

- migrations

- keploy tests

- localstack scripts

- postman collections

- coverage reports

**3. Setup Instructions**

Provide clear commands for:

- Starting services

- Viewing logs

- Stopping services

**4. Service Responsibilities**

Document responsibilities for each service including:

- Order lifecycle

- Product inventory handling

- User validation

- API gateway routing

**5. Database Documentation**

Explain:

- Migration usage

- Schema files

- DB isolation per service

**6. Messaging Workflow**

Document:

- SQS usage

- Queue setup scripts

- Event-driven communication

**7. Testing Documentation**

Add explanation for:

-
- Keploy testing setup

- AI-generated tests (test1.yaml → test36.yaml)

- Manual tests

- Coverage reports

**8. Contribution Guidelines**

Add steps for contributors:

- Fork

- Branch creation

- Testing

- Pull request submission

- Expected Outcome

- Better onboarding experience.

- Easier understanding of project structure.

- Clear testing workflow.

- Improved contributor experience.

**Additional Context**

This update is documentation-only and does not introduce any functional changes.

- Acceptance Criteria

- README includes architecture overview.

- Setup instructions are clear.

- Project structure documented.

- Testing workflow explained.

- Contribution steps included.

Start with README.md and inspect the services, migrations, localstack scripts, Keploy tests, and Postman collections named in the issue to verify the architecture and available commands. Document the service responsibilities, database isolation, SQS workflow, setup and testing procedures, and contribution steps using the repository’s existing structure. Done means the README covers every acceptance criterion without functional changes.

Written by the indexing model from the issue text.