LeanTime

LeanTime is a lightweight and minimalistic countdown timer web app. Designed for simplicity and efficiency, it features real-time synchronization using Socket.IO and provides an intuitive user interface for tasks that require precise time management.

---

📖 Documentation

LeanTime’s documentation is structured to help you quickly find what you need, whether you’re a user, developer, or contributor:

• Documentation Overview — The canonical map of all project docs, update protocols, and contribution guidelines.
• Client AGENTS.md — Frontend architecture, UI patterns, and internal conventions.
• Server AGENTS.md — Backend (server/API/timer) architecture, contracts, and best practices.
• Code of Conduct — Collaboration norms and community rules.
• License — MIT License.

👉 If you update features, protocols, or cross the client/server boundary, always reference the documentation overview and relevant AGENTS.md for required doc changes.

---

Table of Contents

• Features
• Tech Stack
• Documentation
• Getting Started
  • Prerequisites
  • Installation
• Development Workflow
• Testing
• Deployment
• Contributing
• License

---

Features

• Real-Time Timer: Provides a synchronized timer state across multiple clients.
• Simple Interface: Easy-to-use UI for starting, pausing, resetting, and customizing the timer.
• Customizable:
  • Modify the timer’s initial value with the "Apply" function.
  • Sleek alarm sound on completion.
• Fast Feedback Loop: Instant updates powered by Socket.IO.

---

Tech Stack

• Frontend: Vite + TypeScript
  • No frameworks for maximum simplicity.
• Backend: Express + Socket.IO (TypeScript-based)
• Testing: Vitest, with focused unit tests for stability and accuracy.
• Build: Vite for development and production builds.

---

Getting Started

Prerequisites

Ensure you have the following installed:

• Node.js: Version 16 or higher
• npm: Version 7 or higher

Installation

1. Clone this repository:

   git clone https://github.com/seymourpoler/LeanTime.git

2. Navigate to the project directory:

   cd LeanTime

3. Install dependencies:

   npm install

---

Development Workflow

• Start the development server:

  npm run dev

  This will start the Express server and Vite middleware with hot-reloading.

• Run tests:

  npm run test

  This will execute all unit tests using Vitest.

• Build for production:

  npm run build

  This will bundle and optimize the codebase into the dist/ directory.

• Start the production server:

  npm run start

---

Testing

We use Vitest for testing the project’s critical functionalities. To execute tests, run:

npm run test

Tests include:

• Unit tests for timer logic in the backend (DateTimeService)
• Presenter logic on the client side

---

Deployment

LeanTime is currently deployed on Render. You can access the live instance using the link.

---

Contributing

Contributions are welcome! Please read the Code of Conduct and review the Documentation Overview for workflow, checklist, and file update requirements.

To get started:

• Fork this repository.
• Create a new branch.
• Submit a pull request with a clear explanation of changes.

If you change protocols or cross client/server boundaries, update AGENTS.md and the documentation overview accordingly and ensure all affected tests pass.

---

License

This project is licensed under the MIT License.

---

Enjoy using LeanTime! Feedback and suggestions are always appreciated.