JEPX Shadow Trading

A shadow trading dashboard for battery energy storage system (BESS) arbitrage simulation in the Japan Electric Power Exchange (JEPX) wholesale electricity market.

Overview

This application provides tools for evaluating battery storage arbitrage opportunities in Japan's wholesale electricity market:

• Market Data Visualization: View historical JEPX spot prices, regional demand, and weather data
• Battery Asset Management: Configure virtual battery storage assets with custom specifications
• Trading Strategy Configuration: Define arbitrage strategies with customizable parameters
• Backtesting Simulation: Run historical simulations to evaluate strategy performance
• AI-Powered Analysis: Get insights and explanations from an AI assistant

Technology Stack

Frontend

• Framework: Next.js 15 (App Router) with React 19
• Styling: Tailwind CSS with shadcn/ui components
• Charts: Recharts for data visualization
• State Management: React Query (TanStack Query) for server state
• AI Chat: Vercel AI SDK useChat hook

Backend

• Runtime: Next.js API Routes (Edge Runtime where applicable)
• Database: PostgreSQL with Drizzle ORM
• Authentication: Better Auth with Google OAuth

AI Integration

• Provider: OpenRouter via Vercel AI SDK
• Model: anthropic/claude-3.5-sonnet (configurable)
• Features: Function calling / tool use for database queries

Prerequisites

• Node.js 20+
• pnpm package manager
• Docker (for PostgreSQL)
• Google OAuth credentials (for authentication)
• OpenRouter API key (for AI features)

Quick Start

1. Clone the repository

   git clone https://github.com/exbald/jepx-gccg.git
   cd jepx-gccg

2. Run the setup script

   ./init.sh

   This script will:

   • Check prerequisites
   • Start PostgreSQL in Docker
   • Install dependencies
   • Run database migrations
   • Optionally start the development server

3. Configure environment variables

   Edit the .env file with your credentials:

   # Google OAuth
   GOOGLE_CLIENT_ID="your-client-id"
   GOOGLE_CLIENT_SECRET="your-client-secret"
   
   # OpenRouter AI
   OPENROUTER_API_KEY="your-api-key"
   OPENROUTER_MODEL="openai/gpt-4o-mini"  # Optional: defaults to anthropic/claude-3.5-sonnet
   
   # Auth Secret (generate a secure random string)
   BETTER_AUTH_SECRET="your-secure-secret"

   Available AI Models (via OpenRouter):

   • anthropic/claude-3.5-sonnet (default)
   • openai/gpt-4o-mini
   • deepseek/deepseek-r1-0528-qwen3-8b:free (free tier)
   • See OpenRouter Models for full list

4. Start the development server

   pnpm dev

5. Open the application

   Navigate to http://localhost:3000

Project Structure

shadow-trading-poc/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes
│   │   ├── assets/        # Battery asset CRUD
│   │   ├── strategies/    # Trading strategy CRUD
│   │   ├── simulations/   # Simulation endpoints
│   │   ├── prices/        # Spot price data
│   │   ├── demand/        # Demand data
│   │   ├── weather/       # Weather data
│   │   ├── ai/            # AI chat endpoints
│   │   └── auth/          # Authentication
│   ├── dashboard/         # Protected dashboard pages
│   └── page.tsx           # Landing/login page
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   ├── charts/           # Chart components
│   └── forms/            # Form components
├── lib/                   # Utility functions
│   ├── db/               # Drizzle ORM setup
│   └── auth/             # Better Auth setup
├── drizzle/              # Database migrations
└── public/               # Static assets

Database Schema

The application uses PostgreSQL with the following main tables:

• spot_prices: JEPX spot prices (48 periods/day, 9 EPCO regions)
• demand: Regional electricity demand data
• weather: Temperature data for major cities
• battery_assets: User-configured battery specifications
• strategies: Trading strategy configurations
• simulations: Backtest simulation runs
• simulation_daily_results: Daily results with dispatch schedules
• ai_chats: Chat conversation history
• ai_messages: Individual chat messages

EPCO Regions

The app supports all 9 EPCO (Electric Power Company) regions in Japan:

1. Hokkaido
2. Tohoku
3. Tokyo
4. Chuubu
5. Hokuriku
6. Kansai
7. Chuugoku
8. Shikoku
9. Kyushu (default)

Trading Strategies

Three strategy types are supported:

1. Simple Arbitrage: Fixed charge/discharge periods
2. Threshold: Price-based triggers with minimum spread
3. AI Optimized: Machine learning-based optimization (future)

AI Features

The AI assistant can:

• Query spot prices for any date/region
• Find similar historical days based on price patterns
• Calculate arbitrage opportunities
• Retrieve and explain simulation results
• Answer questions about the JEPX market

Data Import

CSV import functionality is available for:

• Spot prices (JEPX historical data)
• Regional demand data
• Weather data (max/min temperatures)

Development

Running Tests

pnpm test

Database Management

# Generate migration
pnpm drizzle-kit generate

# Push schema changes
pnpm drizzle-kit push

# Open Drizzle Studio
pnpm drizzle-kit studio

# Seed test user (creates test@nocodegdn.com / 123123123)
pnpm seed
# or
pnpm db:seed

Docker Commands

# Start database
docker start jepx-postgres

# Stop database
docker stop jepx-postgres

# View logs
docker logs jepx-postgres

Changelog

2026-01-23 (Latest)

• Fix: Dashboard now correctly displays user's simulations (removed dev-mode bypass)
• Fix: AI Assistant can now retrieve and discuss user's simulation results
• Fix: Strategy list page now correctly shows Active/Inactive status
• Fix: Fixed postgres array query error in AI tools (use inArray instead of raw SQL)
• Enhancement: Added pre-defined AI chat prompts: "Tell me about my simulations", "Tell me about this platform"

2026-01-23

• Fix: AI model now reads from OPENROUTER_MODEL environment variable instead of being hardcoded
• Enhancement: Import APIs now support flexible CSV headers (case-insensitive, various naming conventions)
• Feature: Weather data import is now enabled

License

MIT License - See LICENSE for details.

Support

For questions or issues, please open an issue on GitHub.