Mars Rover
Mars Rover Kata¶
A Python implementation of the classic Mars Rover kata, built as part of the Software Development Processes Powered by AI Agents course. The kata demonstrates clean architecture, domain-driven design, and test-driven development — with every feature driven by AI agents for git workflow, architecture, requirements, CI/CD, and TDD/BDD.
What the Kata Solves¶
A rover is deployed onto a rectangular plateau on Mars. An operator sends it a sequence of commands — turn left (L), turn right (R), or move forward (M). The system must:
Accept a plateau size and one or more rovers with initial positions and headings
Process each rover’s command string sequentially
Report the final position and heading of every rover
Prevent any rover from leaving the plateau boundaries
Detect obstacles and stop safely before collision
Tech Stack & Architecture¶
Layer |
Technology |
|---|---|
Language |
Python 3.12 |
CLI |
|
Testing |
pytest + coverage |
Linting |
Black, isort, Ruff, Bandit |
Docs |
Sphinx + MyST + Wagtail theme → GitHub Pages |
CI/CD |
GitHub Actions |
Containerisation |
Docker (multi-stage) |
The codebase follows a Ports & Adapters (Hexagonal) architecture with three layers:
mars_rover/
├── domain/ # Pure business logic — Rover, Plateau, Heading, Commands
├── application/ # Use-case orchestration — MissionController
└── adapters/ # I/O translation — InputParser, OutputFormatter
The domain layer has zero I/O dependencies and is fully unit-testable in isolation.
Build & Run Locally¶
Run the application:
# Build the runtime image
docker build --target runtime -t mars-rover .
# Run with piped input
echo -e "5 5\n1 2 N\nLMLMLMLMM\n3 3 E\nMMRMMRMRRM" | docker run --rm -i mars-rover
Expected output:
1 3 N
5 1 E
Run Tests¶
# Build the test image and run the full suite (lint + tests + coverage)
docker build --target test -t mars-rover-test .
docker run --rm mars-rover-test
The test stage runs pytest with --cov-fail-under=90. The lint stage (Black, isort, Ruff, Bandit) runs as a separate build target:
docker build --target lint -t mars-rover-lint .
Documentation¶
Live Sphinx documentation is published to GitHub Pages on every push to main:
https://dikanovicmihailo.github.io/sdp-powered-by-ai-agents-mihailo-dikanovic/
Docs source lives in docs/ and covers architecture (arc42), user stories, and the glossary.
Project Structure¶
.
├── mars_rover/
│ ├── domain/ # Rover, Plateau, Heading, Commands
│ ├── application/ # MissionController
│ ├── adapters/ # InputParser, OutputFormatter
│ └── __main__.py # CLI entry point
├── tests/
│ ├── domain/ # Unit tests for domain logic
│ ├── application/ # Unit tests for use cases
│ ├── adapters/ # Unit tests for I/O adapters
│ └── test_cli_*.py # End-to-end CLI tests
├── docs/
│ ├── architecture/ # arc42 documentation (12 sections)
│ └── user-stories/ # BDD user stories per feature
├── .github/workflows/ # CI pipeline + Sphinx deploy
├── Dockerfile # Multi-stage: base → deps → lint → test → runtime
└── pyproject.toml # Project metadata and tool config