unisono/specs/009-inactive-sessions-purging/spec.md

# Feature Specification: Inactive Sessions Purging, Form Data Persistence, and Centralized Snackbars

**Feature Branch**: `009-inactive-sessions-purging`  
**Created**: четверг, 16 октября 2025 г.  
**Status**: Draft  
**Input**: User description: "Inactive sessions purging. 1. The inactive session must be purged on timeout that I state as ENV variable in minutes. 2. Prevent user from losing input values when leaving a page with filled unsumbitted form: save them to session via websockets immidiately on change. 3. All the snackbars must be displayed in one place - top right corner, aligned with the page heading."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - System purges inactive sessions (Priority: P1)

As a system administrator, I want inactive user sessions to be automatically purged after a configurable timeout, so that system resources are optimized and security risks from stale sessions are minimized.

**Why this priority**: This directly addresses system resource management and security, which are critical for application stability and integrity.

**Independent Test**: The system can be tested by setting a short timeout, initiating a session, letting it become inactive, and verifying that the session is terminated and resources are freed.

**Acceptance Scenarios**:

1. **Given** a session timeout is configured via an environment variable (e.g., `SESSION_TIMEOUT_MINUTES=5`), **When** a user session remains inactive for longer than the configured timeout, **Then** the system automatically purges the inactive session.
2. **Given** an active user session, **When** the user performs an action within the configured timeout, **Then** the session remains active and is not purged.

---

### User Story 2 - User input values are persisted across navigation (Priority: P1)

As a user, I want my unsubmitted form input values to be automatically saved to my session as I type, so that I don't lose my work if I accidentally navigate away from a page or my browser crashes.

**Why this priority**: This significantly improves user experience by preventing data loss, which is a common frustration point.

**Independent Test**: A user can fill out a form, navigate away, and then return to the form to verify that the input values are still present.

**Acceptance Scenarios**:

1. **Given** a user is filling out a form with input fields, **When** the user types into an input field, **Then** the value of that input field is immediately saved to the user's session via WebSocket.
2. **Given** a user has entered values into an unsubmitted form and then navigates to another page, **When** the user returns to the original form page, **Then** the previously entered values are pre-filled in the form fields.
3. **Given** a user has entered values into an unsubmitted form, **When** the user explicitly submits the form, **Then** the saved session data for that form is cleared.

---

### User Story 3 - Snackbars are consistently displayed (Priority: P2)

As a user, I want all system notifications (snackbars) to appear in a consistent location (top right corner, aligned with page heading), so that I can easily locate and dismiss them without disrupting my workflow.

**Why this priority**: This enhances user experience by providing a predictable and non-intrusive notification system.

**Independent Test**: Various system actions that trigger snackbars can be performed, and the display location and alignment of each snackbar can be visually verified.

**Acceptance Scenarios**:

1. **Given** any system action triggers a snackbar notification, **When** the snackbar is displayed, **Then** it appears in the top right corner of the screen.
2. **Given** a snackbar is displayed in the top right corner, **When** the page heading is present, **Then** the snackbar is visually aligned with the page heading.
3. **Given** multiple snackbars are triggered in quick succession, **When** they are displayed, **Then** they stack or queue in the top right corner without overlapping other critical UI elements.

---

### Edge Cases

- What happens if the WebSocket connection is interrupted while a user is typing in a form? (Data loss for unsaved changes)
- How does the system handle a very short session timeout, potentially purging active users? (Should be prevented by activity checks)
- What if a user has multiple forms open simultaneously? (Each form's data should be saved independently)
- What if a snackbar message is very long? (Should wrap or truncate gracefully)

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The system MUST automatically purge user sessions that have been inactive for a configurable duration.
- **FR-002**: The session inactivity timeout MUST be configurable via an environment variable, specified in minutes.
- **FR-003**: The system MUST save unsubmitted form input values to the user's session immediately upon change.
- **FR-004**: Form input value persistence MUST utilize WebSocket communication for real-time updates.
- **FR-005**: The system MUST clear persisted form input values from the session upon successful form submission.
- **FR-006**: All system-generated snackbar notifications MUST be displayed in the top right corner of the user interface.
- **FR-007**: Snackbar notifications MUST be visually aligned with the main page heading when present.
- **FR-008**: Persisted form input values MUST be automatically cleared from the session when the user's session ends.
- **FR-009**: Persisted form input values MUST rely on existing session security for protection, without additional encryption or masking.
- **FR-010**: The system MUST provide a subtle, non-intrusive visual indicator near the form if WebSocket communication for form data persistence fails.
- **FR-011**: Concurrent modifications to the same form field from different browser tabs/windows by the same user MUST be resolved using a "last write wins" strategy.

### Key Entities

- **Session**: Represents a user's active interaction with the application, containing user-specific data including persisted form inputs.
- **Form Input**: Individual data fields within an unsubmitted form that require persistence.
- **Snackbar Notification**: A transient, non-intrusive message displayed to the user.

## Clarifications

### Session 2025-10-16

- Q: When should persisted form input data be automatically cleared from the session if the form is never submitted? → A: When the user's session ends
- Q: What level of data protection (e.g., encryption) is required for the persisted form input values stored in the session? → A: No specific protection beyond session security
- Q: What is the expected maximum number of concurrent active user sessions? → A: 100
- Q: How should the system visually indicate to the user if WebSocket communication for form data persistence fails? → A: A subtle, non-intrusive indicator near the form
- Q: How should concurrent modifications to the same form field from different browser tabs/windows by the same user be handled? → A: Last write wins

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: System resource utilization (CPU, memory) for inactive sessions is reduced by at least 20% within 24 hours of deploying the session purging feature.
- **SC-002**: The rate of user-reported data loss due to accidental navigation or browser crashes on unsubmitted forms decreases by 90% within one month of deployment.
- **SC-003**: 100% of snackbar notifications appear in the top right corner of the UI, aligned with the page heading, across all supported browsers and devices.
- **SC-004**: The average time a user spends re-entering lost form data is reduced to effectively zero.
- **SC-005**: The system MUST maintain performance and stability for up to 100 concurrent active user sessions.