# Gamified Habit Tracker 🎮

Transform habit tracking into an engaging RPG-style game. Build your character, complete daily quests, unlock achievements, and compete on the leaderboard as you level up through habit completion.

## Requirements

- **Node.js** 18+
- **Python** 3.12+
- **Git**

## Quick Start

### 1. Clone & Install Backend

```bash
git clone https://github.com/YOUR_USERNAME/gamified-habit-tracker.git
cd gamified-habit-tracker/backend

python -m venv venv
# Windows: venv\Scripts\activate
# Mac/Linux: source venv/bin/activate

pip install -r requirements.txt
python manage.py migrate
python manage.py seed_achievements
python manage.py create_mock_users
```

### 2. Run Backend

```bash
python manage.py runserver
# Server at http://localhost:8000
```

### 3. Install & Run Frontend

```bash
cd ../frontend
npm install
npm run dev
# App at http://localhost:5173
```

## Test Accounts

**Default:**
- `johndoe` / `demo123` (admin)
- `reese` / `demo123` (user)

**Plus 49 more:** See `backend/mock_users_auth.txt` for all 51 accounts (levels 1-30)

## Database Reset

To completely reset the database and re-seed all initial data (including test accounts):

```bash
cd backend
python manage.py reset_db
```

**Note:** This will delete all existing data and recreate the database with fresh seed data.

## Key Features

- **Character Progression** - Level up and earn XP through habits
- **5 Attributes** - Strength, Intelligence, Creativity, Social, Health
- **Quest Limits** - Unlock more quests as you level (4 → 6 → 8 → 10 → unlimited)
- **Daily Check-ins** - 100 XP per day with GitHub-style calendar
- **21 Achievements** - Unlock badges through progression
- **Leaderboard** - Compete with other players globally

## Project Stack

- **Backend:** Django 5.2.6 + Django REST Framework
- **Frontend:** React 18 + Vite + Tailwind CSS
- **Database:** SQLite (dev)
- **Auth:** Token-based (dj-rest-auth)

## Directory Structure

### Project Root
```
gamified-habit-tracker/
├── backend/          # Django backend application
├── frontend/         # React frontend application
├── README.md         # This file
├── INSTALLATION.md   # Detailed installation guide
└── USER_MANUAL.md    # User manual and feature guide
```

### Backend Directory (`backend/`)

```
backend/
├── api/                          # Main Django app
│   ├── models.py                 # Database models (User, Habit, Achievement, Equipment)
│   ├── views.py                  # API endpoints for habit management
│   ├── game_views.py             # Game mechanics and tower combat endpoints
│   ├── serializers.py            # Data serialization for API responses
│   ├── game_serializers.py       # Game-specific data formatting
│   ├── ai_service.py             # OpenAI integration for intelligent XP calculation
│   ├── signals.py                # Event handling (e.g., level-up triggers)
│   ├── urls.py                   # API route definitions
│   ├── admin.py                  # Django admin interface configuration
│   └── tests.py                  # Unit tests
│
├── migrations/                   # Database schema version control
│   ├── 0001_initial.py           # Initial database schema
│   ├── 0002_achievement_equipment_*.py  # Game mechanics
│   ├── 0003_add_daily_checkin.py # Daily check-in feature
│   └── ...                       # Additional migrations
│
├── management/commands/          # Django management scripts
│   ├── create_mock_users.py      # Generate test accounts (51 users, levels 1-30)
│   ├── seed_achievements.py      # Populate achievement data (21 badges)
│   ├── seed_equipment.py         # Add equipment items to database
│   ├── reset_db.py               # Complete database reset utility
│   └── ...                       # Additional utilities
│
├── core/                         # Django project configuration
│   ├── settings.py               # Core configuration (database, apps, middleware)
│   ├── urls.py                   # Main URL router
│   ├── wsgi.py                   # WSGI application entry point
│   └── asgi.py                   # ASGI application entry point
│
├── manage.py                     # Django management command runner
├── requirements.txt              # Python dependencies
├── mock_users_auth.txt           # Pre-generated test account credentials
└── .env.example                  # Environment variables template
```

**Key Backend Directories:**
- **`api/`** - Core application logic, models, API endpoints, and game mechanics
- **`migrations/`** - Database schema evolution tracking
- **`management/commands/`** - Custom Django commands for seeding data and utilities
- **`core/`** - Project-wide Django settings and configuration

### Frontend Directory (`frontend/`)

```
frontend/
├── src/
│   ├── components/               # React components
│   │   ├── Login.jsx             # User authentication
│   │   ├── Register.jsx          # User registration
│   │   ├── Navbar.jsx            # Navigation bar
│   │   ├── Dashboard.jsx         # Main dashboard
│   │   ├── HabitTracker.jsx      # Habit tracking interface
│   │   ├── HabitCreation.jsx     # Create new habits
│   │   ├── HabitEditor.jsx       # Edit existing habits
│   │   ├── AchievementPanel.jsx  # Achievement display
│   │   ├── CharacterCustomizer.jsx # Character appearance customization
│   │   ├── StatsDisplay.jsx      # Character stats visualization
│   │   └── game/                 # Game-specific components
│   │       ├── GameDashboard.jsx     # Game dashboard
│   │       ├── CharacterAvatar.jsx   # Character avatar display
│   │       ├── CombatScene.jsx       # Turn-based combat
│   │       ├── RealTimeCombatScene.jsx # Real-time combat
│   │       ├── DailyCheckInTracker.jsx # Daily check-in calendar
│   │       └── ParticleSystem.jsx    # Visual effects
│   │
│   ├── pages/                    # Page-level components
│   │   ├── Home.jsx              # Home page
│   │   ├── Tower.jsx             # Tower combat/progression
│   │   ├── Leaderboard.jsx       # User rankings
│   │   └── Settings.jsx          # User settings
│   │
│   ├── services/                 # API and utility services
│   │   ├── apiClient.js          # Base HTTP client (Axios)
│   │   ├── userApi.js            # User authentication/profile API
│   │   ├── gameApi.js            # Game mechanics API calls
│   │   └── soundManager.js       # Audio/sound effects manager
│   │
│   ├── contexts/                 # React Context state management
│   │   └── AuthContext.jsx       # Authentication state
│   │
│   ├── utils/                    # Utility functions
│   │   ├── characterSprites.js   # Character sprite mapping
│   │   ├── dungeonGenerator.js   # Procedural dungeon generation
│   │   ├── pathfinding.js        # A* pathfinding algorithm
│   │   └── themeBackgrounds.js   # Theme background management
│   │
│   ├── assets/                   # Source assets
│   │   ├── characters/           # Character sprites (default, zoro, cyberpunk)
│   │   ├── equipment/            # Equipment sprites (weapons, armor, helmets)
│   │   └── *.png, *.jpg          # Environment textures and backgrounds
│   │
│   ├── App.jsx                   # Root App component
│   ├── main.jsx                  # React entry point
│   └── index.css                 # Global styles
│
├── public/                       # Static assets
│   └── enemies/                  # Enemy sprites (slimes, skeletons, shadows)
│
├── package.json                  # NPM dependencies and scripts
├── vite.config.js                # Vite build configuration
├── tailwind.config.js            # Tailwind CSS configuration
└── index.html                    # HTML entry point
```

**Key Frontend Directories:**
- **`src/components/`** - Reusable React components for UI and game features
- **`src/pages/`** - Page-level components representing different routes
- **`src/services/`** - API integration and external service management
- **`src/contexts/`** - Global state management using React Context
- **`src/utils/`** - Helper functions and utilities
- **`src/assets/`** - Images, sprites, and visual assets
- **`public/`** - Static files served directly

## Documentation

- [Installation Guide](INSTALLATION.md) - Step-by-step setup instructions
- [User Manual](USER_MANUAL.md) - Complete feature guide and usage instructions

---

**Version:** 1.0.0 | **Last Updated:** November 22, 2025
