mirror of
https://github.com/CarGDev/pomodoro.git
synced 2025-09-18 17:28:27 +00:00
3b577288da
- Upgrade React to v19.1.1 and update all related packages - Add comprehensive keyboard shortcuts (Space, R, S, Ctrl+D) with visual indicators - Implement Zustand global state management for shortcuts and app state - Fix .env file loading with dotenv package and proper Vite configuration - Add text wrapping to all card components to prevent overflow - Improve theme toggle visibility and styling in sidebar - Update button layouts to use flex-direction: row - Add hover effects and consistent styling across components - Fix infinite loop issues in keyboard shortcuts hook - Update Vite config to properly handle .env files and source directories - Add proper TypeScript configuration for React 19 JSX transform
213 lines
6.8 KiB
Markdown
213 lines
6.8 KiB
Markdown
# 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!**
|
|
|