120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
# 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)
|