Pomodoro Castle

Pomodoro Castle is a React Native application which gamifies the Pomodoro study technique, transforming it from a simple time management method into an epic, adrenaline-fueled adventure. While most Pomodoro apps offer zen-like, minimalist experiences, Pomodoro Castle takes a boldly different approach—recognizing that studying is a hardcore endeavor worthy of an equally intense companion app.

About Pomodoro Castle

Vision

Our vision is to make study sessions not just productive, but genuinely exciting. We believe that gamification can transform the often tedious experience of focused study into something students look forward to.

Key Features

• Castle Building: Build and upgrade your fortress with each completed Pomodoro session
• Epic Battles: Defend your castle from monsters and invaders during break periods
• Progression System: Level up your character and unlock new abilities as you complete more study sessions
• Achievement System: Earn badges and rewards for consistency and milestone achievements
• Social Competition: Compare progress with friends and compete on leaderboards
• Customization: Personalize your castle, character, and experience

How It Works

1. Study Phase: Set your Pomodoro timer (typically 25 minutes) and focus on your work while your castle generates resources
2. Break Phase: During short breaks, engage in quick strategic gameplay to defend your castle
3. Long Break: After completing a set of Pomodoros, enjoy more extensive gameplay as a reward

By transforming the Pomodoro technique into an immersive game, Pomodoro Castle helps users maintain focus during study sessions while providing motivating rewards that make the entire process more engaging and sustainable.

Badges

Run Locally

Prerequisites

• Node.js (v23 or later)
• npm or yarn
• Expo CLI
• Android Studio (for Android development)

Installation

Clone the project

  git clone https://github.com/Blodroed/PomodoroCastle.git

Go to the project directory

  cd PomodoroCastle

Install dependencies

  npm install

Running the App

Start the Expo development server

  npx expo start

This will open the Expo developer tools in your browser, where you can choose how to run the app.

Android Studio Setup

1. Install Android Studio
2. Open Android Studio and go to Tools > Device Manager
3. Click "Create Device" to set up a new virtual device with these specifications:
   • Category: Phone
   • Device: Medium Phone (e.g., Pixel 6)
   • System Image: API 35 (Android 15.0)
   • Name: PomodoroCastle_Emulator (or any name you prefer)
4. Click "Finish" to create the virtual device
5. Start the emulator by clicking the play button in the Device Manager
6. In your Expo terminal, press a to open the app in the Android emulator

Alternative Running Options

• Run on physical device: Install the Expo Go app and scan the QR code
• Run in web browser: Press w in the Expo terminal

Documentation

The project documentation is built with MkDocs, a fast and simple static site generator.

Viewing Documentation

You have two options to access the documentation:

Option 1: Build and Browse Documentation Locally

Since the site directory is gitignored, you'll need to build the documentation first:

1. Install documentation dependencies:

pip install -r requirements.txt

2. Build the documentation:

mkdocs build

3. Open the generated site/index.html file in any web browser

Option 2: Run Documentation Server Locally

To run the documentation server locally and make changes:

1. Install documentation dependencies:

pip install -r requirements.txt

2. Start the documentation server:

mkdocs serve

3. Open your browser and go to http://127.0.0.1:8000

Updating Documentation

1. Edit or add markdown files in the docs directory
2. If adding new pages, update the navigation in mkdocs.yml
3. Preview changes with mkdocs serve
4. Build the static site with:

mkdocs build

License

This project is licensed under a proprietary license with Common Clause restrictions that prohibit both commercial use and redistribution of this software.

Under this license, you can:

• Use the code for personal use only
• View and modify the source code for personal use only

You cannot:

• Distribute or share the software with others
• Sell the software
• Use the software to provide a commercial service
• Create derivative applications without explicit written permission

We've chosen this license to protect our investment and ability to monetize our application.

For full license terms, please see the LICENSE file.

Tech Stack

Client:

Server:

(planned)

Security

This project contains security-critical components for the anti-cheat system. We've implemented:

• Chain Hashing: Cryptographically secure session verification using HMAC-SHA256
• Security Verification: Scripts to ensure consistent implementation between client and server

Security Verification

Run these commands from the root directory to check if any security-critical files have been modified:

# PowerShell (Windows)
.\security-check.ps1

# Bash (Linux/macOS)
chmod +x ./security-check.sh  # First time only
./security-check.sh

For more details, see SECURITY.md and Chain Hashing Documentation.