Add ADR records (#83)

* Document some architectural decisions for the project.

Author: omerida

docs/decisions/01-follow-psr-11.md

@@ -0,0 +1,24 @@
+---
+status: accepted
+date: 14-JAN-2026
+---
+
+# Follow PSR-11 for Dependency Injection Containers
+
+## Context and Problem Statement
+
+The spacetraders application should use a dependency injection container (DIC) to promote object composition and discourage direct instantiation of service classes.
+
+## Considered Options
+
+* [Adopting PSR-11](https://www.php-fig.org/psr/psr-11/)
+* Rolling a custom container
+
+## Decision Outcome
+
+Any DIC we use must follow PSR-11 to allow us to change to a new or better implementation in the future.
+
+### Consequences
+
+* May limit the packages we can use as a DIC
+* We are not locked into using any single solution.

docs/decisions/02-dependency-injection.md

@@ -0,0 +1,32 @@
+---
+status: accepted
+date: 14-JAN-2026
+---
+
+# Use PHP-DI for service container
+
+## Context and Problem Statement
+
+PHP classes should support dependency injection for composing objects instead of direct instantiation. We need to provide an easy-to-use Dependency Injection container for developers that follows PSR-11 container interface.
+
+## Considered Options
+
+* php-di/php-di
+  * PRO: autowiring based on typehints, can register with callbacks. Have previous experience using it.
+  * CON: many open issues
+* league/container
+  * PRO: actively maintained
+  * CON: service registration is verbose
+* symfony/dependency-injection
+  * PRO: backed by symfony development
+  * CON: service registration is verbose
+
+## Decision Outcome
+
+Use PHP-DI due to familiarity with it and its syntax.
+
+### Consequences
+
+* Will implement a service container that uses PHP-DI
+* May need to look into container compilation as application grows.
+

docs/decisions/03-follow-psr4-autoloading.md

@@ -0,0 +1,36 @@
+---
+status: accepted
+date: 01-Jan-2026
+---
+
+
+# Use PSR-4 for Autoloading custom classes
+
+## Context and Problem Statement
+
+Project needs to follow some autoloading mechanism for PHP classes.
+
+## Considered Options
+
+* Adopt [PSR-4](https://www.php-fig.org/psr/psr-4/)
+  * PRO: supported by Composer and known wider PHP community
+* Write a custom autoloader
+  * CON: another thing to maintain
+
+## Decision Outcome
+
+Custom classes must follow PSR-4 conventions for naming files and namespaces.
+
+### Consequences
+
+We will need to register namespaces in `composer.json`. For example:
+
+```json
+  "autoload": {
+    "psr-4": {
+      "Phparch\\SpaceTradersCLI\\": "cli/",
+      "Phparch\\SpaceTraders\\": "src/"
+    }
+  },
+```
+

docs/decisions/04-adopt-coding-standard.md

@@ -0,0 +1,32 @@
+---
+status: accepted
+date: 01-JAN-2026
+---
+
+# Adopts PER-3 as project coding style
+
+## Context and Problem Statement
+
+Spacetraders application code needs to follow a consistent coding style guide that can be enforced with an automatic linter and supported by most IDEs.
+
+## Considered Options
+
+Both of these candidates report violations and can try to fix them.
+
+* [PSR-12](https://www.php-fig.org/psr/psr-12/)
+* * PRO: existing coding standard we can adopt
+  * CON: superceded by PER-3
+* [PER-3](https://www.php-fig.org/per/coding-style/)
+  * PRO: evolving standard, adopted in wider PHP community
+* Symfony, Drupal, WordPress or other coding standard
+  * PRO: existing coding standard we can adopt
+  * CON: We are not any of those projects and they each have their own quirks.
+
+## Decision Outcome
+
+Use PER-3 as the project's coding style and enforce it automatically.
+
+### Consequences
+
+Need to identify tooling for linting and automated checks.
+

docs/decisions/05-use-php-codesniffer.md

@@ -0,0 +1,30 @@
+---
+status: accepted
+date: 01-JAN-2026
+---
+
+# Use PHPCodeSniffer to enforce PER-3
+
+## Context and Problem Statement
+
+We have adopted [PER-3](https://www.php-fig.org/per/coding-style/) as our coding style and need automated tools to check, fix, and enforce adherence.
+
+## Considered Options
+
+* [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)
+  * PRO: Familiar with configuring it
+  * CON: XML for rules configuration
+* [PHP CS Fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer)
+  * PRO: Part of symfony
+
+
+## Decision Outcome
+
+Use PHP_Codesniffer since we are familiar with configuring it.
+
+### Consequences
+
+* Add to dev packages in `composer.json`
+* Document how to run its linter and fixer at the command line
+* Report violations when someone tries to push code.
+* Check for violations in CI.

docs/decisions/_adr-template.md

@@ -0,0 +1,25 @@
+---
+status: proposed | rejected | accepted | deprecated | … | superseded by ADR-0123
+date: DD-MMM-YYYY
+decision-makers: 
+consulted: 
+informed: 
+---
+
+
+# <!-- short title, representative of solved problem and found solution -->
+
+## Context and Problem Statement
+
+
+
+## Considered Options
+
+
+
+## Decision Outcome
+
+
+
+### Consequences
+