hensei-web/CLAUDE.md

CLAUDE.md

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

Repository Context

This is the NEW frontend application for the Hensei system - a Granblue Fantasy team/party management platform. It is a SvelteKit rewrite of the existing Next.js application.

System Components:

• hensei-svelte (this repository): New SvelteKit frontend (actively being developed)
• hensei-web (../hensei-web): Current Next.js frontend (being migrated from)
• hensei-api (../hensei-api): Rails API backend that provides all data and authentication
• siero-bot: Discord bot (separate repository)

Development Commands

Frontend (hensei-svelte)

# Install dependencies (using pnpm)
pnpm install

# Development server (Vite + SvelteKit)
pnpm dev              # Start dev server on default port

# Build & Production
pnpm build            # Build for production
pnpm preview          # Preview production build

# Code Quality
pnpm check            # Type-check with svelte-check
pnpm check:watch      # Type-check in watch mode
pnpm lint             # Run Prettier and ESLint
pnpm format           # Format code with Prettier

# Testing
pnpm test             # Run all tests once
pnpm test:unit        # Run tests with Vitest (watch mode)

# Storybook
pnpm storybook        # Start Storybook on port 6006
pnpm build-storybook  # Build Storybook for production

Backend API (hensei-api)

cd ../hensei-api

# Install dependencies
bundle install

# Database
rails db:create       # Create database
rails db:migrate      # Run migrations
rails db:seed         # Seed database

# Development
rails server          # Start API server (port 3000)
rails console         # Rails console

# Testing
bundle exec rspec     # Run test suite

# Code Quality
bundle exec rubocop   # Ruby linter

# Background Jobs
bundle exec sidekiq   # Start background job processor

Migration Status

Overview

This SvelteKit application (hensei-svelte) is a complete rewrite of the existing Next.js application (hensei-web). The migration is currently in progress.

Migrated Features ✅

• Routes:

  • /about - About page
  • /auth - Authentication flow
  • /teams - Team listing and management
  • /party - Party-related pages
  • /collection - Collection management
  • /login - Login page
  • /me - User profile
  • /[username] - User profiles

• Components:

  • Character, Weapon, Summon units (basic versions)
  • Grid components (GridRep)
  • Party components
  • Navigation component
  • Button and Icon components

Not Yet Migrated ❌

• Routes (from hensei-web):

  • /new - New party creation workflow
  • /p - Party permalink/sharing
  • /saved - Saved parties
  • /roadmap - Roadmap page
  • /updates - Updates/changelog page
  • Error pages (server-error, unauthorized)

• Components (from hensei-web):

  • Full modal systems (CharacterModal, WeaponModal, SummonModal)
  • Conflict resolution modals
  • Hovercards (CharacterHovercard, WeaponHovercard, SummonHovercard)
  • Search and filter bars
  • Job system components
  • Mastery components
  • Raid selection components
  • Rich text editor (TipTap integration)
  • Various dialogs and common components

Key Differences in Implementation

• State Management: Migrating from Valtio (Next.js) to TanStack Query (SvelteKit)
• Styling: Both use SCSS modules, but component structure differs
• i18n: Migrating from next-i18next to Paraglide.js
• Routing: From Next.js App Router to SvelteKit file-based routing
• Components: From React to Svelte 5 with runes

Architecture Overview

System Architecture

The Hensei system consists of multiple components:

1. hensei-svelte (this repository): New SvelteKit frontend (in development)
2. hensei-web (../hensei-web): Current Next.js 14 frontend (being replaced)
   • React 18 with TypeScript
   • Radix UI components
   • Valtio for state management
   • TipTap for rich text editing
   • SCSS modules for styling
3. hensei-api (../hensei-api): Rails API backend
   • Ruby 3.3.7 + Rails 8.0.1
   • PostgreSQL with full-text search
   • OAuth2 authentication (Doorkeeper)
   • AWS S3 for image storage
   • Sidekiq for background jobs
   • Blueprinter for JSON serialization

Frontend Tech Stack

• Framework: SvelteKit with Svelte 5
• Build Tool: Vite 7
• Language: TypeScript with strict mode enabled
• Package Manager: pnpm (10.15.1)
• Styling: SCSS with CSS Modules pattern
• Testing: Vitest with browser testing (Playwright)
• Internationalization: Paraglide.js with English and Japanese support
• UI Components: Bits UI library
• Data Fetching: TanStack Query for Svelte
• Deployment: Node adapter for server deployment

Project Structure

src/
├── routes/              # SvelteKit file-based routing
│   ├── [username]/      # Dynamic user profile routes
│   ├── auth/            # Authentication flows
│   ├── teams/           # Team management pages
│   ├── party/           # Party-related pages
│   └── collection/      # Collection management
├── lib/
│   ├── api/             # API client layer
│   │   ├── core.ts      # API client core functionality
│   │   ├── resources/   # Resource-specific API calls (parties, users, etc.)
│   │   └── schemas/     # Zod schemas for API responses
│   ├── components/      # Reusable Svelte components
│   │   ├── units/       # Unit components (Character, Weapon, Summon)
│   │   ├── reps/        # Representation components
│   │   ├── grids/       # Grid layout components
│   │   ├── party/       # Party-specific components
│   │   └── panels/      # Panel components
│   ├── auth/            # Authentication utilities
│   ├── services/        # Business logic services
│   ├── types/           # TypeScript type definitions
│   ├── validation/      # Input validation schemas
│   └── paraglide/       # Generated i18n files
├── themes/              # SCSS theme files
└── assets/              # Static assets

Key Architectural Patterns

1. Component Organization: Components are organized by domain (units, reps, grids, etc.) with each having its own module structure.

2. API Layer: Centralized API client in lib/api/ with resource-specific modules and Zod schema validation.

3. Type Safety: Strict TypeScript configuration with additional safety flags enabled (noUncheckedIndexedAccess, exactOptionalPropertyTypes).

4. Internationalization: Uses Paraglide.js with message files in messages/ directory, supporting English and Japanese locales.

5. Testing Strategy: Dual testing approach with browser tests for Svelte components and Node tests for server-side code.

6. Path Aliases:

   • $lib/* → src/lib/* (SvelteKit default)
   • $types → src/lib/types (custom alias)
   • $src → src/ (Vite alias)

7. Import Patterns:

   • Prefer direct imports over re-exports for better clarity and tree-shaking
   • Import types directly from their source files (e.g., import type { Party } from '$lib/types/api/party')
   • Avoid creating barrel files (index.ts) that re-export from other modules
   • Exception: Generated code (like Paraglide messages) may use re-exports
   • This pattern improves TypeScript performance and makes dependencies explicit

   Correct Import Examples:

   // ✅ Good - Direct imports
   import { partyAdapter } from '$lib/api/adapters/party.adapter'
   import { userAdapter } from '$lib/api/adapters/user.adapter'
   import { createSearchResource } from '$lib/api/adapters/resources/search.resource.svelte'
   import type { Party } from '$lib/types/api/party'
   import type { AdapterOptions } from '$lib/api/adapters/types'
   import { ApiError } from '$lib/api/adapters/errors'
   
   // ❌ Bad - Barrel file imports
   import { partyAdapter, userAdapter } from '$lib/api/adapters'
   import type { Party } from '$lib/api/adapters'
   

Component Patterns

Components follow a consistent structure:

• .svelte file for component logic
• .module.scss for scoped styles (when needed)
• TypeScript for type safety
• Props validation with Zod schemas where applicable

API Integration

The frontend communicates with hensei-api (Rails backend) for:

• Authentication: OAuth2 via Doorkeeper (/oauth/token)
• Party Management: CRUD operations on party configurations
• Grid Management: Managing characters, weapons, and summons in parties
• User Management: Profile updates, username/email availability checks
• Favorites: Managing favorite parties
• Jobs: Job selection and skill management
• Search: Full-text search across game data
• Raids & Guidebooks: Game content categorization

Key API patterns:

• All endpoints require Bearer token authentication
• Responses use Blueprinter serialization
• Base path: /api/v1/
• Image assets served from AWS S3

Domain Models (from hensei-api)

Key models that the frontend interacts with:

• Party: Team configurations with characters, weapons, summons, job, and skills
• Character/Weapon/Summon: Game items with various attributes and enhancements
• GridCharacter/GridWeapon/GridSummon: Junction tables for party composition
• User: Authentication and party ownership
• Job/JobSkill/JobAccessory: Player job system
• Raid/RaidGroup: Content categorization
• Awakening/WeaponKey: Item enhancement systems
• Favorite: User's bookmarked parties
• Guidebook: Game strategy guides

Testing Configuration

Vitest is configured with two test projects:

• Client tests: Browser-based tests for Svelte components using Playwright
• Server tests: Node-based tests for server-side logic

Tests should follow the pattern *.{test,spec}.{js,ts} for server tests and *.svelte.{test,spec}.{js,ts} for component tests.