🌍 World Clock & Timer

React-based time management application with world clocks, countdown timer, and stopwatch

Live Demo · Report Bug · Request Feature

---

📖 Table of Contents

• Overview
• Features
• Demo Screenshots
• Quick Start
• Project Structure
• Technology Stack
• Browser Support
• Security Privacy
• Contributing
• FAQ
• License

---

🌟 Overview

Web application for tracking time across different cities, countdown timers, and stopwatch functionality. Built with React and runs entirely in the browser.

---

✨ Features

• Analog and digital clock display
• World clocks for 25+ cities
• Search and add cities dynamically
• Countdown timer with hours, minutes, seconds
• Stopwatch with millisecond precision
• Lap recording for stopwatch
• Alarm system with toggle
• Time statistics (Day of Year, Week Number, Unix Timestamp)
• Browser notifications for timer completion
• Responsive design
• All data stored locally

---

🖼 Demo & Screenshots

Live demo: [Your Demo URL]

---

🚀 Quick Start

Prerequisites

Node.js >= 16
npm >= 8

Installation

# Clone the repository
git clone https://github.com/BilgeGates/Clock.git

# Navigate to project directory
cd Clock

# Install dependencies
npm install

# Start development server
npm start

The application will automatically open at http://localhost:3000

Production Build

# Create optimized production build
npm run build

---

📁 Project Structure

clock/
│
├── 📂 public/
│   ├── index.html
│   └── favicon.ico
│
├── 📂 src/
│   │
│   ├── 📂 components/
│   │   │
│   │   ├── 📂 ui/              # Reusable UI components
│   │   │   ├── Button.jsx
│   │   │   ├── Card.jsx
│   │   │   ├── Input.jsx
│   │   │   ├── Switch.jsx
│   │   │   └── index.js
│   │   │
│   │   ├── 📂 stats/           # Statistics components
│   │   │   ├── StatCard.jsx
│   │   │   ├── StatsGrid.jsx
│   │   │   └── index.js
│   │   │
│   │   ├── 📂 clock/           # Clock components
│   │   │   ├── AnalogClock.jsx
│   │   │   ├── DigitalTime.jsx
│   │   │   ├── ClockMarkers.jsx
│   │   │   └── index.js
│   │   │
│   │   ├── 📂 world-clock/     # World clock features
│   │   │   ├── TimezoneCard.jsx
│   │   │   ├── TimezoneSearch.jsx
│   │   │   ├── TimezoneList.jsx
│   │   │   ├── WorldClockPanel.jsx
│   │   │   └── index.js
│   │   │
│   │   ├── 📂 stopwatch/       # Stopwatch features
│   │   │   ├── StopwatchDisplay.jsx
│   │   │   ├── StopwatchControls.jsx
│   │   │   ├── LapItem.jsx
│   │   │   ├── LapsList.jsx
│   │   │   ├── StopwatchPanel.jsx
│   │   │   └── index.js
│   │   │
│   │   ├── 📂 timer/           # Timer features
│   │   │   ├── TimerDisplay.jsx
│   │   │   ├── TimerInputs.jsx
│   │   │   ├── TimerControls.jsx
│   │   │   ├── TimerPanel.jsx
│   │   │   └── index.js
│   │   │
│   │   ├── 📂 alarm/           # Alarm features
│   │   │   ├── AlarmCard.jsx
│   │   │   ├── AlarmList.jsx
│   │   │   ├── AlarmPanel.jsx
│   │   │   └── index.js
│   │   │
│   │   └── 📂 layout/          # Layout components
│   │       ├── Header.jsx
│   │       └── index.js
│   │
│   ├── 📂 hooks/               # Custom React hooks
│   │   ├── useTime.js
│   │   ├── useStopwatch.js
│   │   ├── useTimer.js
│   │   ├── useTimezones.js
│   │   ├── useAlarms.js
│   │   └── index.js
│   │
│   ├── 📂 utils/               # Utility functions
│   │   ├── constants.js
│   │   ├── timeUtils.js
│   │   └── index.js
│   │
│   ├── App.jsx                 # Root component
│   ├── index.js                # Entry point
│   └── index.css               # Global styles
│
├── 📄 .gitignore
├── 📄 postcss.config.js
├── 📄 tailwind.config.js
├── 📄 package.json
├── 📄 package-lock.json
├── 📄 README.md
├── 📄 CONTRIBUTING.md
├── 📄 SECURITY.md
└── 📄 LICENSE

---

🛠️ Technology Stack

Core Technologies

React 18.2 UI Framework

JavaScript ES6+ Language

Tailwind CSS 3.3 Styling

Node.js 16+ Runtime

Additional Libraries

• Lucide React - Icon library
• React Hooks - State management (useState, useEffect, useMemo, useCallback)
• Web APIs - Intl.DateTimeFormat, Notification API, Web Audio API

---

🌐 Browser Support

Browser	Version	Status
Chrome	90+	✅ Tested
Firefox	88+	✅ Tested
Safari	14+	✅ Expected to work
Edge	90+	✅ Expected to work
Opera	76+	✅ Expected to work

Required Browser Features

• ES6+ JavaScript support
• CSS Grid & Flexbox
• Web Audio API
• Notification API (optional)
• Intl.DateTimeFormat for timezone support

---

🔐 Security & Privacy

Zero-backend architecture - all functionality runs in the browser.

🔒 Security Highlights

• ✅ No server-side data storage
• ✅ Client-side processing only
• ✅ No cookies, trackers, or fingerprinting
• ✅ No third-party analytics or telemetry
• ✅ No user data is collected, stored, or transmitted

🛡️ Data Safety

All settings, timers, and preferences are stored locally using localStorage.

For security concerns, see SECURITY.md.

---

🤝 Contributing

Contributions welcome.

Quick Contribution Guide

# 1. Fork the repository
# 2. Create your feature branch
git checkout -b feature/amazing-feature

# 3. Commit your changes
git commit -m 'feat: add amazing feature'

# 4. Push to the branch
git push origin feature/amazing-feature

# 5. Open a Pull Request

Please read CONTRIBUTING.md for detailed guidelines on:

• Code standards and best practices
• Pull request process
• Bug reporting
• Feature requests

Contributors

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 Khatai Huseynzada

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

👨‍💻 Author

Khatai Huseynzada

Front-End Web Developer | Open Source Contributor

---

🙏 Acknowledgments

React Team Framework

Tailwind Labs CSS Framework

Lucide Icons Icon Library

---

📧 Community & Support

Channel	Link
🐛 Bug Reports	GitHub Issues
💡 Feature Requests	GitHub Discussions
📧 Email	[email protected]

Responses on a best-effort basis

---

❓ FAQ

How do I report a bug?

1. Check if the issue already exists in GitHub Issues
2. If not, create a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs actual behavior
   • Screenshots (if applicable)
   • Browser and OS information

Can I use this commercially?

Yes! This project is MIT licensed, which means you can use it for commercial purposes.
Just include the license notice in your project.

How do I add more cities?

1. Open src/utils/constants.js
2. Add your city to the TIMEZONES array following the existing format
3. Submit a pull request with your changes

Why do I need to grant notification permissions?

Notification permissions are optional and only used for timer completion alerts.
The app works perfectly fine without them - you'll just see a standard browser alert instead.

How is my data stored?

All user data (timezones, timer settings, alarms) is stored locally in your browser using localStorage.
No data is sent to any server.

---

© 2026 Khatai Huseynzada. Licensed under MIT.