⏰ LolTimeFlash

League of Legends Website Tool: Easily Time and Communicate Summoner Spells - THE FLASH! 🌟

Demo • Features • Quick Start • How It Works • Documentation

---

🎬 Demo

Showcase the real-time Flash tracking, multiplayer synchronization, and customizable backgrounds

---

🎯 What is LolTimeFlash?

LolTimeFlash is a real-time collaborative web application for League of Legends players to track enemy summoner spell cooldowns during gameplay. Create or join rooms with your teammates to monitor Flash timers across all 5 enemy roles and coordinate your ganks perfectly!

🌟 Key Features

• ⏱️ Real-time Flash Tracking - Monitor Flash cooldowns for TOP, JUNGLE, MID, ADC, and SUPPORT
• 🧮 Automatic Cooldown Calculation - Accounts for Lucidity Boots and Cosmic Insight rune
• 🔄 Live Synchronization - All room members see updates instantly via WebSocket
• 👥 Multiplayer Rooms - Create/join rooms with unique 10-character codes
• 🎨 Customizable Backgrounds - Choose from 100+ champion splash arts
• 🔊 Audio Notifications - Get notified when enemy Flash is used
• 📱 Responsive Design - Works perfectly on desktop and mobile
• 🎮 Solo Mode - Practice timing without multiplayer

---

🚀 Quick Start

Prerequisites

• Node.js 20.9.0 or higher
• pnpm 9.10.0 or higher (recommended) or npm

Local Development

# Clone the repository
git clone https://github.com/yourusername/LolTimeFlash.git
cd LolTimeFlash

# Install dependencies
pnpm get_started

# Set up environment variables
cp .env.example .env  # Configure your environment

# Run development servers (API + Web)
pnpm dev

# API: http://localhost:8888
# Web: http://localhost:6333

Docker Deployment (Recommended)

# Quick start - build and run
pnpm docker:test

# Or manually
pnpm docker:build   # Build images
pnpm docker:up      # Start containers
pnpm docker:logs    # View logs
pnpm docker:down    # Stop containers

# Access:
# - Frontend: http://localhost:6333
# - API Health: http://localhost:8888/monitoring/health

---

🎮 How It Works

Flash Cooldown Calculations

LolTimeFlash automatically calculates Flash cooldowns based on enemy items and runes:

Configuration	Cooldown	Reduction
Base	5:00 (300s)	-
Lucidity Boots	4:28 (268s)	-32s
Cosmic Insight	4:15 (255s)	-45s
Both	3:51 (231s)	-69s

Multiplayer Flow

1. Create/Join Room - Generate or enter a 10-character room code
2. Set Username - Identify yourself to teammates
3. Track Flashes - Click role icons when enemy uses Flash
4. Sync with Team - All changes sync in real-time
5. Get Notified - Audio + toast notifications for all team members

---

🛠️ Tech Stack

Frontend (Next.js)

• Framework: Next.js 16.0.1 (App Router + Turbopack)
• Language: TypeScript 5.7.2
• Styling: Tailwind CSS 3.4.17
• State: Zustand 5.0.8, TanStack Query 5.90.8
• Real-time: Socket.IO Client 4.8.1
• UI: Radix UI, React Icons

Backend (NestJS)

• Framework: NestJS 11.0 (Monorepo Architecture)
• Real-time: Socket.IO Server 4.8.1
• Logging: Winston with daily rotation
• API: Riot Games Data Dragon integration

Deployment

• Containerization: Docker + Docker Compose
• Base Image: Node 20.9.0 Alpine
• Package Manager: pnpm 9.10.0
• Monorepo: Turborepo for builds

---

📁 Project Structure

LolTimeFlash/
├── apps/
│   ├── api/                      # NestJS Backend
│   │   ├── src/
│   │   │   ├── game/            # Game logic & WebSocket gateway
│   │   │   ├── room/            # Room management service
│   │   │   ├── riot/            # Riot API integration
│   │   │   ├── monitoring/      # Health checks & metrics
│   │   │   └── logger/          # Winston logging
│   │   ├── libs/shared/         # NestJS internal library
│   │   │   ├── types/           # Shared TypeScript types
│   │   │   └── constants/       # Shared constants
│   │   └── Dockerfile
│   │
│   └── web/                      # Next.js Frontend
│       ├── app/                  # App Router pages
│       ├── components/           # React components
│       ├── features/             # Feature modules
│       ├── hooks/                # Custom hooks
│       ├── lib/                  # Utils & config
│       ├── public/               # Static assets
│       └── Dockerfile
│
├── packages/
│   └── shared/                   # Shared types wrapper
│
├── scripts/                      # Build & sync scripts
├── docker-compose.yml            # Docker orchestration
└── turbo.json                    # Turborepo config

---

🎨 Features in Detail

Real-time Synchronization

All room members see updates instantly when anyone:

• Clicks a Flash button
• Toggles Lucidity Boots or Cosmic Insight
• Cancels a timer

Smart Timer Management

• Click once: Start Flash cooldown
• Click during countdown: Cancel timer (Flash is back)
• Visual feedback: Darkened icon + MM:SS timer overlay

Customization

• Choose from all League of Legends champion splash arts
• Search champions by name
• Background persists across sessions

---

📖 Documentation

For detailed documentation including architecture, API routes, component structure, and development guidelines, see AGENTS.md.

Quick Links

• Architecture Overview
• Game Mechanics
• Socket Events
• Deployment Guide

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting a PR.

Development Workflow

# Create feature branch
git checkout -b feature/your-feature

# Make changes and test
pnpm dev

# Build for production
pnpm build

# Submit PR

---

📝 Environment Variables

Create a .env file at the root:

# API Configuration
PORT=8888
NODE_ENV=development
LOG_LEVEL=info

# Frontend Configuration
NEXT_PUBLIC_SOCKET_PORT=http://localhost:8888
NEXT_PUBLIC_API_URL=http://localhost:8888

See AGENTS.md for advanced configuration.

---

📄 License

This project is a fan-made tool for League of Legends players. League of Legends and all associated properties are trademarks or registered trademarks of Riot Games, Inc.

---

🌐 Links

• Documentation: AGENTS.md
• Riot Developer Portal: developer.riotgames.com
• Next.js Docs: nextjs.org/docs
• Socket.IO Docs: socket.io/docs

---

Built with ❤️ by me

⭐ Star this repo if you find it helpful!