jennie/ghostguild-org
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ghostguild-org/CLAUDE.md
Jennie Robinson Faber 1e30ba23cd
Some checks are pending
Test / vitest (push) Waiting to run
Details
Test / playwright (push) Blocked by required conditions
Details
Test / visual (push) Blocked by required conditions
Details
feat: add testing infrastructure — Vitest, Playwright, CI, git hooks 
Add comprehensive testing covering 420 unit/handler tests across 24 Vitest
files, 9 Playwright E2E specs, accessibility scans, and visual regression.
Includes GitHub Actions CI, Husky pre-push hook, and TESTING.md docs.
2026-04-04 16:07:21 +01:00

5.8 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Ghost Guild is a membership community platform for game developers exploring cooperative business models. Built with Nuxt 4, Vue 3, MongoDB, and Nuxt UI 4.

Commands

npm run dev        # Start dev server at http://localhost:3000
npm run build      # Production build
npm run preview    # Preview production build
npm run test:run   # Vitest single run (pre-push hook)
npm run test:e2e   # Playwright E2E (needs dev server + MongoDB)
npm run test:a11y  # Accessibility scans
npm run test:all   # Vitest + Playwright

Dev helpers: GET /api/dev/test-login — creates a test admin user and sets auth cookie (dev only, blocked in production). Navigate to this URL to access admin pages during development.

Testing: Vitest for unit/handler tests (tests/), Playwright for E2E (e2e/). Husky pre-push hook runs Vitest. See TESTING.md for details.

Architecture

Stack

  • Framework: Nuxt 4 (Vue 3 + Nitro server)
  • UI: Nuxt UI 4 (@nuxt/ui@^4) with Tailwind CSS
  • Database: MongoDB via Mongoose
  • Auth: JWT magic link (email-only, no passwords)
  • Payments: Helcim (recurring subscriptions + ticket sales)
  • Email: Resend
  • Slack: @slack/web-api for member invitations and notifications
  • Images: Cloudinary
  • Analytics: Plausible (ghostguild.org)

Key Directories

  • app/composables/ — State management via useState() (no Pinia/Vuex). Key composables: useAuth, useHelcim, useMemberPayment, useMemberStatus
  • app/config/ — Circle definitions (circles.js) and contribution tiers (contributions.js) used across frontend and forms
  • app/middleware/ — Route guards: auth.js (member pages), admin.js (admin pages), coming-soon.global.js (launch gate)
  • app/layouts/ — default (sidebar, member/public), admin (sidebar, admin pages), landing, coming-soon
  • server/api/ — Nitro API routes organized by feature: auth/, events/, members/, helcim/, series/, updates/, admin/, slack/, dev/ (dev-only helpers)
  • server/models/ — Mongoose schemas: Member, Event, Series, Update
  • server/utils/ — Service integrations: mongoose.js, helcim.js, resend.js, slack.ts, tickets.js

Domain Model

Three membership circles: Community, Founder, Practitioner — each with different access and context. Five contribution tiers: $0, $5, $15, $30, $50/month via Helcim subscriptions.

Member statuses: pending_payment, active, suspended, cancelled.

Events support ticketing with circle-specific pricing overrides and can be grouped into Series with bundled passes.

Design System (Zine Direction)

  • Palette: CSS custom properties in :root / .dark blocks in app/assets/css/main.css — --bg (cream/#f4efe4), --surface, --border, --candle (gold accent), --ember (rust accent), --text, --text-bright, --text-dim, --text-faint, --parch (inverted blocks), --c-community, --c-founder, --c-practitioner
  • Typography: Brygada 1918 (serif, display/headings) + Commit Mono (monospace, body/UI/everything structural) — loaded via Google Fonts in nuxt.config.ts
  • Theme: primary: amber, neutral: stone — configured in app/app.config.ts. Tailwind @theme maps --font-sans and --font-mono to Commit Mono, --font-display to Brygada 1918
  • Key classes: .btn / .btn-primary / .btn-danger (buttons), .field (form groups), .badge (circle badges), .section-label (10px uppercase headers), .dashed-box (bordered containers), .section-divider
  • Visual language: Dashed borders (1px dashed), cream backgrounds, no rounded corners, text-forward density, minimal decoration
  • Color mode: @nuxtjs/color-mode with preference system, fallback light. Dark mode via .dark class on <html>
  • Layouts: default (sidebar + main, member/public pages), admin (sidebar + main, admin pages), landing (horizontal nav, unused)

Environment

Copy .env.example to .env. Required: MONGODB_URI, JWT_SECRET, RESEND_API_KEY, HELCIM_API_TOKEN, SLACK_BOT_TOKEN. Public vars are prefixed NUXT_PUBLIC_. The NUXT_PUBLIC_COMING_SOON flag gates access behind a launch page.

Conventions

  • All frontend code is plain JavaScript (not TypeScript), using Vue 3 Composition API
  • Server utilities auto-imported by Nitro — no explicit imports needed in API routes
  • Use USwitch (not UToggle) — this is the correct Nuxt UI 3+ component name
  • No fallback/placeholder data — always use real data
  • Follow Nuxt 4 file-based routing conventions for route naming
  • Always check Nuxt UI 4 latest documentation on the web when implementing UI components
  • Auth API responses (/api/auth/status, /api/auth/member) must include status in the returned member object — useMemberStatus defaults to PENDING_PAYMENT if missing
  • Helcim payment testing requires ngrok: npx nuxi dev --https then ngrok http https://localhost:3000 — Helcim blocks localhost origins
  • The /api/helcim/initialize-payment endpoint skips auth for event_ticket type payments (public users can buy tickets)

Product Spec

The sections below describe planned and in-progress features for reference.

Member Features

  • Profiles with privacy controls (public/members-only/private per field)
  • Member updates/mini blog with rich text and images
  • Peer support system with Cal.com integration for 1:1 scheduling

Events System

  • RSVP with capacity limits and waitlist management
  • Calendar export (.ics), ticketing, series passes
  • Member-proposed events with interest threshold

Resources (Planned)

  • Learning paths by circle, templates and tools, case studies
  • Tag by circle relevance, download tracking, version control