# 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)