State Persistence Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• index.html
• Quest.html
• README.md
• index.html:125-240 (Script Logic)
• Quest.html:125-240 (Script Logic)

Introduction

The State Persistence Strategy for the Solo System project is built around a client-side storage mechanism designed to maintain user progress, rank statistics, and daily task completion across browser sessions. The system utilizes the browser's localStorage API to provide a seamless "Solo Leveling" experience where user attributes like points and levels are preserved locally.

This strategy ensures that the gamified elements of the application—such as the RPG-style leveling system and the daily penalty mechanism—function consistently without the need for a backend database. The state management logic handles data initialization, periodic updates based on time zones, and reactive UI changes triggered by state mutations.
Sources: index.html:158-160, Quest.html:158-160

Data Schema and Storage

The application state is encapsulated within a single JSON object stored under the key solo_penalty_v1. This object contains all necessary metrics to reconstruct the user's progress and determine current daily requirements.

System Data Structure

The systemData object consists of the following fields:

Field	Type	Description
points	Number	The cumulative XP/points earned by the user.
lastUpdate	String	ISO-style date string (YYYY-MM-DD) of the last session.
dailyTasks	Array	A collection of task objects generated for the current day.
lastPenalty	Number	The amount of points deducted during the last daily cycle check.

Sources: index.html:158-160, Quest.html:158-160

Task Object Structure

Each entry in the dailyTasks array is a sub-object containing:

• n: The name/description of the task (String).
• c: The category (e.g., 'جسدي', 'انضباط', 'عقلي') (String).
• d: Completion status (Boolean).

Sources: index.html:188-193, Quest.html:188-193

Persistence Lifecycle

The system manages state through three primary phases: Initialization, Mutation, and Serialization.

Persistence Flow

The following diagram illustrates how the system retrieves data on load and updates it based on user interaction or daily transitions.

The persistence lifecycle starts with JSON.parse(localStorage.getItem('solo_penalty_v1')) and concludes with the save() function.
Sources: index.html:158-160, index.html:195-220, Quest.html:232

Daily Cycle and Time Synchronization

A critical component of the persistence strategy is the synchronization with the 'Asia/Riyadh' time zone to ensure the "Daily Quest" logic resets correctly regardless of the user's local system time settings.

Cycle Management Logic

The checkDailyCycle function compares the lastUpdate field in the persisted state with the current date in Riyadh. If a mismatch is detected, the system calculates penalties for uncompleted tasks from the previous session before generating new tasks.

State Mutation and UI Synchronization

State persistence is reactive. Any change to the user's progress (such as completing a task) triggers an immediate serialization to localStorage to prevent data loss.

The Save Mechanism

The implementation uses a dedicated save() function to abstract the localStorage interaction:

function save() { 
    localStorage.setItem('solo_penalty_v1', JSON.stringify(systemData)); 
}

Sources: index.html:232, Quest.html:232

Task Interaction Flow

1. User clicks a task card.
2. toggleTask(i) is invoked.
3. The systemData.dailyTasks[i].d boolean is flipped.
4. systemData.points is adjusted based on config.reward.
5. save() is called to commit the change.
6. updateUI() and render() are called to reflect the new state in the DOM.
   Sources: index.html:220-227, Quest.html:220-227

Summary

The Solo System utilizes a robust, synchronous persistence strategy leveraging localStorage and the Intl.DateTimeFormat API. By centralizing all state in the systemData object and ensuring every mutation is followed by a save operation, the application maintains a reliable record of user progress and ensures the integrity of the daily quest and penalty mechanics.