pomodoro/README.md

# 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**
   ```bash
   git clone https://github.com/CarGDev/pomodoro
   cd pomodoro
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Set up environment variables**
   Create a `.env` file in the root directory:
   ```env
   DATABASE_URL=postgresql://username:password@localhost:5432/pomodoro
   SESSION_SECRET=your-session-secret
   PORT=5000
   ```

4. **Set up the database**
   ```bash
   npm run db:push
   ```

5. **Start the development server**
   ```bash
   npm run dev
   ```

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

### Build for Production

```bash
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](LICENSE) file for details.

## Acknowledgments

- [shadcn/ui](https://ui.shadcn.com/) for beautiful UI components
- [Drizzle ORM](https://orm.drizzle.team/) for type-safe database operations
- [Tailwind CSS](https://tailwindcss.com/) for utility-first styling
- [Framer Motion](https://www.framer.com/motion/) for smooth animations

---

**Happy focusing!**