Initial commit

- REST API for calculating age breakdowns (years, months, weeks, days, hours, minutes, seconds)
- Birthtime configured as Unix timestamps
- Sleeps until next birthday countdown
- Per-person lookup via GET /age/{name}
- Docker and Makefile build support
- Woodpecker CI pipelines

README.md

@@ -1,3 +1,59 @@
 # age-api
 
-Simple API for showing a users age
+A simple REST API that calculates age breakdowns for configured people.
+
+## Endpoints
+
+### `GET /age`
+
+Returns age breakdowns for all configured people.
+
+### `GET /age/{name}`
+
+Returns the age breakdown for a single person by name (case-insensitive).
+
+### Response Format
+
+```json
+{
+  "name": "alice",
+  "dob": "1990-05-15",
+  "birthtime": 642988800,
+  "age": {
+    "years": 36,
+    "months": 433,
+    "weeks": 1889,
+    "days": 13222,
+    "hours": 317328,
+    "minutes": 19039680,
+    "seconds": 1142380800
+  }
+}
+```
+
+## Configuration
+
+People are defined in `config.yaml` with `birthtime` as a Unix timestamp:
+
+```yaml
+people:
+  - name: alice
+    birthtime: 642729600
+  - name: bob
+    birthtime: 501465600
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `CONFIG_PATH` | `config.yaml` | Path to the configuration file |
+| `LISTEN_ADDR` | `:8080` | Address and port to listen on |
+
+## Build
+
+```sh
+make build    # build binary to bin/age-api
+make test     # run tests
+make docker   # build docker image
+```