Akyodex - Next.js 16 + Cloudflare Pages

VRChat Avatar & World Encyclopedia

📋 Table of Contents

1. Quick Start
2. Project Overview
3. Glossary
4. Architecture
5. Tech Stack
6. Project Structure
7. Development Setup
8. Deployment Guide
9. Deployment Verification
10. Environment Variables
11. Features
12. API Endpoints
13. Security
14. Troubleshooting
15. Migration History
16. Contributing

---

⚡ Quick Start

Get Akyodex running locally in 5 minutes!

Prerequisites Check

# Check Node.js version (need 20.x or later)
node --version

# Check npm version (need 10.x or later)
npm --version

Step 1: Clone and Install (2 minutes)

# Clone repository
git clone https://github.com/rad-vrc/Akyodex.git
cd Akyodex

# Install dependencies
npm install

Step 2: Set Up Environment (1 minute)

The example below uses Bash heredoc syntax. On PowerShell, create .env.local manually and paste the same key/value pairs.

# Create .env.local file with default credentials
cat > .env.local << 'EOF'
# Admin Authentication (simple access codes)
# Owner password (full access): RadAkyo
# Admin password (limited access): Akyo
ADMIN_PASSWORD_OWNER=RadAkyo
ADMIN_PASSWORD_ADMIN=Akyo

# Session Secret (Development only)
SESSION_SECRET=629de6ec4bc16b1b31a6b0be24a63a9ab32869c3e7138407cafece0a5226c39d8439bd4ac8c21b028d7eb9be948cf37a23288ce4b8eebe3aa6fefb255b9c4cbf

# R2 Base URL (for image fetching)
NEXT_PUBLIC_R2_BASE=https://images.akyodex.com

# App Origin (for CSRF protection)
NEXT_PUBLIC_APP_URL=http://localhost:3000
EOF

Step 3: Run Development Server (30 seconds)

# Start dev server
npm run dev

Step 4: Open in Browser

✅ Gallery:     http://localhost:3000/zukan
✅ Admin Panel: http://localhost:3000/admin

Default Admin Credentials:

• Owner Password: RadAkyo (full access)
• Admin Password: Akyo (limited access)

---

📖 Project Overview

Akyodex は、VRChatのオリジナルアバター「Akyo」シリーズと関連ワールドを網羅したオンライン図鑑です。

Key Features

• 🎨 アバター＋ワールドデータベース - 4桁ID管理システム（日本語/英語/韓国語 CSV + JSON データ、avatar/world 二種別）
• 🔐 Admin Panel - HMAC署名セッション認証、画像クロッピング、VRChat連携
• 📱 PWA対応 - 6種類のキャッシング戦略
• 🌍 多言語対応 - 日本語/英語/韓国語（自動検出 + 手動切替）
• ⚡ Edge Runtime - Cloudflare Pages + R2 + KV
• 🤖 Difyチャットボット - AI搭載のアバター検索アシスタント
• 📊 多段データロード - KV → JSON → CSV 自動フォールバック
• 🔍 Sentry 監視 - エラー追跡 + パフォーマンスモニタリング

Project Status

• ✅ Next.js 16.1.6 + Cloudflare Pages (OpenNext adapter)
• ✅ Avatar + World Support (Dual entry types with separate display IDs)
• ✅ Security Hardening (Timing attack, XSS prevention, Input validation)
• ✅ PWA Implementation (Service Worker with 6 caching strategies)
• ✅ VRChat Image Fallback (3-tier fallback: R2 → VRChat page/API → Placeholder)
• ✅ Sentry Observability (Error tracking + performance monitoring)
• ✅ Dify AI Chatbot Integration (Natural language avatar search)
• ✅ Dual Admin System (Owner/Admin role separation)
• ✅ On-demand ISR (Revalidation API + KV Edge Cache)

---

📖 Glossary

Key terms used in this documentation:

General Terms

• SSG (Static Site Generation): Pre-rendering pages at build time for faster performance
• ISR (Incremental Static Regeneration): Updating static pages periodically without rebuilding the entire site
• PWA (Progressive Web App): Web application with native app-like features (offline support, installable)
• Edge Runtime: Code execution at CDN edge locations (closer to users) for lower latency
• HMAC (Hash-based Message Authentication Code): Cryptographic signature for verifying data integrity and authenticity

Cloudflare Services

• Cloudflare Pages: Static site hosting with automatic deployment from Git
• R2 Bucket: Object storage (like AWS S3) for files (CSV, images)
• KV (Key-Value) Store: Fast distributed database for simple key-value pairs (used for sessions and data cache)

VRChat Terms

• Avatar: 3D character model used in VRChat
• Akyo (あきょ): Japanese VRChat avatar series created by the community
• VRChat ID: Unique identifier for avatars (format: avtr_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Technical Terms

• XSS (Cross-Site Scripting): Security vulnerability where attackers inject malicious scripts
• CSRF (Cross-Site Request Forgery): Attack forcing users to execute unwanted actions
• ReDoS (Regular Expression Denial of Service): Attack exploiting inefficient regex patterns
• Timing Attack: Exploiting time differences in operations to extract sensitive information
• HTTP-only Cookie: Cookie inaccessible to JavaScript (prevents XSS attacks)
• SameSite Cookie: Cookie security attribute preventing CSRF attacks

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗