Improve and restructure README documentation for better clarity Issue 161 #9
Description
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.