guestguard/CLAUDE.md

# CLAUDE.md — GuestGuard

> This file configures Claude Code's behaviour for this project.

## What this project is

GuestGuard is a secure event RSVP platform with real-time fraud detection. Guests receive unique, cryptographically signed invitation links. When someone accesses a link, the system collects device fingerprints and IP geolocation, scores the access for fraud risk, and blocks unauthorised users.

The architecture has three components, each with a genuine reason to be separate:

1. **Core API (Go)** — All synchronous CRUD: events, guests, RSVPs, tokens, auth. Publishes events to NATS. Serves REST + WebSocket.
2. **Fraud Engine (Python/FastAPI)** — Consumes access events from NATS, runs ML risk scoring, publishes fraud scores back. Exposes gRPC for synchronous scoring during RSVP submission.
3. **Notification Worker (Go)** — Consumes events from NATS, sends SMS via Twilio, email via AWS SES, with retry and backoff.

Message broker: NATS JetStream.
Frontend: Nuxt 3 with Tailwind CSS.
Database: PostgreSQL.
Cache: Redis.

## Architecture document

Read `docs/ARCHITECTURE.md` for the full architecture, data flows, database schema, fraud scoring model, and API design. **Always reference this file before building any feature** — it contains the detailed specifications for every component.

## Project context

- **Owner:** alchemistkay (Kwaku Danso)
- **Platform:** k4scloud homelab (k3s) + GitHub mirror
- **Domain:** guestguard.k4scloud.com
- **Registry:** harbor.k4scloud.com/guestguard
- **GitOps:** Gitea Actions → Harbor → ArgoCD
- **Go module:** github.com/alchemistkay/guestguard

## Repository structure

```
guestguard/
├── CLAUDE.md                   # This file
├── docs/
│   └── ARCHITECTURE.md         # Full architecture spec (read this first)
├── cmd/
│   ├── api/main.go             # Core API entrypoint
│   └── notifier/main.go        # Notification worker entrypoint
├── internal/
│   ├── api/                    # HTTP handlers, middleware, WebSocket
│   ├── auth/                   # JWT, OAuth
│   ├── domain/                 # Business logic (events, guests, RSVPs, tokens)
│   ├── fraud/                  # gRPC client for fraud engine
│   ├── nats/                   # NATS publisher/subscriber
│   ├── notification/           # Twilio, SES adapters
│   └── storage/                # PostgreSQL, Redis repositories
├── fraud-engine/
│   ├── app/                    # FastAPI app
│   ├── scoring/                # Risk scoring logic
│   ├── consumers/              # NATS event consumers
│   └── Dockerfile
├── frontend/
│   ├── pages/
│   ├── components/
│   ├── composables/
│   └── Dockerfile
├── docker-compose.yml
├── Makefile
└── README.md
```

## Conventions

### Go services (Core API + Notification Worker)
- Module path: `github.com/alchemistkay/guestguard`
- Use `log/slog` for logging (JSON handler in production)
- Use `net/http` stdlib with Go 1.22+ routing for the Core API
- Health endpoint at `GET /health` on every service
- Config via `os.Getenv` with defaults — no Viper
- Graceful shutdown with signal handling (SIGINT, SIGTERM)
- Table-driven tests
- PostgreSQL via `github.com/jackc/pgx/v5`
- Redis via `github.com/redis/go-redis/v9`
- NATS via `github.com/nats-io/nats.go`
- JWT via `github.com/golang-jwt/jwt/v5`
- gRPC via `google.golang.org/grpc` (client to fraud engine)

### Python service (Fraud Engine)
- Python 3.11+ with FastAPI
- Pydantic v2 for schemas, pydantic-settings for config
- `ruff` for linting and formatting
- `pytest` for testing
- scikit-learn for ML model (start with heuristic scoring, upgrade later)
- NATS via `nats-py`
- gRPC via `grpcio` (server)

### Frontend (Nuxt 3)
- Nuxt 3 with Tailwind CSS
- Dark theme (zinc-950 background)
- Brand colour: green (#22c55e) — conveys safety/security
- All API calls use relative URLs via `useApi()` composable
- WebSocket URLs derived from `window.location`
- No NUXT_ env vars for API URLs in production
- SSR for landing page, client-side for dashboard

### Docker
- Multi-stage builds
- Alpine base for Go, slim base for Python, Alpine for Nuxt (node)
- Non-root user in final image (UID 1000)
- Health check via k8s probes (not HEALTHCHECK in Dockerfile)

### Git
- Branch: main (default), feature/*, release/*, hotfix/*
- Commit messages: conventional commits (feat:, fix:, chore:, docs:, ci:)
- Squash merge feature branches
- Always commit package-lock.json

## What to build vs what NOT to build

### Claude Code builds:
- All Go source code (cmd/, internal/)
- All Python source code (fraud-engine/)
- All frontend code (frontend/)
- Unit tests and integration tests
- docker-compose.yml for local development
- Dockerfiles (multi-stage, following conventions above)
- Database migrations (golang-migrate)
- Protobuf definitions for gRPC (fraud scoring)
- NATS subject definitions and message schemas
- Makefile

### Claude Code does NOT build (human handles):
- Kubernetes manifests (Deployments, Services, etc.)
- Gitea Actions CI/CD pipelines
- ArgoCD Application definitions
- NetworkPolicies
- Sealed Secrets
- Terraform
- Grafana dashboards
- Prometheus alert rules
- Helm charts or Kustomize overlays
- Harbor project configuration

## Quality gates before handoff

Before marking application code as "ready for deployment":

1. `docker-compose up` starts all services (API, fraud engine, notifier, frontend, PostgreSQL, Redis, NATS)
2. Health endpoints return 200 on API (`/health`), fraud engine (`/health`)
3. Unit tests pass: `go test ./...` and `cd fraud-engine && pytest -v`
4. Frontend loads at http://localhost:3000 and can reach backend APIs
5. Core flow works: create event → add guest → generate token → access RSVP link → submit RSVP
6. Fraud flow works: access with different fingerprint → risk score > 60 → SMS verification triggered
7. Notification flow works: RSVP confirmed → confirmation event published to NATS → worker logs delivery attempt
8. No hardcoded localhost URLs in production code paths
9. Structured JSON logging on all services
10. Prometheus metrics endpoint exposed on API (`/metrics`)

## Build order

When building this project, follow this sequence:

### Phase 1: Core API foundation
1. Go project scaffold (cmd/api, internal packages)
2. Config loading from environment
3. PostgreSQL connection + schema (events, guests, tokens, rsvps tables)
4. Event CRUD endpoints (POST/GET/PATCH/DELETE /events)
5. Guest management endpoints (POST/GET /events/:id/guests, CSV import)
6. Token generation (HMAC-SHA256 signed, per-guest unique)
7. RSVP endpoint (validate token → record response)
8. Health endpoint
9. Unit tests for token logic and RSVP validation
10. Dockerfile

### Phase 2: NATS + Fraud Engine
1. NATS JetStream connection in Core API
2. Publish access events on token validation (guest.access.attempted)
3. Fraud Engine scaffold (FastAPI + NATS consumer)
4. Device fingerprint collection (frontend JavaScript)
5. Heuristic risk scoring (weighted features)
6. gRPC service definition (proto file)
7. gRPC server in Fraud Engine
8. gRPC client in Core API (synchronous scoring during RSVP)
9. Publish fraud.scored events back to NATS
10. Core API consumes fraud scores, flags tokens
11. Integration tests (NATS end-to-end)

### Phase 3: Notifications + Frontend
1. Notification Worker scaffold (cmd/notifier)
2. NATS consumers (invitation.send, rsvp.confirmed, fraud.alert)
3. Twilio SMS adapter (with retry logic)
4. Nuxt 3 frontend scaffold
5. Landing page
6. RSVP flow pages (/rsvp/:token)
7. Host dashboard (event list, guest management, RSVP tracking)
8. Real-time monitor page (WebSocket for live RSVPs + fraud alerts)
9. docker-compose.yml for full local development
10. End-to-end testing