docs/configuration.md

@@ -0,0 +1,70 @@
+# Configuration and Logging
+
+This application uses a flexible configuration system that supports YAML files and environment variable overrides. It also features a structured logging setup.
+
+## Configuration
+
+The configuration is loaded from a YAML file. By default, the application looks for `config/config.yaml`. You can specify a different configuration file using the `-config` CLI flag.
+
+```bash
+./app -config /path/to/my-config.yaml
+```
+
+### Configuration Structure
+
+The configuration file supports the following structure:
+
+```yaml
+# Logging configuration
+logging:
+  # Log Level: debug, info, warn, error
+  level: "info"
+
+# Server configuration
+server:
+  host: "localhost"
+  port: 8080
+```
+
+### Environment Variables
+
+All configuration values can be overridden using environment variables. The application uses the `APP_` prefix for all environment variables. The variable name is constructed by capitalizing the path to the configuration value and replacing dots/nesting with underscores.
+
+| YAML Path | Environment Variable | Description |
+| :--- | :--- | :--- |
+| `logging.level` | `APP_LOGGING_LEVEL` | Sets the logging level (debug, info, warn, error) |
+| `server.host` | `APP_SERVER_HOST` | Sets the server host address |
+| `server.port` | `APP_SERVER_PORT` | Sets the server listening port |
+
+**Example:**
+
+To start the application with `debug` logging and listening on port `9090`:
+
+```bash
+APP_LOGGING_LEVEL=debug APP_SERVER_PORT=9090 ./app
+```
+
+## Logging
+
+The application uses structured logging (JSON format) via the standard library's `log/slog` package.
+
+### Log Levels
+
+The supported log levels are:
+
+*   `debug`: Detailed information for debugging purposes.
+*   `info`: General operational events (startup, shutdown, etc.).
+*   `warn`: Non-critical errors or potential issues.
+*   `error`: Critical errors that require attention.
+
+The log level is configured via the `logging.level` setting in the configuration file or the `APP_LOGGING_LEVEL` environment variable.
+
+### Log Output
+
+Logs are output to `stdout` in JSON format to facilitate parsing by log management systems.
+
+**Example Log Entry:**
+
+```json
+{"time":"2023-10-27T10:00:00.123Z","level":"INFO","msg":"Starting application..."}
+```