✅🧱 add tests & ci changes

2026-02-23 22:52:54 +01:00
parent dbbe991a3d
commit 59ddc66a8e
10 changed files with 309 additions and 72 deletions
--- a/Readme.md
+++ b/Readme.md
@@ -0,0 +1,119 @@
+# Handheld Devices
+
+A microservices stack for managing handheld gaming device catalog data: Lua API and worker, Deno/Alpine.js frontend, PostgreSQL, and Redis.
+
+## Architecture
+
+| Service  | Tech             | Port | Description                      |
+| -------- | ---------------- | ---- | -------------------------------- |
+| API      | Lua 5.4          | 8080 | REST API for devices CRUD        |
+| Worker   | Lua 5.4          | -    | Consumes events from Redis queue |
+| Frontend | Deno + Alpine.js | 8090 | Web UI backed by Oak             |
+| Postgres | 15-alpine        | 5432 | Primary data store               |
+| Redis    | 7-alpine         | 6379 | Event queue and caching          |
+
+## Quick Start
+
+### Prerequisites
+
+- Docker and Docker Compose
+- Lua 5.4 + LuaRocks (for local dev/testing)
+- Deno 2.x (for local frontend dev)
+
+### Run with Docker Compose
+
+```bash
+cp .env.example .env
+# Edit .env if needed (e.g. DB_PASSWORD)
+
+make install-deps  # optional: LuaRocks + Deno deps for local dev
+make dev
+```
+
+- API: http://localhost:8080
+- Frontend: http://localhost:8090
+- Health: http://localhost:8080/health/ready
+
+### Stop
+
+```bash
+make down
+```
+
+## Development
+
+Install all dependencies for local development (LuaRocks packages and Deno cache):
+
+```bash
+make install-deps
+```
+
+### API (devices-api)
+
+```bash
+cd devices-api
+make deps    # luarocks install
+make test    # unit tests (busted)
+make lint    # luacheck
+make run     # run locally (needs Postgres + Redis)
+```
+
+### Worker (devices-worker)
+
+```bash
+cd devices-worker
+make deps
+make lint
+make run     # needs Postgres + Redis
+```
+
+### Frontend
+
+```bash
+cd frontend
+make run     # or: deno task start (with watch)
+make lint    # deno check
+```
+
+## Makefile Reference
+
+From project root:
+
+| Target                | Description                               |
+| --------------------- | ----------------------------------------- |
+| `make install-deps`   | Install LuaRocks + Deno deps for local dev |
+| `make dev`            | Start all services                        |
+| `make down`           | Stop all services                         |
+| `make build`          | Build Docker images                       |
+| `make test`           | Run API unit tests                        |
+| `make lint`           | Luacheck + Deno check                     |
+| `make logs`           | Follow API logs                            |
+| `make logs-worker`    | Follow worker logs                         |
+| `make init-db`        | Run DB migrations manually                 |
+| `make shell-postgres` | psql in Postgres container                 |
+| `make status`         | Container status                           |
+
+## API Endpoints
+
+| Method | Path          | Description              |
+| ------ | ------------- | ------------------------ |
+| GET    | /devices      | List devices (paginated) |
+| POST   | /devices      | Create device            |
+| GET    | /devices/:id  | Get device               |
+| PUT    | /devices/:id  | Update device            |
+| DELETE | /devices/:id  | Delete device            |
+| GET    | /health/ready | Readiness (DB + Redis)   |
+| GET    | /health/live  | Liveness                 |
+
+## Deployment
+
+- **Kubernetes**: `helm lint k8s/handheld-devices`
+- **CI**: See `.github/workflows/ci.yml` (lint, build, unit tests, helm lint)
+
+## Environment
+
+See `.env.example` for configuration. Key variables:
+
+- `DB_*` – PostgreSQL connection
+- `REDIS_*` – Redis connection
+- `API_URL` – API URL used by the frontend (for browser requests)