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

Clone the repository

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

Install dependencies
```
npm install
```

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

Set up the database
```
npm run db:push
```
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

Timer State: Managed locally with Zustand for immediate responsiveness
Session Recording: Sessions are stored locally first, then synced to the server
Analytics: Historical data is fetched from the server and cached with React Query
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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!