Inactive Sessions Purging designed

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

@@ -0,0 +1,104 @@
+# 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.