🌌 LIFEOS: Gamified Personal Growth RPG & Deep Work Hub

LIFEOS is a premium, high-fidelity human optimization interface that gamifies daily productivity, fitness, and focus tracking. Inspired by cyberpunk command terminals and RPG progression loops, LIFEOS turns tasks into high-reward directives, calculates real-time streak multipliers, logs performance telemetry, and projects rankings on a global leaderboard network.

Explore Live Terminal • Report Bug • Request Directive

🚀 Tech Stack

Frontend Core

Framework: (App Router, Server-side rendering, standalone build configuration)
Runtime:
Language:

Styling & Interactive UI

Engine: with Next/PostCSS compilation
Animations: (Custom spring-based physics and layout morphing)
Graphics: (Dynamic, mouse-following neural interfaces)
Icons:

Telemetry & Analytics

Charts: (Responsive area vectors with gradient fills)

Infrastructure & Cloud

Containerization: (Alpine Node environment)
Cloud Hosting: (Fully-managed serverless container scaling)

✨ Feature Matrix

Feature	Interface File	Core Utility / Logic	XP Value / Multipliers	Description
Interactive Landing	app/page.tsx	components/3d/hero-3d.tsx	N/A	Parallax mouse-tracking, custom glowing spotlights, and dynamic Spline 3D robot loading.
Operations Hub	app/dashboard/page.tsx	hooks/use-game-state.ts	Custom Calculation	Overview terminal containing analytics, active directive list, and quick focus toggles.
Directive Matrix	app/dashboard/tasks/page.tsx	lib/xp-engine.ts	Low: +10 XP Medium: +25 XP High: +50 XP	Standard CRUD quest board categorized by Work, Study, Gym, and Habit.
Focus Room	app/focus/page.tsx	hooks/use-game-state.ts	+2 XP / min active +50 XP completion bonus	Custom Pomodoro protocol running deep focus timer with active task locks.
Arcane Leaderboard	app/leaderboard/page.tsx	Static generator & User state sync	Dynamic sorting	A scrollable ladder matching user metrics against 49 simulated arcane nodes.
Performance Vitals	app/profile/page.tsx	lib/level-system.ts	Multiplier Tier verification	Profile hub showing total metrics, daily activity logs, and unlocked RPG title equipment.

⚙️ System Architecture & Mechanics

graph TD
    User([User Action]) -->|Complete Directive/Focus| StateHook[hooks/use-game-state.ts]
    StateHook -->|Read/Write State| LocalStore[(Browser LocalStorage)]
    StateHook -->|Compute Level & Title| LevelSys[lib/level-system.ts]
    StateHook -->|Evaluate Daily Multipliers| StreakEng[lib/streak-engine.ts]
    StateHook -->|Evaluate Base XP| XPEng[lib/xp-engine.ts]
    
    LevelSys -->|Returns levelInfo & Title| DashboardView[app/dashboard/page.tsx]
    StreakEng -->|Returns streakCount & multi| DashboardView
    
    DashboardView -->|Renders progress| XPRing[components/gamification/xp-ring.tsx]
    DashboardView -->|Renders chart telemetry| Rechart[components/charts/performance-chart.tsx]
    DashboardView -->|Renders heatmap| Heatmap[components/dashboard/heatmap.tsx]

1. State Persistence & Migration

All gamified progression metrics, activity histories, streaks, and settings are handled via useGameState.

Note

Hydration Validation: To bypass next-generation server-side rendering (SSR) hydration mismatches, the hook waits for useEffect execution to retrieve client data from local storage before rendering child components. State Migration: Automatically parses incoming legacy schemas and fills new parameters (e.g., focusSettings, history arrays) on the client side without throwing runtime parsing exceptions.

2. Quadratic Progression Loop (lib/level-system.ts)

XP requirements scale mathematically to ensure early-stage velocity while rewarding long-term user retention. $$\text{Total XP Required for Level } (L) = L^2 \times 100$$ To calculate a user's level from accumulated XP: $$L = \max\left(1, \left\lfloor\sqrt{\frac{\text{Total XP}}{100}}\right\rfloor\right)$$

3. Daily Streak & Multiplier Engine (lib/streak-engine.ts)

Timestamp Verification: Compares the current local browser ISO date string with lastUpdate history.
Dynamic Decay: If the difference exceeds 24 hours, the streak resets to 1. If completed within the next chronological calendar date, the streak increments by 1.
XP Multipliers: Streaks unlock multipliers based on consistency:
- $\text{Streak } \ge 30 \text{ days} \implies 2.0\text{x XP Multiplier}$
- $\text{Streak } \ge 7 \text{ days} \implies 1.5\text{x XP Multiplier}$
- $\text{Default} \implies 1.0\text{x XP Multiplier}$

📁 Configuration & Environment

LIFEOS is engineered to be zero-config out of the box by using browser-native local storage for progression data, removing the need for initial database setups.

If you are deploying in a production ecosystem, you can optionally configure the following variables:

# Next.js Analytics & Optimization (Optional)
NEXT_TELEMETRY_DISABLED=1

# Spline 3D Assets CDN Cache (Custom URL override, falls back to default if unset)
NEXT_PUBLIC_SPLINE_SCENE_URL="https://prod.spline.design/kZDDjO5HuC9GJUM2/scene.splinecode"

📂 Folder Structure

LIFEOS/
├── .dockerignore
├── .gitignore
├── LICENSE                     # Standard MIT Open Source License
├── Dockerfile                  # Multi-stage production container configuration
├── next.config.ts              # Standalone compilation output settings
├── package.json
├── tsconfig.json
├── app/                        # Next.js App Router Structure
│   ├── dashboard/              
│   │   ├── gym/                # Workouts log portal
│   │   ├── tasks/              # Quest / Directive board
│   │   ├── layout.tsx          
│   │   └── page.tsx            # Main Analytics Terminal
│   ├── focus/                  # Focus Room timer layout
│   ├── leaderboard/            # Ranks listing interface
│   ├── profile/                # Vitals / Titles manager
│   ├── globals.css             # Main styling system
│   └── layout.tsx              
├── components/                 # Component Architecture
│   ├── 3d/                     
│   │   └── hero-3d.tsx         # Floating 3D Spline container
│   ├── charts/                 
│   │   └── performance-chart.tsx # Recharts performance area curves
│   ├── dashboard/              
│   │   └── heatmap.tsx         # Activity grid heatmap
│   ├── gamification/           
│   │   ├── xp-popup.tsx        # Framer Motion float-up notifications
│   │   └── xp-ring.tsx         # SVG Level progression circle
│   └── ui/                     # Generic design system components
├── hooks/                      
│   └── use-game-state.ts       # Unified system state logic
└── lib/                        
    ├── level-system.ts         # Quadratic progression formulas
    ├── streak-engine.ts        # Chrono-stamp validator
    └── xp-engine.ts            # Base valuation variables

🔧 Installation & Setup

Local Development

Clone the Repository

git clone https://github.com/Kanneboinashivakumar/LifeOS.git
cd LifeOS

Install Node Modules Ensure you have Node.js 20+ installed.
```
npm install
```
Run Development Server
```
npm run dev
```
Access the interface at http://localhost:3000.

Docker Production Deployment

Build Container Image
```
docker build -t lifeos:latest .
```
Execute Container Locally
```
docker run -p 3000:3000 lifeos:latest
```

Deploy directly to Google Cloud Run

gcloud run deploy lifeos-app \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --project <your-gcp-project-id>

💻 Hook & API Documentation

The entire state machine is bound to the useGameState custom hook. You can integrate this hook into any component to read user statistics, log activity, or manage directives.

Hook Interface (`useGameState`)

const {
  state,               // Complete GameState object
  addXP,               // (amount: number, type?: string) => void
  addTask,             // (text: string, priority: 'low' | 'medium' | 'high', category: string, desc?: string) => void
  toggleTask,          // (id: string) => void
  updateTaskStatus,    // (id: string, status: 'available' | 'ongoing' | 'completed') => void
  updateFocusSettings, // (workTime: number, breakTime: number) => void
  setActiveTitle,      // (title: string) => void
  isInitialized        // boolean flag indicating LocalStorage hydration status
} = useGameState();

Usage Examples

1. Consuming Unified Game State

Components hook into the central game loop context using standard Next.js client declarations:

'use client';

import { useGameState } from '@/hooks/use-game-state';

export default function MyWidget() {
  const { state, addXP, toggleTask } = useGameState();

  return (
    <div>
      <p>Active Title: {state.activeTitle}</p>
      <p>Current XP: {state.xp}</p>
      <button onClick={() => addXP(50, 'manual_bonus')}>
        Gain 50 XP
      </button>
    </div>
  );
}

2. Dynamic XP Calculation Formula

How multipliers and base XP rates interact in the XP Engine:

import { calculateXP, getStreakMultiplier } from '@/lib/xp-engine';

const baseXP = 100; // Gym workout completion
const currentStreak = 15; // 15-day consistency

const multiplier = getStreakMultiplier(currentStreak); // Yields 1.5
const finalXP = calculateXP(baseXP, multiplier); // Returns 150 XP

📸 Interface Screenshots

🌌 Landing Page (Neural Interface)

📊 Operations Hub (Dashboard)

⏱️ Evolution Lab & Directive Matrix

⏱️ Evolution Lab (Focus Protocol)	📝 Directive Matrix (Task System)

🏆 Arcane Rankings & Subject Vitals

🏆 Arcane Rankings (Leaderboard)	👤 Subject Vitals (Player Profile)

❓ FAQ

Q: How does the system handle page reloads?

All progression markers (XP, custom titles, task matrices, focus history) are serialized into JSON strings and stored in the browser's localStorage. They are re-hydrated dynamically upon subsequent visits.

Q: Can I run this server-side without a browser context?

Yes. The codebase uses custom check utilities (typeof window !== 'undefined') to prevent server runtime compilation errors, allowing the app to build statically.

Q: Where are the 3D model assets loaded from?

The 3D Spline files are loaded dynamically from Spline's content delivery network (CDN) inside the lazy-loaded SplineScene wrapper.

🛠️ Troubleshooting

Hydration Error (Server/Client Text Mismatch):
- Issue: Browser regional formatters causing XP to display as 1,500 (US format) while the server rendered raw numbers.
- Solution: The leaderboard utilizes toLocaleString('en-US') to enforce rendering parity. Ensure custom widgets use strict locale formatting parameters.
Spline Scene Fails to Render:
- Issue: Slow network connections block CDN asset loading.
- Solution: The SplineScene component implements React Suspense and outputs a Tailwind loading spinner fallback until the script finishes execution.

⚡ Performance Optimizations

STANDALONE Next.js Output: next.config.ts compiles the production application as a standalone build directory containing only the minimum necessary production dependencies. This reduces final docker image sizes from >1.2GB to less than 120MB.
Code Splitting / Lazy Loading: The Spline engine is imported lazily:
```
const Spline = lazy(() => import('@splinetool/react-spline'));
```
This removes heavy WebGL packages from the initial bundle size, allowing the landing page to achieve optimal loading speeds.
Tailwind CSS 4 Compilation: Uses Tailwind v4 utility setups which compile directly during Next build passes, removing CSS parsing bottlenecks on client runtimes.

🔮 Future Roadmap

Task-linked XP Modifiers: Introduce active item tracking that modifies XP payout speeds dynamically based on current focus categories.
Collaborative Boss Raids: Sync user profiles to create party-based productivity targets (e.g. "Complete 20 gym workouts collectively to defeat the Boss").
Webhooks Integration: Automate XP gains via GitHub commits or LeetCode completion status APIs.

🤝 Contributing

Contributions are welcome! Please follow these standards:

Fork the repository.
Create your feature branch: git checkout -b feature/amazing-feature.
Commit your changes: git commit -m 'feat: add amazing feature'.
Push your branch to GitHub: git push origin feature/amazing-feature.
Open a Pull Request.

📄 License

Distributed under the MIT License. See LICENSE for more details.

✉️ Contact & Network

Developer: Kanneboina Shivakumar
GitHub: @Kanneboinashivakumar
Project Link: https://github.com/Kanneboinashivakumar/LifeOS

Name		Name	Last commit message	Last commit date
app		app
components		components
hooks		hooks
lib		lib
public		public
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation