Restructure READMEs: Move detailed instructions to component directories

- Simplified root README to be concise project overview
- Updated monolith/README.md with detailed setup instructions and current structure
- Updated system-test/README.md with comprehensive testing guide
- Root README now focuses on quick start and directs to component READMEs
- Removed outdated references to old directory structure
- Each component now has appropriate detailed documentation

Author: valentinajemuovic

README.md

@@ -6,128 +6,29 @@
 [![qa-signoff](https://github.com/optivem/atdd-accelerator-template-python/actions/workflows/qa-signoff.yml/badge.svg)](https://github.com/optivem/atdd-accelerator-template-python/actions/workflows/qa-signoff.yml)
 [![prod-stage](https://github.com/optivem/atdd-accelerator-template-python/actions/workflows/prod-stage.yml/badge.svg)](https://github.com/optivem/atdd-accelerator-template-python/actions/workflows/prod-stage.yml)
 
-This is a Python implementation of the ATDD (Acceptance Test-Driven Development) Accelerator Template, migrated from the original Java version. It provides a complete web application with API endpoints and UI for managing todos, built using FastAPI and modern Python practices.
+This is a Python implementation of the ATDD (Acceptance Test-Driven Development) Accelerator Template. It provides a walking skeleton for building applications using Test-Driven Development practices with Python and FastAPI.
 
-## Technology Stack
+## Structure
 
-- **Python 3.11+**: Modern Python with type hints
-- **FastAPI**: Modern, fast web framework for building APIs
-- **Uvicorn**: ASGI server implementation
-- **Pydantic**: Data validation using Python type annotations
-- **Pytest**: Testing framework with async support
-- **HTTPX**: Modern HTTP client for Python
-- **Docker**: Containerization
+- **`monolith/`** - Main FastAPI application with walking skeleton implementation
+- **`system-test/`** - End-to-end and system tests for acceptance testing
+- **`.github/`** - CI/CD workflows for commit, acceptance, QA, and production stages
 
-## Project Structure
+## Quick Start
 
-```
-monolith/
-├── src/
-│   ├── main/
-│   │   ├── python/
-│   │   │   └── com/optivem/atddaccelerator/template/monolith/
-│   │   │       ├── models/          # Data models (Pydantic)
-│   │   │       ├── controllers/     # Request handlers
-│   │   │       │   ├── api/         # API endpoints
-│   │   │       │   └── web/         # Web page controllers
-│   │   │       ├── config.py        # Application configuration
-│   │   │       └── monolith_application.py  # Main FastAPI app
-│   │   └── resources/
-│   │       └── static/              # Static HTML files
-│   └── test/
-│       └── python/                  # Unit tests
-├── requirements.txt                 # Python dependencies
-├── pyproject.toml                  # Project configuration
-└── Dockerfile                     # Container definition
-
-system-test/
-└── src/test/python/                # System and E2E tests
+```bash
+# Run the application
+cd monolith
+python -m uvicorn src.main:app --reload --port 8080
+
+# Run tests  
+cd system-test
+pytest . -m smoke
 ```
 
-## Getting Started
-
-### Prerequisites
-
-- Python 3.11 or higher
-- pip (Python package manager)
-
-### Installation
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/optivem/atdd-accelerator-template-python.git
-   cd atdd-accelerator-template-python
-   ```
-
-2. **Set up virtual environment**
-   ```bash
-   cd monolith
-   python -m venv venv
-   
-   # On Windows
-   venv\Scripts\activate
-   
-   # On macOS/Linux
-   source venv/bin/activate
-   ```
-
-3. **Install dependencies**
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-4. **Run the application**
-   ```bash
-   python -m uvicorn com.optivem.atddaccelerator.template.monolith.monolith_application:app --host 0.0.0.0 --port 8080 --reload
-   ```
-
-5. **Access the application**
-   - Web UI: http://localhost:8080
-   - API Documentation: http://localhost:8080/docs
-   - Todo Manager: http://localhost:8080/todos
-
-### Running with Docker
-
-1. **Build the Docker image**
-   ```bash
-   cd monolith
-   docker build -t atdd-accelerator-template-python .
-   ```
-
-2. **Run the container**
-   ```bash
-   docker run -p 8080:8080 atdd-accelerator-template-python
-   ```
-
-### Running Tests
-
-1. **Unit tests**
-   ```bash
-   cd monolith
-   pytest src/test/python/
-   ```
-
-2. **System tests** (requires running application)
-   ```bash
-   cd system-test
-   pip install -r requirements.txt
-   pytest src/test/python/
-   ```
-
-## API Endpoints
-
-- `GET /api/echo` - Simple echo endpoint
-- `GET /api/todos/{id}` - Fetch todo by ID from external API
-- `GET /` - Home page
-- `GET /todos` - Todo manager page
-
-## Configuration
-
-The application can be configured using environment variables:
-
-- `TODOS_API_HOST`: External todos API host (default: https://jsonplaceholder.typicode.com)
-- `PORT`: Server port (default: 8080)
-- `HOST`: Server host (default: 0.0.0.0)
+See individual component READMEs for detailed setup instructions:
+- [`monolith/README.md`](monolith/README.md) - Application setup and development
+- [`system-test/README.md`](system-test/README.md) - Testing setup and execution
 
 ## Migration from Java
 

monolith/README.md

@@ -1,6 +1,15 @@
-# Monolith Application (Python)
+# Monolith Application
 
-This is the main Python FastAPI application for the ATDD Accelerator Template.
+This is a walking skeleton FastAPI application that serves as the foundation for ATDD development.
+
+## Technology Stack
+
+- **Python 3.11+**: Modern Python with type hints
+- **FastAPI**: Modern, fast web framework for building APIs
+- **Uvicorn**: ASGI server implementation
+- **Pydantic**: Data validation using Python type annotations
+- **Pytest**: Testing framework with async support
+- **Docker**: Containerization
 
 ## Quick Start
 
@@ -22,59 +31,50 @@ This is the main Python FastAPI application for the ATDD Accelerator Template.
 
 3. **Run the application:**
    ```bash
-   python -m uvicorn com.optivem.atddaccelerator.template.monolith.monolith_application:app --host 0.0.0.0 --port 8080 --reload
-   ```
-
-   Or use the provided scripts:
-   ```bash
-   # Windows
-   start.bat
-   
-   # Linux/macOS
-   ./start.sh
+   python -m uvicorn src.main:app --host 0.0.0.0 --port 8080 --reload
    ```
 
 4. **Access the application:**
    - Home: http://localhost:8080
+   - Health Check: http://localhost:8080/health
    - API Docs: http://localhost:8080/docs
    - Todo Manager: http://localhost:8080/todos
 
 ## Project Structure
 
 ```
 src/
-├── main/
-│   ├── python/              # Python source code
-│   │   └── com/optivem/atddaccelerator/template/monolith/
-│   │       ├── models/      # Data models
-│   │       ├── controllers/ # API and web controllers
-│   │       ├── config.py    # Configuration
-│   │       └── monolith_application.py  # Main app
-│   └── resources/
-│       └── static/          # Static HTML/CSS/JS files
-└── test/
-    └── python/              # Unit tests
+├── main.py              # Main FastAPI application
+└── static/              # Static HTML files
+tests/
+├── test_main.py         # Unit tests
+└── test_basic.py        # Basic smoke tests
+requirements.txt         # Python dependencies
+pyproject.toml          # Project configuration
+Dockerfile              # Container definition
 ```
 
 ## API Endpoints
 
-- `GET /api/echo` - Echo endpoint
+- `GET /health` - Health check endpoint
+- `GET /` - Home page (HTML)
+- `GET /todos` - Todo manager page (HTML)
+- `GET /api/echo` - Simple echo endpoint
 - `GET /api/todos/{id}` - Get todo by ID
-- `GET /` - Home page
-- `GET /todos` - Todo manager page
-
-## Environment Variables
-
-- `TODOS_API_HOST` - External API host (default: https://jsonplaceholder.typicode.com)
-- `HOST` - Server host (default: 0.0.0.0)
-- `PORT` - Server port (default: 8080)
-- `DEBUG` - Debug mode (default: false)
+- `GET /api/todos` - Get all todos
 
 ## Development
 
 ### Running Tests
 ```bash
-pytest src/test/python/
+# All tests
+pytest
+
+# Smoke tests only
+pytest -m smoke
+
+# With verbose output
+pytest -v
 ```
 
 ### Building Docker Image
@@ -86,3 +86,14 @@ docker build -t atdd-accelerator-template-python .
 ```bash
 docker run -p 8080:8080 atdd-accelerator-template-python
 ```
+
+## ATDD Development
+
+This is a walking skeleton designed for ATDD development. To add features:
+
+1. Write a failing acceptance test
+2. Write minimal code to make it pass
+3. Refactor if needed
+4. Repeat
+
+Follow the TODO comments in `src/main.py` to add your features using the ATDD approach.

system-test/README.md

@@ -1,62 +1,90 @@
-# System Test (Python)
+# System Tests
 
-This directory contains system tests for the Python application using pytest.
+End-to-end and system tests for the ATDD Accelerator Template application.
 
-## Instructions
+## Overview
 
-1. **Navigate to the system-test directory:**
-   ```bash
-   cd system-test
-   ```
+This directory contains system tests that verify the application works correctly when deployed. The tests are designed to run against a live instance of the application.
+
+## Test Types
+
+- **Smoke Tests** (`@pytest.mark.smoke`) - Basic functionality verification
+- **E2E Tests** (`@pytest.mark.e2e`) - End-to-end user scenarios
+
+## Test Files
+
+- `test_api_smoke.py` - API smoke tests
+- `test_api_e2e.py` - API end-to-end tests  
+- `test_ui_smoke.py` - UI smoke tests
+- `test_ui_e2e.py` - UI end-to-end tests
+
+## Prerequisites
+
+- Python 3.11 or higher
+- Running application instance (http://localhost:8080)
 
-2. **Install test dependencies:**
+## Setup
+
+1. **Install dependencies:**
    ```bash
    pip install -r requirements.txt
    ```
 
-3. **Start Docker Containers:**
+2. **Start the application with Docker:**
    ```bash
    docker compose up -d
    ```
 
-4. **Run All Tests:**
-   ```bash
-   pytest src/test/python/
-   ```
+## Running Tests
 
-5. **Run Smoke Tests Only:**
-   ```bash
-   pytest src/test/python/ -m smoke
-   ```
-
-6. **Run E2E Tests Only:**
-   ```bash
-   pytest src/test/python/ -m e2e
-   ```
+### All Tests
+```bash
+pytest .
+```
 
-7. **Run with verbose output:**
-   ```bash
-   pytest src/test/python/ -v
-   ```
+### Smoke Tests Only
+```bash
+pytest . -m smoke
+```
 
-8. **Stop Docker Containers:**
-   ```bash
-   docker compose down
-   ```
+### E2E Tests Only
+```bash
+pytest . -m e2e
+```
 
-## Test Structure
+### Verbose Output
+```bash
+pytest . -v
+```
 
+### Specific Test File
+```bash
+pytest test_api_smoke.py
 ```
-src/test/python/
-├── test_api_e2e.py      # API end-to-end tests
-├── test_api_smoke.py    # API smoke tests
-├── test_ui_e2e.py       # UI end-to-end tests
-└── test_ui_smoke.py     # UI smoke tests
+
+## Cleanup
+
+```bash
+docker compose down
 ```
 
+## Expected Endpoints
+
+The tests expect the following endpoints to be available:
+
+### API Endpoints
+- `GET /health` - Health check
+- `GET /api/echo` - Echo endpoint
+- `GET /api/todos/{id}` - Get todo by ID
+- `GET /api/todos` - Get all todos
+
+### UI Endpoints  
+- `GET /` - Home page
+- `GET /todos` - Todo manager page
+
 ## Requirements
 
-- Python 3.9+
+- Python 3.11+
 - pytest
 - httpx
 - Docker (for running the application container)