The HQ Project

A Modern Study Time Tracker Application

---

📖 About

The HQ Project is a desktop application designed to help students and professionals track their study sessions effectively. Built with a modern tech stack combining C++ for the backend and React for the frontend, it provides a seamless and performant user experience.

✨ Features

• ⏱️ Session Tracking: Start, stop, and manage your study sessions with ease
• 📊 Statistics & Analytics: Visualize your study patterns with interactive charts
• 💾 Local Data Storage: All data is stored locally using SQLite for privacy and reliability
• 🎨 Modern UI: Beautiful, responsive interface built with React and TailwindCSS
• 🖥️ Cross-Platform: Works on Windows, macOS, and Linux
• 📈 Progress Monitoring: Track your study habits over time with detailed statistics

🛠️ Tech Stack

Backend

• C++23: Modern C++ for high-performance backend
• Saucer: WebView integration for native desktop applications
• SQLite3: Lightweight, embedded database for local data storage
• CMake: Build system configuration

Frontend

• React 19: Latest React for building interactive UI
• TypeScript: Type-safe JavaScript development
• Vite: Lightning-fast build tool and dev server
• TailwindCSS: Utility-first CSS framework
• Hero UI: Modern React component library
• Recharts: Composable charting library for data visualization
• Framer Motion: Animation library for smooth UI transitions

📋 Prerequisites

Backend

• CMake 4.0 or higher
• C++23 compatible compiler (GCC 13+, Clang 16+, or MSVC 2022+)
• Git

Frontend

• Node.js 18+ or higher
• pnpm (recommended) or npm

Platform-Specific Requirements

Windows

• Microsoft Edge WebView2 Runtime (Download)

Linux

• WebKitGTK or Qt WebEngine (depending on Saucer configuration)

🚀 Getting Started

1. Clone the Repository

git clone https://github.com/NaviTheCoderboi/hq.git
cd hq-test

2. Install Frontend Dependencies

pnpm install
# or
npm install

3. Build Frontend

pnpm build
# or
npm run build

4. Build Backend

mkdir build
cd build
cmake ..
cmake --build .

5. Run the Application

On Linux/macOS:

./build/TheHQProject

On Windows:

.\build\TheHQProject.exe

🔧 Development

Frontend Development

Start the development server with hot reload:

pnpm dev
# or
npm run dev

Run linting:

pnpm lint
# or
npm run lint

Type checking:

pnpm typecheck
# or
npm run typecheck

Format code:

pnpm format
# or
npm run format

Backend Development

The backend uses CMake for building. After making changes to C++ code:

cd build
cmake --build .

📦 Building for Production

Create Installer/Package

Windows (NSIS Installer):

cd build
cpack -G NSIS

macOS (DMG):

cd build
cpack -G DragNDrop

Linux (TGZ):

cd build
cpack -G TGZ

📂 Project Structure

hq/
├── assets/              # Application assets (icons, images)
├── backend/             # C++ backend source files
│   ├── main.cpp        # Application entry point
│   ├── bridge.cpp      # Bridge between frontend and backend
│   ├── db.cpp          # Database operations
│   ├── fs.cpp          # File system utilities
│   └── ...
├── include/            # C++ header files
├── src/                # React frontend source
│   ├── components/     # React components
│   ├── utils/          # Utility functions and stores
│   └── App.tsx         # Main application component
├── external/           # External dependencies (SQLite)
├── cmake/              # CMake modules
├── CMakeLists.txt      # CMake configuration
├── package.json        # Node.js dependencies
└── vite.config.ts      # Vite configuration

🗄️ Database Schema

The application uses SQLite for local data storage with the following main entities:

• Sessions: Study session records with timestamps, duration, and metadata

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📄 License

This project is licensed under the terms specified in the LICENSE file.

👤 Author

NaviTheCoderboi

• GitHub: @NaviTheCoderboi

🙏 Acknowledgments

• Saucer - For the excellent webview integration
• Hero UI - For the beautiful React components
• All the amazing open-source libraries that made this project possible

📮 Support

If you encounter any issues or have questions, please open an issue on GitHub.

---

Made with ❤️ by NaviTheCoderboi