Minesweeper Field Processor — Documentation

This repository provides the official documentation for the Minesweeper Field Processor kata, generated using Sphinx.

The documentation is designed to ensure clarity, traceability, and reproducibility across all stages of development — from requirements definition through implementation and validation.

📚 Scope of Documentation

The documentation reflects both the system architecture and the development process, including:

  • System Overview — project context and usage guidelines

  • Architecture (arc42) — complete system design, constraints, and runtime behavior

  • User Stories — formally defined requirements with traceable scenarios

All user stories follow a layered implementation strategy:

INFRA → Backend → Frontend → End-to-End (E2E)

🗂️ Documentation Structure

Section

Purpose

Overview

Introduction and high-level system description

Architecture

arc42-based system design (structure, behavior, deployment)

User Stories

Requirements specification and scenario definitions

⚙️ Local Setup

Prerequisites

  • Python ≥ 3.10

Install Dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r docs/requirements.txt

Build Documentation

cd docs
make html

Preview Documentation

Open the generated site:

docs/_build/html/index.html

Or serve it locally:

python -m http.server -d docs/_build/html 8000

Then navigate to:

http://localhost:8000

🐳 Execution Environment

The application is fully containerized to ensure a consistent and reproducible runtime environment.

Build and Run

docker build -t kata-tests .
docker run --rm -i kata-tests ./minesweeper <<EOF
4 4
*...
....
.*..
....
0 0
EOF

This enables execution with input provided via standard input.

This approach guarantees:

  • Environment isolation

  • Platform-independent execution

  • Validation of infrastructure-level requirements

🧪 Testing Strategy

Testing is performed within the containerized environment:

docker build -t kata-tests .
docker run --rm kata-tests

Note: Adjust the execution command if a specific test runner (e.g., ctest) is configured.

🚀 Continuous Deployment

The documentation site is automatically built and deployed using GitHub Actions.

Setup

mkdir -p .github/workflows
mv docs/docs-deploy.yml .github/workflows/docs-deploy.yml

Then:

  • Navigate to Settings → Pages

  • Set Source to GitHub Actions

Published Site

After pushing to the main branch, the documentation will be available at:

https://anazec.github.io/sdp-powered-by-ai-agents-ana-zec/

🧠 Development Methodology

This project follows a structured Test-Driven Development (TDD) and Behavior-Driven Development (BDD) approach:

  • Requirements are defined using GIVEN–WHEN–THEN scenarios

  • Implementation progresses through layered validation:

    • Infrastructure

    • Backend

    • Frontend

    • End-to-End behavior

  • Code evolution follows the RED → GREEN → REFACTOR cycle

This methodology ensures:

  • Clear separation of concerns

  • High test coverage

  • Strong alignment between requirements and implementation

👩‍💻 Author

Ana Zec M.Sc. Student, Automotive Software