Skip to content
kareemaimanPublic

About

Habitify RPG — gamified habit & productivity tracking system (FastAPI, Django, PostgreSQL, Docker Compose)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🛡️ Habitify RPG — Gamified Habit & Productivity Tracking System

Habitify RPG Dashboard Hero

FastAPI Django PostgreSQL Docker Tailscale Chart.js


📌 Executive Summary

Habitify RPG is an enterprise-grade, gamified behavioral tracking platform designed to bridge psychological habit formation principles with the mechanics of classic Role-Playing Games (RPGs). By abstracting daily habits, workflows, and one-time tasks into character progression metrics, Habitify transforms discipline into tangible character growth.

The system is built on an isolated, 4-tier microservice architecture:

  • Presentation Tier: Glassmorphism Single-Page Application (SPA) served via Nginx.
  • Game Engine Tier: Django / DRF backend orchestrating game rules, formulas, and leveling logic.
  • Data Access Tier: High-throughput FastAPI CRUD service with SQLAlchemy ORM.
  • Persistence Tier: PostgreSQL database with custom relational constraints and audit logs.
  • Edge Networking: Zero-trust Tailscale Funnel / mesh network ensuring internal database isolation.

⚔️ Key Features & Gamification Mechanics

1. 🧙 RPG Class & Attribute Progression System

  • Choose from iconic classes (Warrior, Mage, Rogue, Cleric, Paladin).
  • Each class applies dynamic attribute scaling multipliers to your core stats:
    • Strength (STR): Boosted by physical exercise and endurance tasks.
    • Intelligence (INT): Boosted by reading, deep work, and learning milestones.
    • Discipline (DIS): Scaled with consistent daily routine execution.
    • Vitality (VIT): Scaled through sleep hygiene, nutrition, and hydration.

2. 📈 Non-Linear Exponential Leveling Curve

Character leveling adheres to a mathematical power progression formula to maintain long-term engagement:

$$\text{EXP}_{\text{required}}(L) = \left\lfloor \text{Base EXP} \times L^{\gamma} \right\rfloor$$

$$\text{Where } \text{Base EXP} = 100, \quad \gamma = 1.5, \quad L = \text{Current Level}$$

3. 🔥 Consistency Streaks & Attrition Penalties

  • Streak Bonuses: Cumulative daily habit executions build exponential streak multipliers, increasing gold and EXP drops.
  • Inactivity Penalties: Failing habits or remaining inactive for $> 3\text{ days}$ triggers progressive stat decay and EXP attrition to enforce accountability.

4. 🍺 The Gilded Tavern & Custom Reward Economy

  • Earn in-game Gold (🪙) by slaying real-world tasks.
  • Spend Gold on in-game consumables (Elixir of Intellect, Streak Shields) or redeem user-defined real-world rewards ("1 Episode of Netflix", "Specialty Coffee Treat").

📸 Visual Showcase & UI Tour

1. Command Center & Character Status

Real-time HUD displaying character level, EXP progress bar, attribute matrix, active class multipliers, and daily quest trackers with streak counters.

Habitify RPG Command Center


2. The Gilded Tavern (Reward Economy)

In-game marketplace featuring utility items, streak freezes, and custom reward redemption.

The Gilded Tavern Shop


3. Hero Insights & Attribute Progression

Multi-dimensional radar matrix of RPG attributes combined with weekly consistency and EXP performance charts.

Hero Insights and Charts


4. Relational Database Schema (ERD)

3NF relational schema enforcing strict foreign key constraints, class modifiers, and audit histories.

Database Entity Relationship Diagram


🏛️ System Architecture

Habitify employs strict service isolation. The persistent database layer and CRUD services are completely inaccessible from the public internet. All traffic passes through a secure reverse proxy and Tailscale VPN tunnel.

graph TD
    Client["🌐 Client Browser / Mobile Web"]
    
    subgraph Edge_Ingress ["Edge & Ingress Layer"]
        TS["🔒 Tailscale Funnel / VPN Mesh"]
        Nginx["⚡ Nginx Reverse Proxy & Static Host"]
    end

    subgraph Business_Logic ["Application & Business Logic"]
        Django["🎮 Django Game Engine / REST API"]
        Scheduler["⏰ Celery / Async Cron Worker"]
    end

    subgraph Data_Access ["Data Access Layer"]
        FastAPI["🚀 FastAPI CRUD Microservice"]
    end

    subgraph Persistence ["Persistence Layer"]
        DB[("🐘 PostgreSQL 15 Database")]
    end

    Client -->|HTTPS| TS
    TS --> Nginx
    Nginx -->|Static Assets| Client
    Nginx -->|"API Proxy /api/*"| Django
    Django -->|Internal HTTP Client| FastAPI
    Scheduler -->|Periodic Penalties & Streak Sync| FastAPI
    FastAPI -->|SQLAlchemy ORM Port 5432| DB
Loading

🗄️ Database Entity Schema Summary

Table Description Key Relationships
users Primary user identity, authentication, and credentials $1 \to 1$ with characters, $1 \to N$ with habits, tasks
classes RPG Archetypes (Warrior, Mage, Rogue, etc.) $1 \to N$ with class_modifiers, characters
class_modifiers Multiplier coefficients per attribute (STR, INT, DIS, VIT) $N \to 1$ with classes
characters Hero state, current Level, total EXP, and Gold balance $1 \to N$ with character_stats, inventory, activity_log
habits Recurring daily routines with frequency and difficulty tiers $1 \to N$ with habit_stat_impacts
tasks Discrete, one-time quests with explicit deadlines $1 \to N$ with task_stat_impacts
inventory Consumables, streak protection shields, and unlocked perks $N \to 1$ with characters
shop_rewards Available in-game and personalized real-world rewards $N \to 1$ with users
activity_log Time-series audit logs of completed quests and rewards $N \to 1$ with characters

🚀 Getting Started & Deployment

Prerequisites

Quick Start via Docker Compose

  1. Clone the Repository:

    git clone https://github.com/your-username/habitify-rpg.git
    cd habitify-rpg
  2. Configure Environment Variables: Create a .env file in the project root:

    VERSION=1.0.0
    DB_HOST=postgres
    DB_PORT=5432
    DB_NAME=habitify
    DB_USER=habitify_admin
    DB_PASSWORD=YourSecurePassword123!
    FILTER_API_URL=http://habitify-filter:8000
    BACKEND_API_URL=http://habitify-backend:8000
    TS_AUTHKEY=tskey-auth-your-tailscale-key
  3. Build and Launch the Stack:

    docker compose -f gamify/docker-compose.yml up -d --build
  4. Verify Service Health:

    docker compose -f gamify/docker-compose.yml ps
  5. Access Endpoints:

    • Frontend App: http://localhost:80 (or http://habitify.home via Traefik)
    • Game Engine API: http://localhost:8000/docs
    • Data CRUD Service: http://localhost:8001/docs

📁 Repository Directory Structure

.
├── assets/
│   ├── diagrams/             # Relational ERD and architectural diagrams
│   │   └── erd-diagram.png
│   └── screenshots/          # High-resolution application UI captures
│       ├── dashboard.png
│       ├── tavern_shop.png
│       └── analytics_insights.png
├── database/                 # SQL schemas, migration scripts, and seeders
│   ├── sql.md
│   └── sql script.txt
├── docs/
│   ├── presentations/        # PowerPoint and slide deck overviews
│   ├── reports_and_data/     # GTmetrix performance audits and test logs
│   └── specifications/       # IEEE SRS v5, functional specifications
├── gamify/                   # Core microservice codebases
│   ├── backend/              # Django / DRF Game Controller Engine
│   ├── filter/               # FastAPI Data Access & ORM Microservice
│   ├── frontend/             # Nginx Static SPA & Chart.js modules
│   ├── tailscale/            # Secure VPN container configuration
│   └── docker-compose.yml    # Master container orchestration
├── Habitify_RPG_Technical_Report.pdf  # Comprehensive academic whitepaper
└── README.md                 # Primary project documentation

📄 Academic Whitepaper & Technical Report

A full IEEE-standard technical whitepaper is included in the root directory: Habitify_RPG_Technical_Report.pdf.

Topics covered in the report:

  1. Behavioral Gamification Theory (Self-Determination Theory & Octalysis Framework).
  2. Mathematical Proofs of EXP Scaling, Dynamic Decay Functions, and Economy Equilibrium.
  3. Multi-tier Microservice Isolation Benchmarks (GTmetrix Performance Audit).
  4. Relational Normalization (3NF) & Concurrency Control.

📜 License & Acknowledgments

This project is licensed under the MIT License. Built with ❤️ for adventurers seeking mastery over their habits.

About

Habitify RPG — gamified habit & productivity tracking system (FastAPI, Django, PostgreSQL, Docker Compose)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages