Haze API

Admin scheduling & reminder backend API — built with zero framework dependencies. Pure Go stdlib net/http + pgx only.

🚀 Live:alpardfm.my.id/api/haze 📖 Swagger:alpardfm.my.id/api/haze/swagger

---

Highlights

• Zero framework — pure net/http + pgx/v5, no Gin/Echo/Chi
• Background workers — reminder scheduler + auto status updater
• Overlap validation — prevents double-booking with time range checks
• Computed status — scheduled → on_going → done based on real time
• Unit tested — service layer, handlers, workers all tested with fake stores
• Production deployed — running on VPS with Docker + CI/CD

---

Architecture

┌─────────────────────────────────────────────────────────┐
│ HTTP Layer │
│ net/http Router → Auth Middleware → Handler │
├─────────────────────────────────────────────────────────┤
│ Module Layer │
│ auth │ appointment │ publicschedule │ health │
│ Each module: handler → service (interface) → store │
├─────────────────────────────────────────────────────────┤
│ Worker Layer │
│ reminder-worker │ status-worker (one-shot commands) │
├─────────────────────────────────────────────────────────┤
│ Platform Layer │
│ database │ config │ shared/response │
├─────────────────────────────────────────────────────────┤
│ PostgreSQL │
└─────────────────────────────────────────────────────────┘

Design decisions:

• Interface-based Store pattern — services depend on interfaces, not implementations
• Dependency injection via struct fields — no DI container, no magic
• Workers as separate binaries — can run independently or in Docker
• Computed status — never stored stale, always derived from start_at/end_at vs now()

---

Tech Stack

Layer	Technology
Language	Go 1.24
HTTP	stdlib net/http (no framework)
Database	PostgreSQL via pgx/v5
Auth	HMAC token (crypto/hmac)
Password	bcrypt (golang.org/x/crypto)
Migrations	Raw SQL files
Container	Docker multi-stage build
CI/CD	GitHub Actions → VPS deploy

Total direct dependencies: 2 (pgx/v5 + golang.org/x/crypto)

---

Project Structure

haze-api/
├── cmd/
│ ├── api/ # HTTP server entrypoint
│ ├── migrate/ # Database migration runner
│ ├── seed-admin/ # Initial admin seeder
│ ├── reminder-worker/ # Reminder notification scheduler
│ └── status-worker/ # Auto status updater (scheduled→on_going→done)
├── internal/
│ ├── appointment/ # Core domain: CRUD + overlap + computed status
│ ├── auth/ # Login, token, middleware, password hashing
│ ├── publicschedule/ # Public schedule checker (no sensitive data)
│ ├── worker/ # Reminder + status worker logic
│ ├── notification/ # Notification log model
│ ├── health/ # Health check handler
│ ├── config/ # Environment-based configuration
│ ├── database/ # PostgreSQL connection + migration runner
│ └── shared/response/ # JSON response helpers
├── migrations/ # SQL migration files
├── docs/ # OpenAPI spec + business rules
├── scripts/ # Deploy scripts
├── Dockerfile # Multi-stage build (all 5 binaries)
└── docker-compose.yml

---

API Endpoints

Auth

Method	Path	Description
POST	/auth/login	Admin login, returns HMAC token

Appointments (Protected)

Method	Path	Description
GET	/appointments	List appointments (filter: date, status)
POST	/appointments	Create appointment (validates overlap)
GET	/appointments/:id	Get appointment detail
PUT	/appointments/:id	Update appointment
PATCH	/appointments/:id/cancel	Cancel appointment (idempotent)

Public

Method	Path	Description
GET	/public/schedules?date=YYYY-MM-DD	Occupied time slots (no sensitive data)

System

Method	Path	Description
GET	/health	Liveness + DB ping

---

Quick Start

Prerequisites

• Go 1.24+
• Docker & Docker Compose

1. Clone & Setup

git clone https://github.com/alpardfm/haze-api.git
cd haze-api
cp .env.example .env

2. Start Database

docker compose up -d postgres

3. Run Migrations

go run ./cmd/migrate

4. Seed Admin

go run ./cmd/seed-admin

5. Run API

go run ./cmd/api

API available at http://localhost:8080. Health check: GET /health.

6. Run Workers (optional)

go run ./cmd/reminder-worker # Run once: process due reminders
go run ./cmd/status-worker # Run once: update stale statuses

---

Testing

go test ./...

Tests use fake store implementations (no database required). Covered:

• Appointment service: create, update, cancel (idempotent), list with computed status, overlap rejection
• Auth handler & middleware
• Public schedule service & handler
• Worker: reminder slot calculation, anti-double-send
• Shared response helpers

---

Business Rules

• Fixed duration: 120 minutes per appointment (v1)
• Overlap prevention: Create/update rejected if time range conflicts
• Computed status:scheduled → on_going → done based on current time vs start_at/end_at
• Cancel is idempotent: Cancelling an already-cancelled appointment returns success
• Reminder: Configurable per appointment (reminder_start_at + interval_hours), anti-double-send via notification logs
• Public checker: Only exposes occupied time slots, never client names or notes

---

Deployment

Production runs at alpardfm.my.id/api/haze via:

1. Push/merge to master → GitHub Actions runs tests
2. Code synced to VPS via rsync
3. Docker containers rebuilt + restarted
4. Migrations + admin seed run automatically

---

Related

• haze-ui — React + TypeScript frontend for this API

---

License

MIT License. See LICENSE for details.