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.
- 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.
Character leveling adheres to a mathematical power progression formula to maintain long-term engagement:
- 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.
- 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").
Real-time HUD displaying character level, EXP progress bar, attribute matrix, active class multipliers, and daily quest trackers with streak counters.
In-game marketplace featuring utility items, streak freezes, and custom reward redemption.
Multi-dimensional radar matrix of RPG attributes combined with weekly consistency and EXP performance charts.
3NF relational schema enforcing strict foreign key constraints, class modifiers, and audit histories.
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
| Table | Description | Key Relationships |
|---|---|---|
users |
Primary user identity, authentication, and credentials |
characters, habits, tasks
|
classes |
RPG Archetypes (Warrior, Mage, Rogue, etc.) |
class_modifiers, characters
|
class_modifiers |
Multiplier coefficients per attribute (STR, INT, DIS, VIT) |
classes
|
characters |
Hero state, current Level, total EXP, and Gold balance |
character_stats, inventory, activity_log
|
habits |
Recurring daily routines with frequency and difficulty tiers |
habit_stat_impacts
|
tasks |
Discrete, one-time quests with explicit deadlines |
task_stat_impacts
|
inventory |
Consumables, streak protection shields, and unlocked perks |
characters
|
shop_rewards |
Available in-game and personalized real-world rewards |
users
|
activity_log |
Time-series audit logs of completed quests and rewards |
characters
|
- Docker Engine (v24.0+)
- Docker Compose (v2.20+)
- Tailscale Account & Auth Key (Optional, for public mesh exposure)
-
Clone the Repository:
git clone https://github.com/your-username/habitify-rpg.git cd habitify-rpg -
Configure Environment Variables: Create a
.envfile 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
-
Build and Launch the Stack:
docker compose -f gamify/docker-compose.yml up -d --build
-
Verify Service Health:
docker compose -f gamify/docker-compose.yml ps
-
Access Endpoints:
- Frontend App:
http://localhost:80(orhttp://habitify.homevia Traefik) - Game Engine API:
http://localhost:8000/docs - Data CRUD Service:
http://localhost:8001/docs
- Frontend App:
.
├── 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
A full IEEE-standard technical whitepaper is included in the root directory: Habitify_RPG_Technical_Report.pdf.
Topics covered in the report:
- Behavioral Gamification Theory (Self-Determination Theory & Octalysis Framework).
- Mathematical Proofs of EXP Scaling, Dynamic Decay Functions, and Economy Equilibrium.
- Multi-tier Microservice Isolation Benchmarks (GTmetrix Performance Audit).
- Relational Normalization (3NF) & Concurrency Control.
This project is licensed under the MIT License. Built with ❤️ for adventurers seeking mastery over their habits.



