Feature: Focus Sessions

Relevant source files

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

• client/products/pointron/focus/session.store.ts
• client/products/pointron/focus/session.utils.ts
• client/types/pointron/session.type.ts
• client/landing/routes/+page.server.ts
• WARP.md
• README.md

The Focus Sessions feature is the core mechanism for time and focus management within the Pointron application. It provides a flexible and robust system for users to track time spent on various activities, goals, and tasks. The system is designed to be highly customizable, supporting multiple focus methodologies to suit different user workflows.

This feature allows users to start, pause, resume, and complete timed sessions, which are then logged for analytics and progress tracking. It supports several focus methods, including the Pomodoro technique, simple count-up and count-down timers, and sessions that run until a specific end time. This functionality is central to Pointron's value proposition as a tool for enhancing productivity and focus.

Sources: README.md, WARP.md, client/landing/routes/+page.server.ts:657-662

Core Data Model

The entire Focus Session feature is built around a central data structure, IFocusSession, which captures all the necessary information about a single session. This model is supported by several enumerations that define the session's state, method, and other characteristics.

Sources: client/types/pointron/session.type.ts

IFocusSession Interface

This interface is the primary data model for a focus session.

Property	Type	Description
id	string	A unique identifier for the session.
method	FocusMethod	The timing method used for the session (e.g., Pomodoro, Countdown).
state	SessionState	The current state of the session (e.g., Ready, Running, Paused).
startTime	number (timestamp)	The time the session was started.
endTime	number (timestamp)	The time the session was completed or is scheduled to end.
duration	number (milliseconds)	The total intended duration of the session.
goal	IGoal (optional)	The goal associated with this focus session.
pomodoros	IPomodoro (optional)	Specific data for a Pomodoro session, including rounds and breaks.
pauses	Array<{ start: number; end: number }>	An array of objects recording the start and end times of each pause.
createdAt	number (timestamp)	The time the session object was created.
updatedAt	number (timestamp)	The time the session object was last updated.

Sources: client/types/pointron/session.type.ts:33-51

Enumerations

Several enums define the possible states and methods for a focus session.

Enum	Values	Description
FocusMethod	POMODORO, COUNT_UP, COUNT_DOWN, END_TIME	Defines the different types of focus timers available.
SessionState	READY, RUNNING, PAUSED, COMPLETED	Represents the lifecycle state of a session.
PomodoroState	FOCUS, BREAK	Defines the state of a single round within a Pomodoro session.

Sources: client/types/pointron/session.type.ts:4-24

Data Model Diagram

The following diagram illustrates the relationships between the main data structures for a Focus Session.

State Management

The state of the active focus session is managed by a Svelte writable store, sessionStore. This store provides a reactive, centralized point of control for the UI to interact with and respond to changes in the session's lifecycle.

Sources: client/products/pointron/focus/session.store.ts

Session Store (sessionStore)

The sessionStore holds the current IFocusSession object or null if no session is active. A set of exported functions manipulates this store, ensuring that state transitions are handled consistently.

Key functions include:

• startSession(session: IFocusSession): Sets the session state to RUNNING and updates the store.
• pauseSession(): Sets the session state to PAUSED and records the pause start time.
• resumeSession(): Sets the session state back to RUNNING and records the pause end time.
• completeSession(): Sets the session state to COMPLETED and records the session end time.
• resetSession(): Resets the store to its initial state (null).

Sources: client/products/pointron/focus/session.store.ts:10-58

Session State Lifecycle

A session progresses through a well-defined set of states, managed by the sessionStore functions.

The diagram below shows the possible state transitions for a focus session.

Interaction Flow

This sequence diagram illustrates a typical user interaction flow for starting, pausing, and completing a session.

Session Utilities

Helper functions for creating and managing session-related data are located in session.utils.ts. These utilities abstract the logic for session creation and data formatting.

Sources: client/products/pointron/focus/session.utils.ts

Session Creation

The createFocusSession function is responsible for initializing a new IFocusSession object based on user-provided settings (IFocusSessionCreate).

// client/products/pointron/focus/session.utils.ts:11-30
export function createFocusSession(
  session: IFocusSessionCreate
): IFocusSession {
  const now = Date.now();
  return {
    id: `ses_${nanoid(10)}`,
    state: SessionState.READY,
    method: session.method,
    startTime: 0,
    endTime: 0,
    duration: session.duration,
    goal: session.goal,
    pomodoros: session.pomodoros,
    pauses: [],
    createdAt: now,
    updatedAt: now
  };
}

Sources: client/products/pointron/focus/session.utils.ts:11-30

Other Utilities

• getFormattedTime(time: number): Formats a time value in milliseconds into a human-readable string (e.g., HH:MM:SS).
• getCompletionPercentage(session: IFocusSession): Calculates the completion progress of a session, with logic tailored to the specific FocusMethod being used.

Sources: client/products/pointron/focus/session.utils.ts:32-61

Focus Methods

Pointron supports several distinct methods for focus tracking, catering to different user preferences and workflows.

Sources: client/landing/routes/+page.server.ts:658-659, client/types/pointron/session.type.ts:4-8

Method	FocusMethod Enum	Description	Key Properties in IFocusSession
Pomodoro	POMODORO	A cyclical method involving focused work intervals followed by short breaks.	pomodoros
Countdown	COUNT_DOWN	A session that runs for a predefined duration and counts down to zero.	duration
Count-up	COUNT_UP	A session that starts from zero and runs until manually stopped by the user.	duration (can be 0)
End Time	END_TIME	A session that runs until a specific, predefined time of day.	endTime