Update README.md with comprehensive project documentation

- Replace outdated TLS certificate setup with a detailed overview of the Copenhagen Truck Wash API.
- Add sections on architecture, stack components, local development, configuration, testing, monitoring, and API documentation.
- Include instructions for running tests, logs inspection, and utilizing tools like Traefik, Jaeger, and Portainer.

README.md

@@ -1,35 +1,71 @@
-### Local TLS certificates with Docker Compose
+# Copenhagen Truck Wash API
 
-Nginx is configured to terminate TLS using certificates mounted at `/etc/letsencrypt` inside the container. To use your real Let’s Encrypt certificates on the host, the Compose file mounts a configurable path via `LETSENCRYPT_PATH`.
+Backend API for Copenhagen Truck Wash services.
 
-#### 1) Configure the host certificate path
-Copy `.env.example` to `.env` in the project root and adjust the path for your environment:
+## Architecture & Stack
+- **Edge Proxy:** [Traefik 2.11](https://doc.traefik.io/traefik/) (Handles TLS termination, routing, and rate limiting).
+- **Web Server:** [Caddy 2.7](https://caddyserver.com/) (Serves the PHP application via FastCGI).
+- **PHP Runtime:** PHP 8.2-FPM (Scale out with workers `php1` to `php5`).
+- **Cache/Queue:** Redis 7.
+- **Observability:** Jaeger (Tracing), Prometheus (Metrics).
 
-```
-cp .env.example .env
-# Edit .env and set one of the following:
-# Linux:  LETSENCRYPT_PATH=/etc/letsencrypt
-# Windows (WSL Ubuntu): LETSENCRYPT_PATH=//wsl$/Ubuntu/etc/letsencrypt
+## Getting Started
+
+### Prerequisites
+- Docker Desktop 4.x+
+- PHP 8.2 CLI (optional, for host-side testing)
+
+### Local Development
+To bring up the minimal development stack (Traefik, Redis, Caddy, and one PHP worker):
+```powershell
+docker compose up -d traefik redis php1 caddy
 ```
 
-Ensure the following files exist under the path you set:
-- `live/api.truckwash.dk/fullchain.pem`
-- `live/api.truckwash.dk/privkey.pem`
-- `live/cloud.truckwash.dk/fullchain.pem`
-- `live/cloud.truckwash.dk/privkey.pem`
+The API is accessible at:
+- `http://localhost`
+- `https://localhost` (using Traefik default cert)
+- `http(s)://localhost/api/` (proxied with `/api` prefix stripped)
 
-If you don’t have certs for `cloud.truckwash.dk` locally, either comment out that TLS server block in `services/nginx/nginx.conf` or place a temporary self‑signed cert/key at the expected path.
-
-#### 2) Start Nginx
-```
-docker compose up -d nginx
+To start all services including multiple PHP workers and development tools (Jaeger, Portainer):
+```powershell
+docker compose --profile dev up -d
 ```
 
-Check logs:
-```
-docker compose logs -f nginx
+### Configuration
+Configuration is primarily managed via environment variables.
+- The application root is located at `services/nginx/app`.
+- `services/nginx/app/config.php` loads configuration from the environment (requires `USE_ENV=true`).
+- `php1` performs an automatic `composer install` on startup if `AUTO_COMPOSER_INSTALL=true`.
+
+## Testing
+
+The project uses a lightweight testing approach using procedural PHP scripts.
+
+### Running Tests
+Tests are located in `services/nginx/app/tests/`.
+
+**From the host (requires PHP 8.2):**
+```powershell
+php services/nginx/app/tests/subusers/SelfservePermissionInitTest.php
 ```
 
-#### 3) Troubleshooting
-- “cannot load certificate … no such file or directory”: verify `LETSENCRYPT_PATH` and that all `live/<domain>/` files exist on the host.
-- For purely local testing without HTTPS, you may comment out the HTTPS server blocks and the HTTP→HTTPS redirect in `services/nginx/nginx.conf` and run on port 80.
+**Inside Docker (recommended for integration tests):**
+```powershell
+docker compose exec -T php1 php /var/www/html/tests/subusers/SelfservePermissionInitTest.php
+```
+
+### Creating New Tests
+Place new tests under `services/nginx/app/tests/<domain>/`. Every test should define the `WD` constant to point to the app root:
+```php
+if (!defined('WD')) { define('WD', dirname(__DIR__, 2)); }
+```
+
+## Logs & Monitoring
+- **Logs:** `docker compose logs -f [service_name]` (e.g., `php1`, `caddy`, `traefik`).
+- **Traefik Dashboard:** `http://traefik.localhost` (available in dev).
+- **Jaeger (Tracing):** `http://localhost:16686` (when running with `--profile dev`).
+- **Portainer:** `http://localhost:9000` (when running with `--profile dev`).
+
+## API Documentation
+- **OpenAPI:** The authoritative OpenAPI 3.0 contract is at `openapi.yaml`.
+- **Writerside:** Documentation projects are located in `/Writerside` and `/Writerside2`.