Improve and restructure README documentation for better clarity Issue 161

Abierto
  • ¿Algo no está bien?
#9 0 comentarios 0 reacciones 0 asignados Ver en GitHub

@Jerry-145 ya está trabajando en esto.

Desde el 24/2/2026.

  • #8 de @Jerry-145 — abierto
  • #12 de @unnatii14 — abierto

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
aws, docker-compose, mysql, python
Área
backend, databases, devops, documentation

Línea de trabajo

Comienza con README.md e inspecciona los servicios, las migraciones, los scripts de localstack, las pruebas de Keploy y las colecciones de Postman mencionados en el issue para verificar la arquitectura y los comandos disponibles. Documenta las responsabilidades de los servicios, el aislamiento de la base de datos, el flujo de trabajo de SQS, los procedimientos de configuración y pruebas, y los pasos para contribuir utilizando la estructura existente del repositorio. Se considera terminado cuando README.md cubre todos los criterios de aceptación sin cambios funcionales.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Python
Estrellas
3
Forks
11
Merge medio
1 h 6 min
PR fusionados (30 d)
3

Preparar el entorno

  • Incluye un Dockerfile o un archivo de Docker Compose
  • Sin plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de keploy/ecommerce_sample_app

Todos los issues de keploy/ecommerce_sample_app

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.