PetTimer is an integrated productivity management platform that leverages gamification mechanics to enhance user engagement with time management and goal-setting practices. The application synthesizes the Pomodoro Technique methodology with virtual pet care mechanics, creating a behavioral reinforcement system that promotes sustained focus and productive work habits. Through a combination of timer-based task management, adaptive goal tracking, and AI-assisted planning capabilities, PetTimer establishes a dynamic ecosystem where user productivity directly correlates with measurable in-application rewards and virtual asset accumulation.

The platform operates on a dual-incentive model: immediate gratification through pet care mechanics paired with long-term productivity tracking through goal management and check-in systems. Users interact with customizable virtual companions (fox, cat, or dog) whose well-being metrics fluctuate based on completion of 25-minute focused work intervals. The accumulation of in-application currency and experience points creates a closed economic loop that incentivizes consistent user engagement with the primary productivity mechanism.

The system comprises several interconnected subsystems that create a comprehensive productivity ecosystem:

• Temporal Management Module: Pomodoro-based 25-minute focus intervals generate primary rewards (flames and coins)
• Pet Care Mechanics: Accumulated currency enables maintenance and enhancement of virtual companion states
• Dynamic Status System: Pet health metrics (hunger, happiness, energy) adjust based on user productivity patterns
• Reward Structure: Completion of work cycles translates directly to virtual asset accumulation

The application incorporates a multi-dimensional pet state model that serves as the primary user engagement interface. Users select from three distinct pet archetypes (fox, cat, dog), each with unique personality characteristics and behavioral responses. The pet state encompasses three primary metrics:

• Satiation Level: Tracks nutritional requirements over time; depletes at configurable intervals and requires currency-based replenishment through in-app purchases
• Affection Index: Increases through tactile interaction (petting mechanics) and proper care; influences overall pet responsiveness and engagement signals
• Energy Reserves: Diminishes through passage of time and activity; recovers through designated rest periods, creating a temporal barrier to continuous interaction

Interactive feedback mechanisms include contextual vocalizations and behavioral responses (e.g., "Woof!" for positive interactions, tired animations during low-energy states), reinforcing user comprehension of pet state transitions.

The application implements the established Pomodoro Technique through a 25-minute focus interval mechanism paired with automatic break period notifications. The system generates quantifiable rewards upon successful interval completion:

• Primary Reward Mechanism: 1 flame point (🔥) per completed interval
• Secondary Currency: 5 coin units (🪙) per completed interval
• Optional Goal Association: Users may link intervals to specific objectives, enabling horizontal progress tracking across multiple goal categories

The interface displays a circular progress indicator providing real-time visualization of remaining focus duration. After four consecutive intervals, the system generates a notification recommending an extended 15-minute break, aligning with documented Pomodoro methodology principles.

The goal management subsystem enables hierarchical task decomposition and progress quantification. The system supports:

• Categorical Organization: Work, study, health, hobby, and personal development categories
• Temporal Framing: Automated deadline calculation based on user-specified timeframe
• Subtask Decomposition: Large objectives subdivide into discrete, measurable steps
• Progress Quantification: Automatic calculation of completion percentages based on subtask fulfillment
• Status Lifecycle: Active, completed, and abandoned status designations for goal categorization

AI-assisted planning generates recommended daily action sequences derived from goal parameters and specified difficulty levels, facilitating structured progression toward stated objectives.

The check-in calendar provides a temporal record of user productivity and subjective well-being metrics:

• Temporal Recording: Date-stamped entries capturing focused duration and completed activities
• Subjective Metrics: Mood indicators (happy, neutral, tired) enabling longitudinal affective tracking
• Multimedia Integration: Photo upload capability for documentation purposes
• Social Sharing: Direct integration with Instagram for progress dissemination
• Streak Tracking: Continuous flame counter monitoring consecutive check-in days

The calendar visualization operates at a monthly granularity, providing overview-level perspective on productivity patterns and engagement consistency.

The shop system implements an economic mechanism for currency circulation and aesthetic customization:

• Asset Classification: Food categories (bones, fish, cakes, sushi), apparel (hats, capes, crowns), entertainment items (balls, toy mice, frisbees)
• Rarity Stratification: Common, rare, and epic designations with corresponding cost differentiation
• Price Stratification: Currency costs ranging from 10 to 150 coins based on asset rarity
• Transaction Validation: Automatic currency sufficiency verification prior to purchase authorization

The profile module consolidates account-level metrics and achievement tracking:

• Pet Metadata: Name, current level, experience points, and level progression percentage
• Productivity Metrics: Cumulative Pomodoro completion count, consecutive check-in count, total currency reserves, and total flame accumulation
• Achievement Archival: Historical record of completed objectives and system milestones

React 18 with TypeScript: The application utilizes functional component patterns and hook-based state management for reactive UI rendering. TypeScript provides comprehensive type safety ensuring compile-time validation of component interfaces and data structures.

Vite Build Tool: Implements rapid development iteration through native ES module support and optimized production bundling, significantly reducing development cycle latency.

Zustand: Provides lightweight, minimalist global state management without excessive boilerplate, enabling efficient data flow across component hierarchies.

Browser Storage Persistence: Local storage implementation ensures durability of user data across session terminations, enabling offline-first functionality.

Tailwind CSS: Utility-first CSS framework enabling rapid prototyping and consistent design system implementation across the entire application surface.

Lucide React Icon Library: Provides scalable vector iconography ensuring visual clarity across varying screen densities and resolutions.

Custom Animation Framework: CSS keyframe animations supplemented with Tailwind CSS animation utilities create smooth visual transitions and engaging user feedback mechanisms.

• usePetState: Manages temporal state degradation and recovery cycles for pet welfare metrics
• usePomodoro: Encapsulates 25-minute timer logic with interval completion detection
• useGoalProgress: Calculates hierarchical progress aggregation across subtask completion
• useCheckInStreak: Maintains chronological consistency for consecutive daily engagement
• usePetReaction: Generates contextual behavioral responses based on interaction state

The application incorporates Qwen AI language model integration via DashScope API, providing adaptive goal planning and analysis capabilities. The implementation employs Vite proxy configuration to circumvent Cross-Origin Resource Sharing (CORS) restrictions in browser environments, ensuring seamless API communication.

Environment Setup:

cp .env.example .env

API Credential Configuration:

# Preferred (used by Vite dev proxy)
DASHSCOPE_API_KEY="Your DashScope API Key"

# Optional compatibility key (web/desktop fallback)
VITE_DASHSCOPE_API_KEY="Your DashScope API Key"

Development Server Initialization:

npm run dev

API requests fail gracefully if neither DASHSCOPE_API_KEY nor VITE_DASHSCOPE_API_KEY is configured.

PetTimer/
├── src/
│   ├── components/              # React component modules
│   │   ├── PetCard.tsx          # Pet interaction and rendering
│   │   ├── PomodoroTimer.tsx    # Timer control interface
│   │   ├── GoalTracker.tsx      # Objective management
│   │   ├── CheckInCalendar.tsx  # Temporal record display
│   │   ├── Shop.tsx             # Economic transaction interface
│   │   ├── NavBar.tsx           # Application navigation
│   │   └── PetSelector.tsx      # Pet selection interface
│   ├── hooks/                   # Custom React Hook definitions
│   │   └── index.ts
│   ├── store/                   # Zustand state definitions
│   │   └── appStore.ts
│   ├── types/                   # TypeScript interface definitions
│   │   └── index.ts
│   ├── App.tsx                  # Primary application component
│   ├── main.tsx                 # Application bootstrap
│   └── index.css                # Global stylesheet
├── public/                      # Static asset resources
├── index.html                   # HTML document template
├── package.json                 # Dependency manifest
├── tsconfig.json                # TypeScript configuration
├── vite.config.ts              # Build system configuration
├── tailwind.config.js           # Style framework configuration
└── postcss.config.js            # CSS processing configuration

npm install

npm run dev

Application server initialization defaults to http://localhost:5173

npm run build

interface Pet {
  id: string;
  type: 'fox' | 'cat' | 'dog';
  name: string;
  level: number;
  experience: number;
  hunger: number;              // Range: 0-100
  happiness: number;           // Range: 0-100
  energy: number;              // Range: 0-100
  lastFed: Date;
  lastPetted: Date;
  items: PetItem[];
}

interface Goal {
  id: string;
  title: string;
  description: string;
  category: string;
  targetDate: Date;
  progress: number;            // Range: 0-100
  subtasks: Subtask[];
  shortTermGoals: string[];
  createdAt: Date;
  status: 'active' | 'completed' | 'abandoned';
}

interface CheckInRecord {
  id: string;
  date: Date;
  focusTime: number;           // Duration in minutes
  activities: string[];
  achievement?: string;
  photoUrl?: string;
  mood: 'happy' | 'normal' | 'tired';
  notes?: string;
}

The application implements browser-level local storage mechanisms for persistent data management. All user data—including profile information, pet state, objective definitions, check-in records, and currency metrics—is maintained in the browser's localStorage. This architecture enables offline-first functionality while maintaining client-side data autonomy.

1. Select pet archetype (fox, cat, or dog)
2. Assign personalized pet identifier
3. Initiate primary application flow

1. Home Dashboard: Monitor pet wellness metrics and initiate focus intervals
2. Objective Management: Define, decompose, and track progress toward stated goals
3. Daily Documentation: Record productivity metrics and affective state
4. Economic Transactions: Allocate accumulated currency toward pet maintenance items
5. Metrics Review: Consult aggregated productivity metrics and achievement records

Focus Interval Completion → Flame + Coin Accumulation
                      ↓
Pet Item Acquisition → Affection Metric Increases
                      ↓
Daily Documentation → Engagement Streak Increases
                      ↓
Objective Completion → Achievement Recognition

• Advanced Natural Language Processing for dynamic goal decomposition
• Multi-user collaborative features enabling progress sharing
• Achievement badge system for milestone recognition
• Pet evolution mechanics and variant transformations
• Concurrent multi-pet management capabilities
• Quantitative analytics visualization and reporting
• Substrate-agnostic display mode selection (dark/light)
• Internationalization framework supporting multiple language communities
• Systematic notification delivery for engagement optimization

Technical feedback, bug reports, and feature proposals may be submitted through GitHub issue tracking or pull request mechanisms.

MIT License

Maximize your productivity while nurturing your virtual companion in PetTimer. 🐾✨