Pomodoro Timer

A modern, feature-rich Pomodoro timer application built with React, TypeScript, and Express. This application helps users stay focused and productive using the Pomodoro Technique, with beautiful UI components following atomic design principles.

Features

• Pomodoro Timer: Focus sessions (25 min) and break sessions (5 min) with customizable durations
• Session Tracking: Record and analyze your productivity sessions
• Progress Visualization: Beautiful progress rings and charts to track your focus time
• Sound Notifications: Audio alerts when sessions complete
• Responsive Design: Works seamlessly on desktop and mobile devices
• Dark/Light Theme: Toggle between themes for comfortable viewing
• Session History: View detailed analytics and progress over time
• Settings Customization: Adjust timer durations, sounds, and preferences
• Offline Support: Works even when disconnected from the internet

Architecture

This project follows Atomic Design principles and is built with a modern tech stack:

Frontend (Client)

• React 18 with TypeScript
• Atomic Design Components:
  • Atoms: Button, ProgressRing, SoundToggle
  • Molecules: DurationSelector, SuggestionChips, TimerControls
  • Organisms: HistoryChart, PomodoroTimer, Sidebar
  • Templates: MainLayout
• State Management: Zustand for local state
• Styling: Tailwind CSS with shadcn/ui components
• Routing: Wouter for lightweight routing
• Data Fetching: TanStack Query (React Query)

Backend (Server)

• Express.js with TypeScript
• Database: PostgreSQL with Drizzle ORM
• Authentication: Passport.js with local strategy
• Session Management: Express sessions with memory store
• Real-time: WebSocket support for live updates

Shared

• Schema Validation: Zod schemas for type safety
• Database Schema: Shared between client and server

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database
• npm or yarn

Installation

1. Clone the repository

   git clone https://github.com/CarGDev/pomodoro
   cd pomodoro
   

2. Install dependencies

   npm install
   

3. Set up environment variables Create a .env file in the root directory:

   DATABASE_URL=postgresql://username:password@localhost:5432/pomodoro
   SESSION_SECRET=your-session-secret
   PORT=5000
   

4. Set up the database

   npm run db:push
   

5. Start the development server

   npm run dev
   

The application will be available at http://localhost:5000

Build for Production

npm run build
npm start

Project Structure

pomodoro/
├── client/                 # Frontend React application
│   ├── src/
│   │   ├── components/     # Atomic design components
│   │   │   ├── atoms/      # Basic building blocks
│   │   │   ├── molecules/  # Simple component combinations
│   │   │   ├── organisms/  # Complex UI sections
│   │   │   ├── templates/  # Page layouts
│   │   │   └── ui/        # shadcn/ui components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── lib/           # Utilities and configurations
│   │   ├── pages/         # Application pages
│   │   └── main.tsx       # Application entry point
├── server/                 # Backend Express server
│   ├── index.ts           # Server entry point
│   ├── routes.ts          # API route definitions
│   └── storage.ts         # Database operations
├── shared/                 # Shared code between client/server
│   └── schema.ts          # Database schemas and types
├── drizzle.config.ts       # Database configuration
└── package.json            # Project dependencies

Key Components

PomodoroTimer

The main timer component that manages focus and break sessions, tracks progress, and handles session completion.

ProgressRing

A beautiful circular progress indicator showing time remaining in the current session.

HistoryChart

Visualizes productivity data over time using Recharts, helping users track their progress.

DurationSelector

Allows users to customize focus and break session durations according to their preferences.

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run check - TypeScript type checking
• npm run db:push - Push database schema changes

UI Components

This project uses shadcn/ui components built on top of Radix UI primitives, providing:

• Accessible components following WAI-ARIA guidelines
• Consistent design system
• Dark/light theme support
• Responsive design patterns
• Beautiful animations with Framer Motion

Data Flow

1. Timer State: Managed locally with Zustand for immediate responsiveness
2. Session Recording: Sessions are stored locally first, then synced to the server
3. Analytics: Historical data is fetched from the server and cached with React Query
4. Real-time Updates: WebSocket connections provide live updates when available

API Endpoints

• POST /api/sessions - Create new session
• GET /api/sessions - Retrieve session history
• GET /api/stats/summary - Get productivity statistics
• GET /api/suggestions - Get productivity suggestions

Security Features

• Session-based authentication
• Input validation with Zod schemas
• SQL injection protection with Drizzle ORM
• Secure session management

Development

Code Style

• TypeScript strict mode enabled
• ESLint and Prettier for code formatting
• Atomic design principles for component organization
• Consistent naming conventions

Testing

• Component testing with React Testing Library
• API testing with supertest
• End-to-end testing with Playwright

Mobile Support

• Responsive design that works on all screen sizes
• Touch-friendly interface elements
• Progressive Web App (PWA) capabilities
• Offline functionality with service workers

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Acknowledgments

• shadcn/ui for beautiful UI components
• Drizzle ORM for type-safe database operations
• Tailwind CSS for utility-first styling
• Framer Motion for smooth animations

---

Happy focusing!