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.