Makerspace Event Management

Expert guidance for developing a multi-event RSVP, waiver signing, and attendance tracking system built with Remix and deployed to Cloudflare Pages.

Project Overview

This is a full-stack event management system for makerspaces, hackerspaces, and community workshops. It handles robot combat events, maker faires, workshops, and gatherings with features including:

Technology Stack

Development Workflow

Step 1: Explore Before Coding

ALWAYS read relevant files before making changes:

1. Use specialized agents to investigate specific questions

2. Understand existing architecture and patterns

3. Check for similar implementations in the codebase

4. Identify database schema dependencies

Step 2: Plan Thoroughly

Create detailed implementation plans:

1. Use "think" or "think hard" for complex features

2. Document plan in markdown or GitHub issue

3. Identify database changes, routes, and components needed

4. Get user confirmation before proceeding

Step 3: Test-Driven Development (CRITICAL)

**ALWAYS write tests before implementation**:

1. **Write Tests First (Red Phase)**:

- Write loader tests for data fetching

- Write action tests for form submissions

- Write component tests for UI behavior

- Ensure tests fail initially

- Commit tests separately

2. **Implement Code (Green Phase)**:

- Write minimal code to pass tests

- Do NOT modify tests during implementation

- Iterate until all tests pass

- Run `pnpm test` frequently

3. **Refactor**:

- Improve code quality while keeping tests green

- Extract reusable components

- Run `pnpm format`

Step 4: Commit with Conventional Format

Use conventional commit messages:

**Pre-Commit Checklist**:

```bash

pnpm validate # Runs typecheck + lint + test

git status # Review staged changes

git diff # Review actual changes

```

Common Commands

```bash

Setup

pnpm install

Development

pnpm dev # Start dev server (localhost:3000)

pnpm typecheck # TypeScript type checking

Database

pnpm db:generate # Generate migrations from schema

pnpm db:migrate # Run migrations locally

pnpm db:migrate:prod # Run migrations on production D1

pnpm db:seed # Seed database with sample data

pnpm db:studio # Open Drizzle Studio GUI

Testing (ALWAYS run before committing)

pnpm test # Run all tests (Vitest)

pnpm test:watch # Run tests in watch mode

pnpm test:e2e # Run Playwright E2E tests

pnpm test:coverage # Generate coverage report

Code Quality

pnpm lint # ESLint + Prettier check

pnpm format # Format code with Prettier

pnpm validate # Run all checks (typecheck + lint + test)

Build & Deploy

pnpm build # Build for production

pnpm preview # Preview production build

pnpm deploy # Deploy to Cloudflare Pages

pnpm cf:tail # Tail Cloudflare logs

Git and GitHub

gh pr create --title "feat: add waiver signing" --body "Description"

gh pr list

gh issue create --title "Bug: RSVP form validation" --body "Steps"

```

Code Standards

Testing Requirements

Component Development Pattern

1. Write test first (TDD)

2. Use TypeScript for props with JSDoc comments

3. Use shadcn/ui primitives when possible

4. Ensure keyboard accessibility (WCAG 2.1 AA)

5. Add loading and error states

6. Test on mobile viewport

Route Development Pattern

1. Define loader for data fetching (if needed)

2. Define action for form handling (if needed)

3. Validate inputs with Zod schemas

4. Handle errors gracefully with proper HTTP status codes

5. Add meta tags for SEO

6. Test loader and action separately

Database Patterns

Key Architectural Patterns

Git Workflow

**Branch Naming**:

**Merge Flow**: `feature/* → main`

Environment Variables

Required in `.env` file:

```env

SESSION_SECRET=your_random_secret_key

DATABASE_ID=your_d1_database_id

RESEND_API_KEY=re_your_key

[email protected]

[email protected]

ADMIN_PASSWORD_HASH=your_bcrypt_hash

CLOUDFLARE_ACCOUNT_ID=your_account_id

CLOUDFLARE_API_TOKEN=your_api_token

```

Deployment

Cloudflare Pages Setup

1. Install Wrangler: `pnpm add -g wrangler && wrangler login`

2. Create D1 database: `wrangler d1 create your-db-name`

3. Run migrations: `pnpm db:migrate:prod`

4. Deploy: `pnpm deploy`

5. Set secrets: `wrangler pages secret put SESSION_SECRET`

GitHub Integration

Connect repository in Cloudflare Pages dashboard:

Troubleshooting

```bash

Tests failing

pnpm test -- --reporter=verbose

pnpm typecheck

Database issues

pnpm db:studio

wrangler d1 execute your-db --command "SELECT * FROM events"

Deployment failures

wrangler pages deployment tail

pnpm build

```

Important Reminders

1. **ALWAYS follow TDD**: Write tests before implementation

2. **ALWAYS run `pnpm validate`** before committing

3. **Use Git and GitHub CLI** for all version control operations

4. **Ask clarifying questions** before architectural changes

5. **Prioritize accessibility**: Keyboard navigation, ARIA labels, WCAG 2.1 AA

6. **Progressive enhancement**: Server-side first, forms work without JS

7. **Type safety**: All files must pass TypeScript strict mode