Timezone App

A production-ready application that automatically detects and displays timezone information based on IP geolocation.

Overview

Built entirely with Claude Code as a PoC for AI-assisted software development. Features comprehensive testing (96.68% coverage), intelligent caching, health monitoring, and security hardening—demonstrating that AI agents can build production-ready applications following industry best practices.

Features

• Automatic timezone detection via IP geolocation
• Intelligent caching (24h TTL, 80-90% hit rate) reduces API calls
• Health monitoring with liveness/readiness probes
• Security hardened (rate limiting, CORS, Helmet.js)
• 96.68% test coverage with 213 passing tests
• Production-ready with Docker, CI/CD, graceful shutdown

Quick Start

git clone https://github.com/olaoluthomas/timezone-app.git
cd timezone-app
npm install
npm start
# Open http://localhost:3000

Installation

Prerequisites: Node.js 18+ or 20+

git clone https://github.com/olaoluthomas/timezone-app.git
cd timezone-app
npm install
cp .env.example .env  # Optional

Usage

npm run dev              # Development with hot-reload
npm start                # Production
npm test                 # Run tests
npm run lint             # Check code quality

API Endpoints

• GET /api/timezone - Returns timezone and location data for requesting IP
• GET /health - Liveness probe (basic health status)
• GET /health/ready - Readiness probe (comprehensive checks)

See API Documentation for detailed request/response formats.

Configuration

Create .env file:

PORT=3000
NODE_ENV=production

See Configuration Guide for advanced options.

Technology Stack

Core: Node.js, Express.js, Axios, node-cache, ipapi.co API
Testing: Jest, Supertest, Nock
Quality: ESLint, Prettier, Husky

Built with AI:

• Claude Code (Anthropic CLI) with Sonnet 4.5
• Claude Code Router (QWEN, Llama, local models)
• MCP Servers (Augment Code, GitHub)

Documentation

Guides

• API Documentation
• Deployment Guide
• Configuration
• Troubleshooting
• Testing

Project Info

• Architecture
• Performance Metrics
• Roadmap

Contributing

Contributions welcome! Follow the mandatory issue-first workflow:

# 1. Create issue — Preferred: GitHub MCP issue_write | Fallback: gh issue create
# 2. Branch, commit, push
git checkout -b type/issue-N-description
git commit -m "type: description"
git push -u origin type/issue-N-description
# 3. Create PR — Preferred: GitHub MCP create_pull_request | Fallback: npm run create-pr

See CONTRIBUTING.md for full details.

License

MIT License - see LICENSE file.

Support

For issues or questions:

• Open an issue on GitHub
• Include error messages, logs, and Node.js version
• Check Troubleshooting Guide

---

Made with ❤️ for developers who need timezone information

Test documentation change