{"id":29492628,"url":"https://github.com/popand/timerfy","last_synced_at":"2026-04-09T08:10:44.413Z","repository":{"id":303881365,"uuid":"1017006160","full_name":"popand/Timerfy","owner":"popand","description":"Real-time distributed timer system supporting 50+ concurrent rooms with sub-100ms synchronization. Spring Boot + Redis + WebSocket.","archived":false,"fork":false,"pushed_at":"2025-07-10T03:38:27.000Z","size":81,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-10T08:39:39.580Z","etag":null,"topics":["countdown","distributed-systems","events","open-source","presentations","react","real-time","redis","spring-boot","timer","websocket"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/popand.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-09T21:58:39.000Z","updated_at":"2025-07-10T03:38:30.000Z","dependencies_parsed_at":"2025-07-10T08:39:42.611Z","dependency_job_id":"30da951e-c940-40d2-8607-9510048ad3bd","html_url":"https://github.com/popand/Timerfy","commit_stats":null,"previous_names":["popand/timerfy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/popand/Timerfy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popand%2FTimerfy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popand%2FTimerfy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popand%2FTimerfy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popand%2FTimerfy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/popand","download_url":"https://codeload.github.com/popand/Timerfy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popand%2FTimerfy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265443228,"owners_count":23766369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["countdown","distributed-systems","events","open-source","presentations","react","real-time","redis","spring-boot","timer","websocket"],"created_at":"2025-07-15T15:28:02.078Z","updated_at":"2026-04-09T08:10:44.382Z","avatar_url":"https://github.com/popand.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Timerfy - Distributed Timer System\n\n\u003cdiv align=\"center\"\u003e\n\n![Timerfy Logo](https://img.shields.io/badge/Timerfy-Distributed%20Timer%20System-blue?style=for-the-badge)\n\n[![Java](https://img.shields.io/badge/Java-17+-orange?style=flat-square\u0026logo=openjdk)](https://openjdk.org/)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2+-green?style=flat-square\u0026logo=spring)](https://spring.io/projects/spring-boot)\n[![Redis](https://img.shields.io/badge/Redis-7.0+-red?style=flat-square\u0026logo=redis)](https://redis.io/)\n[![React](https://img.shields.io/badge/React-18+-blue?style=flat-square\u0026logo=react)](https://reactjs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square\u0026logo=typescript)](https://www.typescriptlang.org/)\n\n**A free, open-source distributed countdown timer system with real-time synchronization**\n\n[Demo](https://timerfy.io) • [Documentation](#api-documentation) • [Contributing](#contributing) • [Roadmap](#development-roadmap)\n\n\u003c/div\u003e\n\n## 🎯 Project Overview\n\nTimerfy is a web-based distributed countdown timer system designed as a free, open-source alternative to commercial timer solutions. Built with a modern decoupled architecture, it provides real-time timer synchronization across multiple devices through RESTful APIs and WebSocket connections.\n\n### ✨ Key Features\n\n- **🚀 Real-time Synchronization**: Sub-100ms latency across all connected devices\n- **🏗️ Decoupled Architecture**: Independent client and server applications\n- **📱 Multi-device Support**: Works seamlessly across desktop, tablet, and mobile ([See Screenshots](#-client-applications))\n- **⚡ High Performance**: Supports 50+ concurrent rooms with 20+ viewers each\n- **🔄 Auto-cleanup**: Rooms automatically expire after 24 hours\n- **🎨 Customizable**: Flexible timer configurations and message system\n- **🔌 API-First**: Complete functionality accessible via REST APIs\n- **📡 WebSocket Events**: Live updates without polling\n- **👥 Dual Interface**: Separate controller and viewer experiences optimized for each use case\n\n### 🎪 Use Cases\n\n- **Conference Presentations**: Professional speaker timing\n- **Educational Settings**: Classroom activities and exams\n- **Corporate Events**: Meeting time management\n- **Sports Events**: Competition timing\n- **Broadcasting**: Live show timing systems\n- **Workshops**: Training session management\n\n## 🏗️ Architecture Overview\n\nTimerfy follows a **separation of concerns** principle with completely independent applications:\n\n```\ntimerfy-system/\n├── timerfy-server/            # Spring Boot API Server\n│   ├── src/main/java/\n│   │   └── com/timerfy/\n│   │       ├── controller/    # REST Controllers\n│   │       ├── service/       # Business Logic\n│   │       ├── model/         # Data Models\n│   │       ├── dto/           # Data Transfer Objects\n│   │       ├── config/        # Configuration\n│   │       └── websocket/     # WebSocket Handlers\n│   └── pom.xml\n├── timerfy-client/            # React Application (Coming Soon)\n│   ├── src/\n│   │   ├── components/\n│   │   ├── services/\n│   │   └── types/\n│   └── package.json\n└── shared-types/              # Shared Type Definitions (Coming Soon)\n```\n\n### 🛠️ Technology Stack\n\n#### Backend (timerfy-server) ✅ **IMPLEMENTED**\n- **Runtime**: Java 17+ with Spring Boot 3.2+\n- **Framework**: Spring MVC for REST APIs\n- **WebSockets**: Spring WebSocket with STOMP protocol\n- **Database**: Redis for state management and pub/sub\n- **Validation**: Bean Validation (JSR-303)\n- **Documentation**: SpringDoc OpenAPI (Swagger)\n- **Build**: Maven\n- **Monitoring**: Spring Boot Actuator\n\n#### Frontend (timerfy-client) 🚧 **PLANNED**\n- **Framework**: React 18 with TypeScript\n- **Styling**: Tailwind CSS\n- **HTTP Client**: Axios\n- **WebSocket**: STOMP.js\n- **State Management**: React Query + Context API\n- **Build**: Vite\n\n#### Infrastructure\n- **Containerization**: Docker \u0026 Docker Compose\n- **Caching**: Redis\n- **Monitoring**: Prometheus + Grafana\n- **CI/CD**: GitHub Actions\n\n## 📊 Current Implementation Status\n\n### ✅ **COMPLETED MILESTONES** (6/7 Server Milestones Done)\n\n#### **Milestone 1: Server Foundation** ✅ **COMPLETED**\n- [x] Spring Boot 3.2.0 setup with Java 17+\n- [x] Maven configuration with all required dependencies\n- [x] Redis connection configuration using Spring Data Redis\n- [x] CORS settings for cross-origin requests\n- [x] Application.yml with environment configurations\n- [x] Complete project structure and Spring Boot Actuator\n\n#### **Milestone 2: Data Models \u0026 Core Services** ✅ **COMPLETED**\n- [x] **Data Models**: Room, Timer, Message entities with validation\n- [x] **Enums**: TimerState, TimerType, MessagePriority, UserRole\n- [x] **DTOs**: Complete request/response objects with Bean Validation\n- [x] **RoomService**: Full CRUD operations with Redis persistence\n- [x] **TimerService**: Thread-safe timer operations with event publishing\n- [x] **Core Utilities**: Room ID generation, scheduled cleanup services\n\n#### **Milestone 3: REST API Implementation** ✅ **COMPLETED**\n- [x] **Controllers**: RoomController, TimerController, MessageController\n- [x] **API Endpoints**: All 13 REST endpoints implemented\n- [x] **Global Exception Handling**: 7 custom exceptions with @ControllerAdvice\n- [x] **Rate Limiting**: AspectJ-based rate limiting for API protection\n- [x] **OpenAPI Documentation**: Complete Swagger/SpringDoc integration\n\n#### **Milestone 4: WebSocket Implementation** ✅ **COMPLETED**\n- [x] **WebSocket Configuration**: STOMP protocol with heartbeat mechanism\n- [x] **Real-time Timer Events**: Broadcasting for all timer state changes\n- [x] **Message Events**: Real-time message creation, updates, and visibility\n- [x] **Connection Management**: User role management and room subscriptions\n- [x] **Event Rate Limiting**: Anti-flooding protection (10 events/second)\n\n#### **Milestone 5: Message System** ✅ **COMPLETED**\n- [x] **Message Management**: Complete CRUD operations via RoomService\n- [x] **Message Priority Handling**: HIGH, MEDIUM, LOW, CRITICAL priorities\n- [x] **Auto-hide Functionality**: Scheduled tasks for message cleanup\n- [x] **WebSocket Integration**: Real-time message broadcasting\n- [x] **Room Settings**: Comprehensive room configuration updates\n\n#### **Milestone 6: Testing and Quality Assurance** ✅ **COMPLETED**\n- [x] **Unit Tests**: 70+ comprehensive tests for services and controllers\n- [x] **MockMvc Testing**: Complete HTTP endpoint testing\n- [x] **Test Utilities**: Redis TestContainers and test data factories\n- [x] **Validation Testing**: Bean Validation coverage for DTOs and entities\n- [x] **Error Scenario Testing**: Edge cases and failure condition coverage\n\n### 🚧 **REMAINING SERVER MILESTONE**\n\n#### **Milestone 7: Performance and Deployment** \n- ⏳ **Performance Optimization**: Timer tick optimization, Redis connection pooling\n- ⏳ **Caching Strategy**: Spring Boot @Cacheable annotations\n- ⏳ **Error Handling Enhancement**: Network disconnection retry logic  \n- ⏳ **Deployment Configuration**: Dockerfile, CI/CD pipeline, SSL certificates\n- ⏳ **Monitoring Setup**: Spring Boot Actuator metrics and Prometheus integration\n\n### 📊 **Implementation Statistics**\n\n- **Total Java Files**: 39 classes\n- **Test Files**: 8 comprehensive test classes  \n- **API Endpoints**: 13 REST endpoints + WebSocket support\n- **Lines of Code**: ~3,500+ lines (including tests)\n- **Test Coverage**: 70+ unit and integration tests\n- **Dependencies**: 15+ Spring Boot starters and libraries\n\n### 🎯 **Server Production Ready**\n\nThe **Timerfy Server is production-ready** for core functionality:\n- ✅ Handles multiple concurrent rooms and users\n- ✅ Real-time timer synchronization across clients\n- ✅ Persistent data storage with Redis\n- ✅ Comprehensive error handling and validation\n- ✅ Rate limiting and security measures\n- ✅ Health monitoring and metrics endpoints\n- ✅ Extensive test coverage ensuring reliability\n\n### 🗓️ **Upcoming Client Milestones**\n- **Phase 3**: React Client Foundation (Coming Soon)\n- **Phase 4**: Client UI Implementation\n- **Phase 5**: Polish and Deployment\n\n## 📱 Client Applications\n\nTimerfy features responsive React applications optimized for different devices and use cases. Here's what's available:\n\n\n### 🎨 **Design Features Across Devices**\n\n### 📸 **Application Screenshots**\n\nHere are the actual screenshots of the Timerfy client applications across different devices:\n\n#### **🖥️ Desktop Web Application**\n![Desktop Web Application](screenshots/webapp.png)\n*Full-featured controller dashboard with timer management, message system, and real-time synchronization*\n\n#### **📱 iPad Application** \n![iPad Application](screenshots/ipad.png)\n*Responsive tablet interface optimized for both landscape and portrait orientations*\n\n#### **📱 iPhone Application**\n![iPhone Application](screenshots/phone.png)\n*Mobile-optimized interface with compact controls and immersive viewer experience*\n\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Java 17+** ([Download](https://adoptium.net/))\n- **Maven 3.6+** ([Download](https://maven.apache.org/download.cgi))\n- **Redis 7.0+** ([Download](https://redis.io/download) or use Docker)\n\n### 🏃‍♂️ Running the Server\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/popand/Timerfy.git\n   cd Timerfy\n   ```\n\n2. **Start Redis** (using Docker)\n   ```bash\n   docker run -d -p 6379:6379 --name timerfy-redis redis:7-alpine\n   ```\n\n3. **Build and run the server**\n   ```bash\n   cd timerfy-server\n   mvn clean compile\n   mvn spring-boot:run\n   ```\n\n4. **Verify the server is running**\n   ```bash\n   curl http://localhost:3001/actuator/health\n   ```\n\n### 🐳 Docker Setup\n\n```bash\n# Start Redis and the application\ndocker-compose up -d\n\n# Check logs\ndocker-compose logs -f\n```\n\n### 🔧 Configuration\n\nThe server can be configured via `application.yml`:\n\n```yaml\nserver:\n  port: 3001\n\nspring:\n  data:\n    redis:\n      host: localhost\n      port: 6379\n      timeout: 2000ms\n\ntimerfy:\n  room:\n    expiration: 86400  # 24 hours in seconds\n    max-timers: 10\n    max-users: 50\n    cleanup-interval: 3600  # 1 hour in seconds\n```\n\n## 📚 API Documentation\n\n### Base URL\n- **Development**: `http://localhost:3001`\n- **Production**: `https://api.timerfy.io` (Coming Soon)\n\n### Authentication\n- **No authentication required** for MVP\n- **Room-based access control** via room IDs\n- **Role-based permissions** (controller vs viewer)\n\n### Core Endpoints\n\n#### Room Management\n```http\nPOST   /api/v1/rooms                     # Create new room\nGET    /api/v1/rooms/{roomId}           # Get room details\nDELETE /api/v1/rooms/{roomId}           # Delete room\nGET    /api/v1/rooms/{roomId}/status    # Get room status\n```\n\n#### Timer Control\n```http\nPOST   /api/v1/rooms/{roomId}/timers                    # Create timer\nPUT    /api/v1/rooms/{roomId}/timers/{timerId}         # Update timer\nDELETE /api/v1/rooms/{roomId}/timers/{timerId}         # Delete timer\nPOST   /api/v1/rooms/{roomId}/timers/{timerId}/start   # Start timer\nPOST   /api/v1/rooms/{roomId}/timers/{timerId}/stop    # Stop timer\nPOST   /api/v1/rooms/{roomId}/timers/{timerId}/pause   # Pause timer\nPOST   /api/v1/rooms/{roomId}/timers/{timerId}/reset   # Reset timer\nPOST   /api/v1/rooms/{roomId}/timers/{timerId}/adjust  # Adjust timer time\n```\n\n#### Message Management\n```http\nPOST   /api/v1/rooms/{roomId}/messages                 # Create message\nPUT    /api/v1/rooms/{roomId}/messages/{messageId}     # Update message\nDELETE /api/v1/rooms/{roomId}/messages/{messageId}     # Delete message\nPOST   /api/v1/rooms/{roomId}/messages/{messageId}/show # Show message\nPOST   /api/v1/rooms/{roomId}/messages/{messageId}/hide # Hide message\nPUT    /api/v1/rooms/{roomId}/settings                 # Update room settings\n```\n\n#### WebSocket Connection\n```javascript\n// STOMP connection to room updates\nconst client = Stomp.over(new SockJS('/ws'));\nclient.connect({}, () =\u003e {\n  client.subscribe('/topic/room/{roomId}', (message) =\u003e {\n    // Handle real-time updates\n  });\n});\n```\n\n### 📖 Interactive API Documentation\n\nOnce the server is running, visit:\n- **Swagger UI**: `http://localhost:3001/swagger-ui.html`\n- **OpenAPI Spec**: `http://localhost:3001/v3/api-docs`\n\n## 🧪 Testing\n\n### Running Tests\n```bash\ncd timerfy-server\n\n# Run unit tests\nmvn test\n\n# Run integration tests\nmvn verify\n\n# Generate test coverage report\nmvn jacoco:report\n```\n\n### Load Testing\n```bash\n# Test concurrent rooms (requires JMeter)\njmeter -n -t load-tests/room-load-test.jmx\n```\n\n### Performance Targets\n- ⚡ **Timer sync latency**: \u003c100ms\n- 🏠 **Room creation**: \u003c2 seconds\n- 👥 **Concurrent rooms**: 50+\n- 📺 **Viewers per room**: 20+\n- ⏱️ **Uptime**: 99.9%\n\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Setup\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n### Code Style\n- **Java**: Follow [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)\n- **TypeScript**: Use Prettier with ESLint\n- **Commits**: Follow [Conventional Commits](https://conventionalcommits.org/)\n\n### Issues and Bug Reports\nPlease use our [issue tracker](https://github.com/popand/Timerfy/issues) to report bugs or request features.\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [Spring Boot](https://spring.io/projects/spring-boot) and [React](https://reactjs.org/)\n- Redis for fast, reliable state management\n- The open-source community for continuous inspiration\n\n## 📞 Support\n\n- 📧 **Email**: support@timerfy.io\n- 🐛 **Issues**: [GitHub Issues](https://github.com/popand/Timerfy/issues)\n- 📖 **Documentation**: [docs.timerfy.io](https://docs.timerfy.io)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by the Timerfy Team**\n\n[⭐ Star this repo](https://github.com/popand/Timerfy) • [🐛 Report bug](https://github.com/popand/Timerfy/issues) • [✨ Request feature](https://github.com/popand/Timerfy/issues)\n\n\u003c/div\u003e ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpopand%2Ftimerfy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpopand%2Ftimerfy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpopand%2Ftimerfy/lists"}