website/CLAUDE.md

CLAUDE.md

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

🚨 CRITICAL: MANDATORY MCP SERVER USAGE 🚨

YOU MUST USE MCP SERVERS PROACTIVELY AND EXTENSIVELY. This codebase requires heavy use of MCP tools for all operations. Never work blind - always use the appropriate MCP servers BEFORE making any decisions or changes.

⚡ INSTANT MCP TRIGGERS FOR HARBORSMITH

These MUST happen automatically without asking:

User Says	Immediate MCP Response	Full Chain
"charter" or "booking"	Serena:find_symbol("*charter*")	→ Zen:analyze → Edit → Test
"yacht" or "vessel"	Serena:search_for_pattern("yacht|vessel")	→ Understand → Modify → Verify
"payment" or "stripe"	Context7:resolve-library-id("stripe")	→ Docs → Implement → Review
"auth" or "login"	Zen:secaudit + Serena:find_symbol("*auth*")	→ Security check → Fix → Test
"slow" or "performance"	Browser-tools:runPerformanceAudit()	→ Zen:analyze → Optimize → Verify
"error" or "bug"	Zen:debug + Browser-tools:getConsoleErrors()	→ Investigate → Fix → Validate
"deploy"	Zen:precommit	→ Validate → Build → Deploy
"test"	Zen:testgen + Playwright:automate	→ Generate → Run → Report
ANY code edit	IDE:getDiagnostics()	→ Fix errors → Zen:review
New feature	Zen:planner	→ Plan → Research → Implement

🎯 MCP Server Quick Reference

Copy-paste these patterns:

// Debug pattern
await zen.debug({ step: "Investigating charter booking issue", confidence: "medium" })
await browserTools.getConsoleErrors()
await serena.find_symbol("CharterBooking")

// Review pattern
await zen.codereview({ relevant_files: ["apps/api/*"], review_type: "security" })

// Performance pattern
await browserTools.runPerformanceAudit()
await zen.thinkdeep({ focus_areas: ["performance"] })
await serena.search_for_pattern("SELECT.*FROM", context_lines_after: 5)

Available MCP Servers and When to Use Them

1. Zen - ALWAYS USE FOR COMPLEX TASKS

• MANDATORY for: Debugging, code review, architecture decisions, planning
• Tools: thinkdeep, debug, codereview, consensus, planner, precommit
• Usage: ANY complex problem, architecture decision, or code quality check
• Example: mcp__zen__debug for any bug, mcp__zen__codereview after writing code

2. Serena - ALWAYS USE FOR CODE NAVIGATION

• MANDATORY for: Reading/understanding code, refactoring, symbol search
• Tools: find_symbol, get_symbols_overview, search_for_pattern, replace_symbol_body
• Usage: NEVER read files directly without first using Serena's semantic tools
• Example: Always use find_symbol before editing, get_symbols_overview before understanding a file

3. Context7 - ALWAYS USE FOR LIBRARIES

• MANDATORY for: Any external library usage or documentation
• Tools: resolve-library-id, get-library-docs
• Usage: Before implementing ANY library feature, get its documentation
• Example: Using Stripe? First: resolve-library-id("stripe") then get-library-docs

4. Playwright - USE FOR ALL UI TESTING

• Tools: browser_navigate, browser_click, browser_snapshot, browser_fill_form
• Usage: Testing user flows, capturing UI state, form validation

5. 21st-dev Magic - USE FOR UI COMPONENTS

• Tools: 21st_magic_component_builder, logo_search
• Usage: When user requests UI components or logos

MCP Usage Rules

1. ALWAYS chain MCP tools - One tool's output should trigger the next
2. NEVER make assumptions - Use tools to verify everything
3. Parallel execution - Run independent MCP calls simultaneously
4. Use Zen for thinking - Complex reasoning MUST go through Zen
5. Verify with tools - After changes, ALWAYS run verification tools

Project Overview

Harborsmith is a comprehensive yacht charter and maintenance management platform for the San Francisco Bay Area, built with a microservices architecture using Docker containers behind nginx.

Technology Stack

Frontend:

• Nuxt 3 (SSG for website, SPA for webapp, SSR/SPA for admin portal)
• Tailwind CSS v4, Nuxt UI v3, Tremor (dashboards), Motion.dev (animations)
• Pinia (state management), VueUse (utilities)
• Uppy (file uploads, 10GB+ support), hls.js (video streaming)

Backend:

• Fastify + tRPC (type-safe APIs)
• Prisma ORM with PostgreSQL 16
• BullMQ (job queues), Socket.io (real-time)
• Redis (caching), PgBouncer (connection pooling)

Infrastructure:

• Docker Compose orchestration
• nginx reverse proxy (host level)
• External MinIO for object storage
• Keycloak (authentication), Directus (CMS)
• Multiple service replicas for high availability

Architecture Pattern

nginx (host) → Docker Containers → Services
                ├── API (3 replicas) → PostgreSQL/Redis
                ├── Website (2 replicas)
                ├── WebApp (2 replicas)
                └── Portal (2 replicas)

Essential Commands

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View logs
docker-compose logs -f [service_name]

# Run database migrations
docker-compose run --rm api npx prisma migrate deploy

# Database operations
docker exec harborsmith_postgres pg_dump -U $DB_USER harborsmith > backup.sql
docker exec -i harborsmith_postgres psql -U $DB_USER harborsmith < backup.sql

# Deploy to production
./deploy.sh

# Check service health
./scripts/wait-for-healthy.sh

# Rebuild specific service
docker-compose up -d --no-deps --build api-1

Service Ports

• 3000, 3010, 3020: API replicas
• 3001-3002: Website replicas
• 3003-3004: WebApp replicas
• 3005-3006: Portal replicas
• 5432: PostgreSQL (via PgBouncer on 6432)
• 6379: Redis
• 9000: MinIO (external)
• 8080: Keycloak

Environment Configuration

Critical environment variables that MUST be set:

# Database
DB_USER=harborsmith
DB_PASSWORD=<secure_password>

# External MinIO (already running separately)
MINIO_ENDPOINT=<minio_host>
MINIO_PORT=9000
MINIO_USE_SSL=true
MINIO_ACCESS_KEY=<access_key>
MINIO_SECRET_KEY=<secret_key>

# Authentication
KEYCLOAK_URL=https://auth.harborsmith.com
KEYCLOAK_REALM=harborsmith
KEYCLOAK_CLIENT_ID=harborsmith-webapp

# Payments
STRIPE_SECRET_KEY=sk_live_<key>
CAL_API_KEY=cal_live_<key>

Critical Implementation Details

WebSocket Scaling

• nginx uses ip_hash for sticky sessions
• Socket.io configured with Redis adapter
• Connection state recovery enabled

Database Optimization

• PgBouncer for connection pooling (transaction mode)
• Proper indexes on all foreign keys
• PostgreSQL performance tuning applied

Security Configuration

• CORS with origin validation
• Application-level rate limiting
• JWT refresh token rotation
• All containers expose ports only to localhost

Caching Strategy

• Cache-aside pattern with Redis
• TTL strategies per data type
• Cache warming for popular content

Media Handling

• Uppy for resumable uploads (10GB+)
• Tus protocol implementation
• FFmpeg for HLS video transcoding
• MinIO for S3-compatible storage

🔥 Harborsmith-Specific MCP Workflows

Charter Booking Flow Issues

1. Zen:debug("charter booking failing")
2. Serena:find_symbol("CharterService/createBooking")
3. Browser-tools:getNetworkErrors()
4. Context7:get-library-docs("/stripe/stripe-node", topic="payments")
5. Fix issue with Serena:replace_symbol_body
6. Playwright:test booking flow
7. Zen:codereview(review_type="security")

Yacht Maintenance Scheduling

1. Zen:planner("implement maintenance scheduling")
2. Serena:search_for_pattern("maintenance.*schedule")
3. Context7:resolve-library-id("node-cron")
4. Implement with BullMQ queues
5. Zen:testgen for maintenance service
6. Browser-tools:performance audit

Payment Integration

1. Context7:get-library-docs("/stripe/stripe-node", topic="webhooks")
2. Zen:secaudit(focus="payment-processing")
3. Serena:find_symbol("PaymentService")
4. Implement Stripe webhook handler
5. Zen:codereview(review_type="security", severity_filter="high")
6. Playwright:test payment flow with test cards

Admin Portal Dashboard

1. Zen:consensus("dashboard visualization library")
2. Context7:resolve-library-id("tremor")
3. Serena:find_symbol("AdminDashboard")
4. Implement with Tremor components
5. Browser-tools:runAccessibilityAudit()
6. Zen:codereview(focus="performance")

Development Workflow with MCP

Before ANY Code Change:

1. Use Serena to understand current implementation
   • find_symbol to locate code
   • find_referencing_symbols to check impact
2. Use Zen to plan approach
   • planner for complex tasks
   • thinkdeep for architecture decisions

During Implementation:

1. Use Context7 for library documentation
2. Use Serena for code modifications
3. Use Zen chat for second opinions

After Changes:

1. ALWAYS run getDiagnostics() via IDE tools
2. Use Zen codereview for quality check
3. Use Zen precommit before committing

For Debugging:

1. Start with Zen debug for systematic investigation
2. Use Browser-tools for UI issues
3. Use Serena to navigate to problematic code

Monorepo Structure (Planned)

harborsmith/
├── apps/
│   ├── website/      # Public SSG site
│   ├── webapp/       # Customer SPA
│   ├── portal/       # Admin portal
│   └── api/          # Main API
├── packages/
│   ├── shared/       # Shared types/utils
│   ├── ui/           # UI components
│   └── database/     # Prisma schema
└── services/         # Microservices
    ├── charter/
    ├── maintenance/
    ├── payments/
    └── notifications/

🧪 Automated Testing & Review Patterns

MANDATORY Test Automation for Every Feature

# 1. Generate comprehensive tests
Zen:testgen(target="CharterService", confidence="high")

# 2. Run unit tests
npm run test:unit -- --coverage

# 3. E2E automation
Playwright:browser_navigate("/charter/new")
Playwright:browser_fill_form([
  {name: "vessel", value: "Yacht001"},
  {name: "date", value: "2024-03-15"},
  {name: "duration", value: "4"}
])
Playwright:browser_click("Book Charter")
Playwright:browser_wait_for(text="Booking Confirmed")

# 4. Validate UI
Browser-tools:runAccessibilityAudit()
Browser-tools:runPerformanceAudit()
Browser-tools:getConsoleErrors()

# 5. Security review
Zen:secaudit(audit_focus="owasp", threat_level="high")

Code Review Automation

# After EVERY significant change
Zen:codereview(
  relevant_files=["apps/api/src/**"],
  review_type="full",
  severity_filter="medium",
  model="gemini-2.5-pro"
)

# Security-focused review for auth/payment
Zen:codereview(
  review_type="security",
  focus_on="authentication,authorization,payment",
  model="o3"
)

# Performance review for critical paths
Zen:codereview(
  review_type="performance",
  focus_on="database queries,caching,api response time",
  model="gemini-2.5-flash"
)

Continuous Testing Pattern

# Watch mode during development
npm run test:watch

# After each code change
IDE:getDiagnostics()
npm run lint
npm run typecheck

# Before commit
Zen:precommit(
  focus_on="security,completeness,tests",
  severity_filter="high"
)

# Full validation before deploy
./scripts/run-all-tests.sh
Zen:codereview(review_type="full")
Browser-tools:runAuditMode()

MCP-First Development Principles

1. NEVER work without MCP tools - Always gather context first
2. Chain operations - Each MCP output informs the next action
3. Parallel when possible - Run independent MCP calls simultaneously
4. Verify constantly - Use diagnostic tools after every change
5. Think through Zen - Complex reasoning must use Zen tools
6. Document in memories - Use Serena to persist important decisions

🚀 Harborsmith Feature Implementation Patterns

Crew Management Feature

# Planning
Zen:planner("crew management system with scheduling")
Zen:consensus([{model:"o3",stance:"for"},{model:"gemini-2.5-pro",stance:"neutral"}])

# Research
Context7:get-library-docs("/prisma/prisma", topic="relations")
Serena:search_for_pattern("crew|staff|employee")

# Implementation
Serena:insert_after_symbol("YachtModel", "crew relation")
Serena:create CrewService with CRUD operations
Implement crew scheduling with BullMQ

# Validation
Zen:testgen("CrewService", confidence="high")
Playwright:test crew assignment flow
Zen:codereview(review_type="full")

Real-time Vessel Tracking

# Architecture
Zen:thinkdeep("real-time vessel tracking architecture")
Context7:get-library-docs("/socketio/socket.io", topic="namespaces")

# Implementation
Serena:find_symbol("SocketService")
Implement vessel namespace in Socket.io
Add Redis adapter for scaling
Integrate with AIS data provider

# Testing
Playwright:browser_navigate("/vessel-tracker")
Browser-tools:getNetworkLogs() # Check WebSocket
Zen:codereview(focus="real-time-performance")

Weather Integration

# Research
Context7:resolve-library-id("openweather")
Zen:consensus("weather API provider selection")

# Implementation
Serena:create WeatherService
Implement caching with Redis (1hr TTL)
Add weather alerts for charters

# Validation
Zen:testgen("WeatherService")
Browser-tools:runPerformanceAudit()
Zen:precommit()

Common MCP Workflows

Bug Investigation

1. Zen debug (start investigation)
2. Browser-tools (gather symptoms)
3. Serena find_symbol (locate code)
4. Zen debug (refine hypothesis)
5. Serena replace_symbol_body (fix)
6. Zen codereview (verify fix)

Feature Implementation

1. Zen planner (break down task)
2. Context7 (get library docs)
3. Serena find_symbol (understand current code)
4. Implement changes
5. Zen codereview (quality check)
6. Playwright (test user flow)

Performance Optimization

1. Browser-tools audits (baseline)
2. Zen thinkdeep (analyze bottlenecks)
3. Serena search_for_pattern (find issues)
4. Optimize code
5. Browser-tools audits (verify improvement)

IMPORTANT: External MinIO Integration

MinIO runs in a SEPARATE Docker Compose stack. The application connects via:

• MINIO_ENDPOINT: External MinIO host/IP
• MINIO_PORT: Usually 9000
• Ensure network connectivity between Docker containers and MinIO

🚀 Production Deployment & Monitoring Workflows

Pre-Deployment MCP Validation

# 1. Comprehensive security audit
Zen:secaudit(
  audit_focus="comprehensive",
  threat_level="high",
  compliance_requirements=["PCI DSS", "GDPR"]
)

# 2. Performance baseline
Browser-tools:runPerformanceAudit()
Browser-tools:runBestPracticesAudit()

# 3. Final code review
Zen:codereview(
  review_type="full",
  review_validation_type="external",
  model="o3"
)

# 4. Pre-commit validation
Zen:precommit(
  precommit_type="external",
  severity_filter="medium",
  include_staged=true,
  include_unstaged=true
)

Deployment Automation

# 1. Build and test
docker-compose build
docker-compose run --rm api npm test
docker-compose run --rm api npm run test:e2e

# 2. Database migration
docker-compose run --rm api npx prisma migrate deploy

# 3. Rolling deployment
./scripts/deploy.sh --strategy=rolling

# 4. Health verification
./scripts/wait-for-healthy.sh

# 5. Post-deployment validation
Playwright:browser_navigate("https://harborsmith.com")
Browser-tools:runAuditMode()

Monitoring & Alerting Patterns

# Container health monitoring
docker-compose ps
docker-compose logs -f --tail=100

# Performance monitoring
Browser-tools:runPerformanceAudit() # Every hour
Zen:analyze(analysis_type="performance") # Daily

# Error tracking
Browser-tools:getConsoleErrors() # Real-time
Zen:debug(confidence="exploring") # On error spike

# Security monitoring
Zen:secaudit(audit_focus="dependencies") # Weekly
Browser-tools:runBestPracticesAudit() # Daily

Incident Response Workflow

# 1. Immediate assessment
Zen:debug(
  step="Production incident: [description]",
  confidence="exploring",
  model="o3"
)

# 2. Gather evidence
Browser-tools:getConsoleErrors()
Browser-tools:getNetworkErrors()
docker-compose logs --tail=1000 api

# 3. Root cause analysis
Zen:thinkdeep(
  focus_areas=["performance", "security", "architecture"],
  thinking_mode="high"
)

# 4. Implement fix
Serena:find_symbol("[problematic code]")
Serena:replace_symbol_body()
Zen:codereview(review_type="quick")

# 5. Deploy hotfix
./scripts/deploy-hotfix.sh
Zen:precommit(precommit_type="internal")

Backup & Recovery

# Database backup
docker exec harborsmith_postgres pg_dump -U $DB_USER harborsmith > backup_$(date +%Y%m%d_%H%M%S).sql

# MinIO data sync
rclone sync harborsmith-minio:/ backup/minio/

# Configuration backup
cp -r .env* docker-compose.yml nginx.conf backup/config/

# Recovery validation
docker-compose down
docker-compose up -d
./scripts/wait-for-healthy.sh
Playwright:test critical user flows

Security Checklist

Before ANY commit:

• Run Zen precommit validation
• No secrets in code
• CORS properly configured
• Rate limiting implemented
• Input validation with Zod
• SQL injection prevented (Prisma)

Performance Targets

• Page load: < 1 second
• API response: < 200ms
• Database queries: < 50ms
• Upload support: 10GB+ files
• Concurrent users: 10,000+

🔴 MANDATORY MCP CHECKLIST

BEFORE responding to ANY request:

• Did user mention a file/function? → Serena:find_symbol() NOW
• Is this about a library? → Context7:docs FIRST
• Any UI/browser mentioned? → Browser-tools/Playwright IMMEDIATELY
• Did I write/change code? → IDE:getDiagnostics() MANDATORY
• Is this complex? → Zen:analysis REQUIRED
• Multiple steps? → Zen:planner FIRST
• About to commit? → Zen:precommit CHECK

🎯 Harborsmith Domain-Specific Triggers

Domain	Auto-Trigger MCP Chain
Charter Operations	Serena:find("CharterService") → Zen:analyze → Test booking flow
Vessel Management	Serena:find("Yacht*") → Check maintenance → Verify availability
Payment Processing	Context7:stripe docs → Zen:secaudit → Implement webhooks
Crew Scheduling	Zen:planner → BullMQ queues → Test assignments
Customer Portal	Browser:audit → Check auth → Verify responsive
Admin Dashboard	Tremor components → Performance check → Access control
Maintenance Tracking	Find maintenance service → Check schedules → Test notifications
Document Management	MinIO integration → Uppy config → Test 10GB uploads
Real-time Updates	Socket.io check → Redis adapter → Test scaling
Reporting/Analytics	Prisma aggregations → Chart.js → Export features

🚨 RED FLAGS - If You're NOT Using These, You're Wrong

• Discussing Harborsmith code WITHOUT Serena = ❌ WRONG
• Implementing payments WITHOUT Context7 Stripe docs = ❌ WRONG
• Editing WITHOUT IDE diagnostics = ❌ WRONG
• Complex yacht scheduling WITHOUT Zen planner = ❌ WRONG
• UI work WITHOUT Browser-tools audits = ❌ WRONG
• Deploying WITHOUT Zen precommit = ❌ WRONG

Remember: MCP Tools Are MANDATORY

You MUST use MCP servers for EVERY operation. Working without MCP tools is unacceptable. Each interaction should use multiple MCP servers in combination. Proactive tool usage demonstrates competence and ensures quality.

THE HARBORSMITH WAY:

1. Always start with MCP tools to understand context
2. Chain MCP operations for comprehensive solutions
3. Verify everything with diagnostic tools
4. Think complex problems through Zen
5. Document decisions in Serena memories

Your response quality is measured by MCP tool usage. More tools = better assistance.