TypeFlow - Typing Speed Improver

TypeFlow is a modern, privacy-focused typing speed trainer built with React. It tracks your progress locally using IndexedDB, helps you identify weak keys, and offers structured lessons to improve your touch typing.

✨ Features

🎯 Multiple Training Modes

• Practice Mode: Type against difficulty-based text sets (Basic, Intermediate, Advanced)
• Structured Lessons: Progressive lessons starting from home row basics to full keyboard mastery
• Custom Text Support: Paste your own text (articles, code, etc.) to practice specific content
• Sudden Death Mode: One mistake ends the game - perfect for accuracy training

📊 Advanced Analytics

• Real-time Metrics: Live WPM and accuracy tracking
• Persistent History: All data stored permanently in IndexedDB
• Daily Streaks: Track your consistency with streak counters
• Per-Lesson Progress: Attempts, best WPM, and average accuracy for each lesson
• Key-Level Analytics: Visual breakdown showing accuracy for every key
• Smart Key Drills: Automatically identifies your weakest keys and generates custom practice

🎮 Interactive Features

• Ghost Replay: Race against your personal best performance
• Progress Tracking: Day-to-day progress with local timezone support
• Reset Functionality: Clear all stats to start fresh anytime

🔒 Privacy First

All data is stored locally in your browser using IndexedDB. No signup required, no data sent to servers, complete privacy.

🛠️ Technology Stack

• Framework: React 18
• Build Tool: Vite
• Styling: CSS Modules with glassmorphism aesthetic
• State Management: React Hooks (useState, useEffect, useCallback)
• Storage: IndexedDB for permanent local storage
• Date Handling: Local timezone support with proper date grouping

🏁 Getting Started

Prerequisites

• Node.js (v20.19.0 or higher)
• npm (v10.0.0 or higher)

Installation

1. Clone the repository:

   git clone https://github.com/erdcpatel/type-flow.git
   cd type-flow

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

4. Open your browser: Navigate to http://localhost:5173

Building for Production

npm run build

The production-ready files will be in the dist/ directory.

🧪 Testing

TypeFlow uses Vitest for testing with jsdom environment and fake-indexeddb for IndexedDB polyfills.

Running Tests

# Run tests in watch mode
npm run test

# Run tests once (CI mode)
npm run test:ci

# Run linter
npm run lint

Test Setup

Tests use fake-indexeddb for IndexedDB polyfills. Setup file: src/test/setupTests.cjs

🌐 Browser Compatibility

TypeFlow works on all modern browsers:

• ✅ Chrome 90+ (recommended)
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+

Requirements:

• ES6+ JavaScript support
• IndexedDB support
• CSS Grid and Flexbox

🚀 Deployment

GitHub Pages (Current)

npm run deploy

This builds and deploys to GitHub Pages using gh-pages.

Other Platforms

Vercel:

• Connect your GitHub repository
• Vercel will auto-detect Vite and deploy

Netlify:

• Drag and drop the dist/ folder, or
• Connect repository with build command: npm run build

Cloudflare Pages:

• Connect repository
• Build command: npm run build
• Output directory: dist

Build Configuration:

• Build command: npm run build
• Output directory: dist
• Node version: 20.19.0+

⚙️ Environment Variables

TypeFlow requires no environment variables. The application is 100% client-side with no server dependencies or API keys needed.

📁 Project Structure

type-flow/
├── src/
│   ├── components/          # React components
│   │   ├── TypingArea.jsx   # Main typing interface
│   │   ├── StatsModal.jsx   # Statistics and analytics
│   │   ├── ResultCard.jsx   # Test completion results
│   │   └── LessonSelector.jsx
│   ├── hooks/               # Custom React hooks
│   │   └── useTypingGame.js # Core typing game logic
│   ├── utils/               # Utility functions
│   │   ├── db.js           # IndexedDB wrapper
│   │   ├── storage.js      # Storage operations
│   │   ├── generator.js    # Text generation
│   │   ├── lessons.js      # Lesson definitions
│   │   └── texts.js        # Practice texts
│   ├── App.jsx             # Main application
│   └── main.jsx            # Entry point
├── public/                  # Static assets
├── docs/                    # Additional documentation
└── package.json

💾 Data Storage

TypeFlow uses IndexedDB for permanent local storage:

• Database: TypeFlowDB
• Object Stores:
  • history - All typing test results with timestamps
  • replays - Best performance replays for ghost mode

Data Persistence

• Data survives browser restarts and cache cleanup
• Automatic migration from old localStorage data
• Local timezone support for accurate date tracking
• Reset functionality available in stats modal

🎓 How to Use

1. Choose a Mode: Practice, Lesson, or Custom
2. Start Typing: Click the input area and begin
3. View Stats: Click "view detailed stats" to see your progress
4. Track Progress: Check your daily streak and improvement over time
5. Practice Weak Keys: Use the smart drill feature to target problem areas

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md for details on:

• Code style guidelines
• Development workflow
• How to submit pull requests
• Project architecture

📚 Additional Documentation

• ARCHITECTURE.md - System design and architecture
• AI_AGENT_GUIDE.md - Guide for AI agents working on this project
• CONTRIBUTING.md - Contribution guidelines

🐛 Troubleshooting

Data Not Persisting

• Ensure your browser supports IndexedDB
• Check browser console for errors
• Try resetting stats and starting fresh

Performance Issues

• Clear browser cache
• Disable browser extensions
• Check for console errors

📄 License

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

🙏 Acknowledgments

Built with modern web technologies and best practices for an optimal typing training experience.