Contributing

Set up a local MyClaude development environment, understand the codebase conventions, and submit your first pull request.

Prerequisites

$ node -v   # must be >= 20
$ npm -v    # must be >= 10
$ npx firebase --version

Local setup

$ git clone https://github.com/your-org/vault-marketplace.git
$ cd vault-marketplace
$ npm install
$ cp .env.example .env.local

Fill in .env.local with your Firebase project credentials, Stripe test keys, and R2 credentials. See the Self-Hosting guide for a full variable reference.

Start the dev server

$ npm run dev

The app runs at http://localhost:3000. Hot reload is enabled.

Firebase emulators (optional)

For offline development without a live Firebase project:

$ npx firebase emulators:start --only auth,firestore,storage

Point your .env.local Firebase config to the emulator endpoints.

Project structure

src/
  app/            # Next.js App Router pages and API routes
  components/
    atoms/        # Small UI primitives (badges, buttons, inputs)
    molecules/    # Composed components (cards, search bars)
    organisms/    # Complex sections (headers, product grids)
    ui/           # shadcn/ui components (do not edit)
  contexts/       # React context providers (auth, language)
  lib/
    server/       # Firebase Admin SDK (SSR + API routes ONLY)
    client/       # Firebase Client SDK (browser ONLY)
    i18n/         # Translation dictionaries
  types/          # Shared TypeScript types

Code conventions

Dual SDK boundary

This is the most important architectural rule. Violations break the build.

Never import lib/server/ in a "use client" file. Never import lib/client/ in a Server Component.

TypeScript

• Strict mode enabled. No any unless absolutely necessary.
• Named exports preferred over default exports (except page components).
• Use SafeProduct / SafeUserProfile types in all client-facing code -- these strip sensitive fields like fileUrl.

Atomic design

Components follow the atoms > molecules > organisms hierarchy. A new button goes in atoms/. A card that composes multiple atoms goes in molecules/. A full page section goes in organisms/.

Design system tokens

All styling uses Tailwind theme tokens and custom @utility classes. Inline arbitrary values (text-[#...], bg-[oklch(...)]) are prohibited. See the design system rules for the full policy.

Making changes

Branch naming

Branch from master. No enforced naming convention, but descriptive names help:

$ git checkout -b feat/add-search-filters

Commit messages

Follow the format:

feat|fix|refactor: F{task_id} -- {description}

Examples:

• feat: F42 -- add category filter to explore page
• fix: F38 -- prevent duplicate order creation on webhook retry
• refactor: F50 -- extract rate limit config to constants

Testing

Build gate

npm run build is the primary quality gate. Every PR must pass a clean build.

$ npm run build

This runs the prebuild script (generates docs assets), compiles TypeScript, and produces the production Next.js bundle. Type errors, missing imports, and broken server/client boundaries all fail here.

Integration tests

Integration tests live in tests/. Run them with:

$ npx jest tests/integration-security.test.ts

Manual verification

For API route changes, verify:

1. Auth token is extracted and verified via admin.auth().verifyIdToken()
2. User authorization is checked (ownership, admin role, ban status)
3. Rate limiting is applied (standard or strict)
4. No sensitive data leaks in the response

Submitting a pull request

PR description template

## What changed
One-sentence summary.

## Why
Link to issue or task ID.

## Security checklist
- [ ] Auth token verified on all new/modified API routes
- [ ] User authorization checked (ownership, role, ban)
- [ ] Input validated and sanitized
- [ ] No fileUrl or sensitive data exposed to client
- [ ] Rate limiting applied to new mutation routes
- [ ] Error messages do not leak internal details

What reviewers look for

Related pages

• Architecture -- System design overview
• Security Model -- Security architecture details
• Self-Hosting -- Full environment variable reference
• API Overview -- Endpoint groups and rate limits