# 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

```bash
npm run dev        # Start dev server at http://localhost:3000
npm run build      # Production build
npm run preview    # Preview production build
```

No test framework is currently configured.

## 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`, `admin`, `landing`, `coming-soon`
- `server/api/` — Nitro API routes organized by feature: `auth/`, `events/`, `members/`, `helcim/`, `series/`, `updates/`, `admin/`, `slack/`
- `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

- **Colors:** `guild-*` (warm neutral), `candlelight-*` (amber/gold accent), `parchment-*` (cream surfaces), `ember-*` (rust accent), `earth-*` (brown/ochre) — defined in `app/assets/css/main.css`
- **Circle tokens:** `--color-circle-community`, `--color-circle-founder`, `--color-circle-practitioner` with `-light`, `-dark`, `-bg` variants
- **Typography:** Inter (body), Quietism (display/headers, self-hosted from `public/fonts/`), Ubuntu Mono (code)
- **Theme:** `primary: amber`, `neutral: stone` — configured in `app/app.config.ts`
- **Effects:** `.candlelight-glow`, `.warm-text`, `.ink-grain`, `.paper-texture`, `.woodcut-border`, `.guild-stamp`, `.halftone-texture`, `.dithered-bg`, `.dithered-warm`
- **Content:** `.prose-guild` class for wiki/long-form content with warm palette and Quietism headings

### 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 3 latest documentation on the web when implementing UI components

## 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

### Implementation Priority
**Must have:** Payment processing, Slack automation, member dashboard, resource library, event listing/RSVP
**Nice to have:** Member profiles, peer matching, Cal.com, member updates
**Post-launch:** Etherpad integration, member-proposed events, advanced search, analytics dashboard