Add Home

Home.md

@@ -0,0 +1,112 @@
+# 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
+
+```bash
+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 |
+
+```bash
+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
+
+```bash
+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](../blob/main/.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)