CLAUDE.md

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

Communication Style

IMPORTANT: Always communicate in casual Japanese (タメ口). Do not use polite/formal Japanese (敬語).

Development Rules

IMPORTANT: Do NOT run npm commands (install, build, test, etc.) unless explicitly instructed by the user. Only execute npm commands when the user specifically requests them.

Code Style

IMPORTANT: Always use double quotes (") for strings in TypeScript/JavaScript code. Do not use single quotes (').

Example:

// Good
const message = "Hello";
import { Router } from "express";

// Bad
const message = 'Hello';
import { Router } from 'express';

Project Overview

rui-keiba

is a horse racing data analysis platform that migrates data from SQLite (netkeiba-scraper) to PostgreSQL and builds a full-stack TypeScript application for analysis.

Technology Stack:

Database: PostgreSQL 18
Backend: TypeScript + Express + Node.js
Frontend: Next.js 15 + TypeScript + Tailwind CSS
DevOps: Docker + Docker Compose
Admin: pgAdmin 4

Development Commands

Docker Environment

# Start PostgreSQL and pgAdmin containers
docker-compose up -d

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

# Restart containers (useful after schema changes)
docker-compose restart postgres

Database Access

PostgreSQL:
```
localhost:5432
```
- Database:
```
rui_keiba
```
- User:
```
rui
```
- Password:
```
keiba2025
```
pgAdmin:
```
http://localhost:5050
```
- Email:
```
[email protected]
```
- Password:
```
admin2025
```
- Server connection uses hostname
```
postgres
```
  (Docker container name)

Backend Development

cd backend
npm install           # Install dependencies
npm run dev          # Start development server (port 3001)
npm run build        # Build for production
npm start            # Run production build

Environment Variables:

Create
```
.env
```
file in
```
backend/
```
directory

Required:

DB_HOST

DB_PORT

DB_USER

DB_PASSWORD

DB_NAME

PORT

Available API Endpoints:

```
GET /health
```
- Health check with database connection status
```
GET /api/horses
```
- Get latest 10 horses
```
GET /api/races
```
- Get latest 10 races

Frontend Development

cd frontend
npm install           # Install dependencies
npm run dev          # Start development server (port 3000)
npm run build        # Build for production
npm start            # Run production build

Environment Variables:

Create
```
.env.local
```
file in
```
frontend/
```
directory
```
NEXT_PUBLIC_API_URL
```
- Backend API URL (default: http://localhost:3001)

Tech Stack:

Next.js 15 with App Router
TypeScript strict mode
Tailwind CSS for styling
Axios for API calls

Database Architecture

The database schema (database/schema.sql) is automatically initialized when the PostgreSQL container first starts. It defines a comprehensive horse racing data model:

Core Entities:

```
horse
```
- Horse information (ID, name, gender, birthday, relationships to trainer/owner/breeder)
```
jockey
```
- Jockey master data
```
trainer
```
- Trainer master data
```
owner
```
- Owner master data
```
breeder
```
- Breeder master data
```
birthplace
```
- Horse birthplace/region data

Race Data:

```
race_info
```
- Race metadata (name, surface, distance, weather, date, location, class)
```
race_result
```
- Individual horse results per race (position, time, odds, jockey weight, etc.)
- Contains foreign keys to
```
horse
```
  ,
```
jockey
```
  ,
```
trainer
```
  ,
```
owner
```
```
payoff
```
- Betting payouts by ticket type
```
corner_position
```
- Horse positions at each corner (1-10)
```
lap_time
```
- Furlong lap times per race

Key Relationships:

```
race_result
```
links races to horses, jockeys, trainers, and owners
```
race_info_id
```
connects results, payoffs, corner positions, and lap times to races
Cascade deletes on
```
race_info
```
remove all associated race data
Restrict deletes on entity references (horse, jockey, trainer, owner) prevent orphaned results

Schema Features:

Comprehensive indexes on foreign keys, names, and date fields for query performance
Auto-updating
```
updated_at
```
trigger on
```
horse
```
table
Timezone: Asia/Tokyo

Data Migration

Source data comes from

../netkeiba-scraper/race.db

(SQLite). The schema was converted from SQLite to PostgreSQL format. Migration scripts are planned but not yet implemented.

Project Structure

rui-keiba/
├── docker-compose.yml          # PostgreSQL + pgAdmin services
├── .env.example               # Environment variable template
├── database/
│   └── schema.sql             # PostgreSQL schema (auto-loaded on init)
├── backend/                   # TypeScript + Express API server
│   ├── src/
│   │   ├── index.ts          # Main entry point
│   │   ├── config/
│   │   │   └── database.ts   # PostgreSQL connection pool
│   │   ├── routes/           # API route handlers (planned)
│   │   ├── controllers/      # Business logic (planned)
│   │   └── services/         # Data access layer (planned)
│   ├── .env                  # Environment variables (not committed)
│   ├── package.json
│   ├── tsconfig.json
│   └── nodemon.json
└── frontend/                  # Next.js + TypeScript UI (bulletproof-react architecture)
    ├── app/                   # Next.js App Router
    │   ├── page.tsx          # Main dashboard page
    │   ├── layout.tsx        # Root layout
    │   └── races/[id]/       # Race detail page
    ├── src/                   # Application source code
    │   ├── components/       # Shared UI components
    │   │   └── ui/           # Basic UI components (Header, Footer, LoadingScreen)
    │   ├── features/         # Feature-based modules
    │   │   ├── races/        # Race feature
    │   │   │   ├── api/      # Race API hooks (races-api.ts)
    │   │   │   ├── components/ # Race components (RaceCard, RaceList, RaceDetailCard)
    │   │   │   └── types/    # Race type definitions (race.types.ts)
    │   │   └── health/       # Health check feature
    │   │       ├── api/      # Health API hooks (health-api.ts)
    │   │       ├── components/ # Health components (HealthStatus)
    │   │       └── types/    # Health type definitions (health.types.ts)
    │   ├── lib/              # Library configurations
    │   │   ├── api-client.ts # Axios instance configuration
    │   │   ├── providers.tsx # React Query & MUI providers
    │   │   └── theme.ts      # MUI theme configuration
    │   └── utils/            # Utility functions
    │       └── date-utils.ts # Date formatting utilities
    ├── .env.local            # Environment variables (not committed)
    ├── package.json
    ├── tsconfig.json         # Path alias: @/* -> ./src/*
    ├── tailwind.config.ts
    └── next.config.ts

Frontend Architecture (bulletproof-react based):

Feature-based structure: Each feature (races, health) has its own api/components/types
No index.ts files: Import directly from specific files
Shared components in
```
src/components/ui/
```
Path alias
```
@/*
```
maps to
```
src/*
```
for clean imports

Architecture Notes

Backend (Express + TypeScript):

Simple REST API server with PostgreSQL connection pooling
Database config in backend/src/config/database.ts
Main server file: backend/src/index.ts
Currently has basic endpoints; expand by adding routes/controllers/services

Frontend (Next.js 15):

Uses App Router with client-side data fetching
API client configured in frontend/lib/api.ts
Main dashboard: frontend/app/page.tsx
Fetches horses and races on mount, displays with Tailwind styling

Database:

Schema is mounted at
```
/docker-entrypoint-initdb.d/01-schema.sql
```
and runs only on first initialization
To reload schema changes:
```
docker-compose down -v
```
(WARNING: destroys all data)
Data persisted in
```
postgres_data
```
Docker volume
Source SQLite database:
```
../netkeiba-scraper/race.db
```

Development Workflow:

Start Docker containers:
```
docker-compose up -d
```
Start backend:
```
cd backend && npm run dev
```
Start frontend:
```
cd frontend && npm run dev
```
Access frontend at http://localhost:3000

CLAUDE.md

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

Communication Style

IMPORTANT: Always communicate in casual Japanese (タメ口). Do not use polite/formal Japanese (敬語).

Development Rules

IMPORTANT: Do NOT run npm commands (install, build, test, etc.) unless explicitly instructed by the user. Only execute npm commands when the user specifically requests them.

Code Style

IMPORTANT: Always use double quotes (") for strings in TypeScript/JavaScript code. Do not use single quotes (').

Example:

// Good
const message = "Hello";
import { Router } from "express";

// Bad
const message = 'Hello';
import { Router } from 'express';

Project Overview

rui-keiba

is a horse racing data analysis platform that migrates data from SQLite (netkeiba-scraper) to PostgreSQL and builds a full-stack TypeScript application for analysis.

Technology Stack:

Database: PostgreSQL 18
Backend: TypeScript + Express + Node.js
Frontend: Next.js 15 + TypeScript + Tailwind CSS
DevOps: Docker + Docker Compose
Admin: pgAdmin 4

Development Commands

Docker Environment

# Start PostgreSQL and pgAdmin containers
docker-compose up -d

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

# Restart containers (useful after schema changes)
docker-compose restart postgres

Database Access

PostgreSQL:
```
localhost:5432
```
- Database:
```
rui_keiba
```
- User:
```
rui
```
- Password:
```
keiba2025
```
pgAdmin:
```
http://localhost:5050
```
- Email:
```
[email protected]
```
- Password:
```
admin2025
```
- Server connection uses hostname
```
postgres
```
  (Docker container name)

Backend Development

cd backend
npm install           # Install dependencies
npm run dev          # Start development server (port 3001)
npm run build        # Build for production
npm start            # Run production build

Environment Variables:

Create
```
.env
```
file in
```
backend/
```
directory

Required:

DB_HOST

DB_PORT

DB_USER

DB_PASSWORD

DB_NAME

PORT

Available API Endpoints:

```
GET /health
```
- Health check with database connection status
```
GET /api/horses
```
- Get latest 10 horses
```
GET /api/races
```
- Get latest 10 races

Frontend Development

cd frontend
npm install           # Install dependencies
npm run dev          # Start development server (port 3000)
npm run build        # Build for production
npm start            # Run production build

Environment Variables:

Create
```
.env.local
```
file in
```
frontend/
```
directory
```
NEXT_PUBLIC_API_URL
```
- Backend API URL (default: http://localhost:3001)

Tech Stack:

Next.js 15 with App Router
TypeScript strict mode
Tailwind CSS for styling
Axios for API calls

Database Architecture

The database schema (database/schema.sql) is automatically initialized when the PostgreSQL container first starts. It defines a comprehensive horse racing data model:

Core Entities:

```
horse
```
- Horse information (ID, name, gender, birthday, relationships to trainer/owner/breeder)
```
jockey
```
- Jockey master data
```
trainer
```
- Trainer master data
```
owner
```
- Owner master data
```
breeder
```
- Breeder master data
```
birthplace
```
- Horse birthplace/region data

Race Data:

```
race_info
```
- Race metadata (name, surface, distance, weather, date, location, class)
```
race_result
```
- Individual horse results per race (position, time, odds, jockey weight, etc.)
- Contains foreign keys to
```
horse
```
  ,
```
jockey
```
  ,
```
trainer
```
  ,
```
owner
```
```
payoff
```
- Betting payouts by ticket type
```
corner_position
```
- Horse positions at each corner (1-10)
```
lap_time
```
- Furlong lap times per race

Key Relationships:

```
race_result
```
links races to horses, jockeys, trainers, and owners
```
race_info_id
```
connects results, payoffs, corner positions, and lap times to races
Cascade deletes on
```
race_info
```
remove all associated race data
Restrict deletes on entity references (horse, jockey, trainer, owner) prevent orphaned results

Schema Features:

Comprehensive indexes on foreign keys, names, and date fields for query performance
Auto-updating
```
updated_at
```
trigger on
```
horse
```
table
Timezone: Asia/Tokyo

Data Migration

Source data comes from

../netkeiba-scraper/race.db

(SQLite). The schema was converted from SQLite to PostgreSQL format. Migration scripts are planned but not yet implemented.

Project Structure

rui-keiba/
├── docker-compose.yml          # PostgreSQL + pgAdmin services
├── .env.example               # Environment variable template
├── database/
│   └── schema.sql             # PostgreSQL schema (auto-loaded on init)
├── backend/                   # TypeScript + Express API server
│   ├── src/
│   │   ├── index.ts          # Main entry point
│   │   ├── config/
│   │   │   └── database.ts   # PostgreSQL connection pool
│   │   ├── routes/           # API route handlers (planned)
│   │   ├── controllers/      # Business logic (planned)
│   │   └── services/         # Data access layer (planned)
│   ├── .env                  # Environment variables (not committed)
│   ├── package.json
│   ├── tsconfig.json
│   └── nodemon.json
└── frontend/                  # Next.js + TypeScript UI (bulletproof-react architecture)
    ├── app/                   # Next.js App Router
    │   ├── page.tsx          # Main dashboard page
    │   ├── layout.tsx        # Root layout
    │   └── races/[id]/       # Race detail page
    ├── src/                   # Application source code
    │   ├── components/       # Shared UI components
    │   │   └── ui/           # Basic UI components (Header, Footer, LoadingScreen)
    │   ├── features/         # Feature-based modules
    │   │   ├── races/        # Race feature
    │   │   │   ├── api/      # Race API hooks (races-api.ts)
    │   │   │   ├── components/ # Race components (RaceCard, RaceList, RaceDetailCard)
    │   │   │   └── types/    # Race type definitions (race.types.ts)
    │   │   └── health/       # Health check feature
    │   │       ├── api/      # Health API hooks (health-api.ts)
    │   │       ├── components/ # Health components (HealthStatus)
    │   │       └── types/    # Health type definitions (health.types.ts)
    │   ├── lib/              # Library configurations
    │   │   ├── api-client.ts # Axios instance configuration
    │   │   ├── providers.tsx # React Query & MUI providers
    │   │   └── theme.ts      # MUI theme configuration
    │   └── utils/            # Utility functions
    │       └── date-utils.ts # Date formatting utilities
    ├── .env.local            # Environment variables (not committed)
    ├── package.json
    ├── tsconfig.json         # Path alias: @/* -> ./src/*
    ├── tailwind.config.ts
    └── next.config.ts

Frontend Architecture (bulletproof-react based):

Feature-based structure: Each feature (races, health) has its own api/components/types
No index.ts files: Import directly from specific files
Shared components in
```
src/components/ui/
```
Path alias
```
@/*
```
maps to
```
src/*
```
for clean imports

Architecture Notes

Backend (Express + TypeScript):

Simple REST API server with PostgreSQL connection pooling
Database config in backend/src/config/database.ts
Main server file: backend/src/index.ts
Currently has basic endpoints; expand by adding routes/controllers/services

Frontend (Next.js 15):

Uses App Router with client-side data fetching
API client configured in frontend/lib/api.ts
Main dashboard: frontend/app/page.tsx
Fetches horses and races on mount, displays with Tailwind styling

Database:

Schema is mounted at
```
/docker-entrypoint-initdb.d/01-schema.sql
```
and runs only on first initialization
To reload schema changes:
```
docker-compose down -v
```
(WARNING: destroys all data)
Data persisted in
```
postgres_data
```
Docker volume
Source SQLite database:
```
../netkeiba-scraper/race.db
```

Development Workflow:

Start Docker containers:
```
docker-compose up -d
```
Start backend:
```
cd backend && npm run dev
```
Start frontend:
```
cd frontend && npm run dev
```
Access frontend at http://localhost:3000

CLAUDE.md

CLAUDE.md

Communication Style

Development Rules

Code Style

Project Overview

Development Commands

Docker Environment

Database Access

Backend Development

Frontend Development

Database Architecture

Data Migration

Project Structure

Architecture Notes

Related Skills

Nano Banana Pro

Markdown Converter

1password

CLAUDE.md

Communication Style

Development Rules

Code Style

Project Overview

Development Commands

Docker Environment

Database Access

Backend Development

Frontend Development

Database Architecture

Data Migration

Project Structure

Architecture Notes