Handheld Devices

A microservices stack for managing handheld gaming device catalog data. Built with Lua (API + 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 + Oak	8090	Web UI
PostgreSQL	15-alpine	5432	Primary data store
Redis	7-alpine	6379	Event queue and caching

The API publishes domain events to Redis on create/update/delete. The worker consumes from the queue and can fan out to external systems. The frontend serves static assets and proxies API requests with CORS and CSP.

Quick Start

cp .env.example .env
# Edit .env (e.g. DB_PASSWORD)

make install-deps   # optional: for local dev
make dev

URL	Service
http://localhost:8080	API
http://localhost:8090	Frontend
http://localhost:8080/health/ready	Readiness probe

make down    # stop all services

Development

Prerequisites

Docker + Docker Compose - for running the stack
Lua 5.4 + LuaRocks - for API/worker local dev and tests
Deno 2.x - for frontend local dev

Install Dependencies

make install-deps   # LuaRocks packages + Deno cache

Per-Service Commands

Service	Directory	Commands
API	`devices-api/`	`make deps`, `make test`, `make lint`, `make run`
Worker	`devices-worker/`	`make deps`, `make lint`, `make run`
Frontend	`frontend/`	`make run`, `make lint`

API Reference

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

Makefile Targets (from root)

Target	Description
`make install-deps`	Install all local dev deps
`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

Deployment

Kubernetes: Helm chart in k8s/handheld-devices/
CI: See .github/workflows/ci.yml — lint, build, unit tests, helm lint

Configuration

Copy .env.example to .env. Key variables:

DB_* - PostgreSQL connection
REDIS_* - Redis connection
API_URL - API URL used by the frontend (for browser requests)