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

## Production roadmap

Phases 1–3 above were the initial build and shipped a feature-complete demo.
What follows is the trajectory from demo to a product that can be sold.
Future sessions: read this section before starting new feature work so you know
which tier you're contributing to.

Detailed sequencing lives in:
- `docs/TIER1_PLAN.md` — the 8 blocks of launch-blocker work
- `docs/TIER2_PLAN.md` — the 8 blocks of post-launch work (Tier 2)

### Tier 1 — Launch blockers

Cannot ship to paying customers without these.

| Feature | What "done" means |
|---|---|
| **Real authentication** | Email + password (bcrypt) or magic links, email verification, password reset, JWT-based sessions with refresh tokens. The `useHost()` localStorage bootstrap must be removed. |
| **Authorisation / multi-tenancy** | Every host-facing endpoint behind session middleware. Row-level authz: a host only sees their own events, guests, tokens. No more `?host_id=...` query params. |
| **Real notifications** | Twilio SMS and AWS SES email actually wired, branded HTML templates, retry/backoff, bounce + complaint webhook handling, unsubscribe links. |
| **CSV guest import** | Drag-drop upload, server-side validation, dedup by email, preview/confirm step. The marketing page already promises this. |
| **Billing** | Stripe integration, free tier limits enforced in code, paid tiers, webhook handling for payment events, customer portal. |
| **Rate limiting + abuse controls** | Redis-backed sliding-window limits on the bootstrap, RSVP-submit, token-issue, and event-create endpoints. CAPTCHA on user-creation flow. |
| **Backups + disaster recovery** | Daily automated Postgres backups, point-in-time recovery via WAL archiving, documented + tested restore drill. (Claude builds restore docs; infra is human-owned.) |
| **Privacy compliance** | Data export endpoint, right-to-erasure endpoint, privacy policy + ToS pages, retention policy, signed DPAs with subprocessors (Twilio/SES/Stripe). |

### Tier 2 — Customer expectations (first 3 months post-launch)

Features hosts will ask for almost immediately.

| Feature | Notes |
|---|---|
| **Smarter fraud detection** | Current heuristic scorer has false positives (same guest scoring `0` then `61` on consecutive opens). Add geolocation (MaxMind), per-event tunable thresholds, "actually legit" feedback loop, allowlists, eventual ML model. |
| **Reminders + broadcasts** | Auto-reminders 7-day / 1-day / day-of, "last call" to non-responders, custom announcements when details change. Killer feature for wedding planners. |
| **Editable RSVPs** | Guests can change "attending" → "declined" via the same link. |
| **Multi-host / collaborators** | Owner / Editor / Viewer roles per event, invitation flow. |
| **Event branding** | Custom colours, logo upload, optional custom domain for RSVP pages. |
| **Day-of check-in** | QR codes on confirmations, PWA scanner, live arrival count, walk-in handling, plus-one verification. |
| **Calendar integration** | "Add to Google / Outlook / Apple" on confirmation page. |
| **Host analytics** | Response-rate over time, who hasn't opened, source attribution. |

### Tier 3 — Operations & polish

Required for running this at scale, not for first launch.

| Area | Notes |
|---|---|
| **Observability** | Prometheus `/metrics`, OpenTelemetry tracing across API↔fraud-engine↔NATS, Sentry, uptime monitoring, alert routing. |
| **CI/CD** | Gitea/GitHub Actions: tests on PR, lint, security scans (gosec, trivy), staging auto-deploy, blue/green prod, automated rollback. |
| **Accessibility** | WCAG 2.1 AA audit + fixes. Particular attention to focus states, contrast, reduced-motion respect for the float animations. |
| **i18n** | Vue i18n, translated email/SMS templates, date/time/currency localisation, RTL support. |
| **Mobile** | PWA + push notifications first, native apps later. |
| **Secrets management** | Vault or AWS Secrets Manager, rotation, no secrets in images. |
| **Performance** | Actually use Redis (cache hot queries), read replicas, CDN, query-plan audits, load tests. |

### Tier 4 — Moat & enterprise

Differentiators that justify enterprise pricing.

| Feature | Notes |
|---|---|
| **SSO (SAML, OIDC)** | For corporate hosts. |
| **White-label** | For event planners running GuestGuard for *their* clients. |
| **Public API + webhooks** | So customers can build on top. |
| **Zapier integration** | Non-negotiable for SMB segment. |
| **CRM sync** | Salesforce, HubSpot — for corporate events teams. |
| **AI setup assistant** | Paste an invitation email, get an event auto-created with guest list extracted. |
| **Marketplace integrations** | Caterers, photographers, venues. |
| **Biometric / face check-in** | High-end events only, opt-in. |
| **SLAs + regional data residency** | EU-only deployment option, signed SLA contracts. |