---
sessionId: session-260701-224904-11t1
---

# Requirements

### Overview & Goals
Refactor the frontend session lifecycle so a new Pinia `sessionStore` becomes the single orchestrator for bootstrap, authenticated startup, initial private data loading, login, logout, gateway connection, and cleanup.

### In Scope
- Add `frontend/src/stores/session.ts` with `isBootstrapping`, `isReady`, and lifecycle actions.
- Refactor `authStore` to manage identity only.
- Refactor `appStore` to keep only global non-user app state such as `baseurl`.
- Refactor `gatewayStore` to manage WebSocket connection state only and remove global `window` orchestration events.
- Add `reset()` actions to `server`, `category`, `channel`, and `message` stores.
- Update app startup, router guards, login flow, and any logout call sites to use `sessionStore`.
- Verify backend WebSocket authentication remains enforced.

### Out of Scope
- Rewriting business data fetching APIs beyond moving initial orchestration into `sessionStore`.
- Adding a new UI design or a new full-screen loader component unless needed for compilation/runtime correctness.
- Changing backend auth semantics unless `/ws/gateway` is found not to reject unauthenticated users.

### Acceptance Criteria
- `authStore` no longer knows about gateway, bootstrap, or business stores.
- `gatewayStore` no longer dispatches or relies on `gateway:connected`/`gateway:disconnected` browser events.
- `appStore.initialize()` no longer orchestrates auth/gateway/data loading, and app startup uses `sessionStore.bootstrap()` instead.
- No WebSocket `/ws/gateway` connection is attempted for unauthenticated users.
- On login, user identity is loaded, gateway connects once, and `server`, `category`, and `channel` initial data are loaded once.
- On logout, gateway disconnects, private business stores reset, and `authStore.user` becomes `null`.
- Protected/admin routing still redirects correctly based on `authStore.isAuthenticated` and `authStore.isAdmin` after session readiness.

# Technical Design

### Current Implementation
- `frontend/src/stores/app.ts` currently imports `authStore`, `gatewayStore`, and business stores, defines `loadAppData()` inside `initialize()`, registers `window.addEventListener('gateway:connected', loadAppData)`, calls `gatewayStore.connect()` unconditionally, and loads `servers/categories/channels` from the event or connected status.
- `frontend/src/stores/auth.ts` exposes `user`, `isInitialized`, `initialize()`, and `logout()`. `initialize()` calls `GET /auth/me`; login is currently performed directly in `frontend/src/pages/auth/login.vue`.
- `frontend/src/stores/gateway.ts` builds `ws://.../ws/gateway` from `appStore.baseurl`, sets `status`, dispatches `window.dispatchEvent(new CustomEvent('gateway:connected'))`, and schedules reconnect on every close.
- `frontend/src/main.ts` currently calls `appStore.initialize()` before `app.mount('#app')`, without awaiting it.
- `frontend/src/router/index.ts` currently calls `authStore.initialize()` inside `beforeEach` when `!authStore.isInitialized`.
- Backend gateway route `src/routes/gateway/handlers.rs` requires `CurrentUser` in `ws_handler`, and `CurrentUser` rejects unauthenticated requests. However `src/routes/mod.rs` nests `/ws` routes outside `secure_routes`; protection therefore depends on global auth/context middleware in `src/http/server.rs`, which is currently applied globally.

### Key Decisions
- **Use a dedicated `sessionStore` orchestration layer.** It will be the only place that sequences `authStore.fetchCurrentUser()`, `gatewayStore.connect()`, business data loading, and cleanup.
- **Use bootstrap-before-mount as the primary startup model.** Existing `App.vue` has only `<router-view/>` and no loader UI, so `main.ts` will `await sessionStore.bootstrap()` before `app.mount('#app')`. Router guards will still be safe/idempotent by calling or awaiting `sessionStore.bootstrap()` only when needed.
- **Keep `appStore` for `baseurl` only.** `gatewayStore` still needs a base URL source for direct WebSocket URL construction, while `useApi.ts` currently uses Vite proxy path `/api`.
- **Make `authStore.login()` match the existing backend contract.** `POST /api/auth/login` returns `LoginResponse { token }`, not a user payload, so `authStore.login(username, password)` will post credentials and then call `fetchCurrentUser()` to populate `this.user` from `GET /auth/me`.
- **Prevent reconnect after intentional disconnect.** `gatewayStore.disconnect()` should close and clear the socket without scheduling an automatic reconnect that would violate logout cleanup.

### Proposed Data Flow
```mermaid
graph LR
  Main[main.ts] --> Session[sessionStore.bootstrap]
  Router[router guard] --> Session
  Login[login.vue] --> SessionLogin[sessionStore.login]
  Session --> Auth[authStore identity]
  Session --> Gateway[gatewayStore websocket]
  Session --> Stores[business stores]
  Logout[logout action] --> SessionLogout[sessionStore.logout]
  SessionLogout --> Gateway
  SessionLogout --> Stores
  SessionLogout --> Auth
```

### Proposed Changes
- Add `frontend/src/stores/session.ts`:
  - State: `isBootstrapping: false`, `isReady: false`.
  - `bootstrap()`:
    - return early if `isReady` or `isBootstrapping`;
    - call `authStore.fetchCurrentUser()`;
    - if `authStore.isAuthenticated`, call `startAuthenticatedSession()`;
    - set `isReady = true` in `finally`, and clear `isBootstrapping`.
  - `startAuthenticatedSession()`:
    - call `gatewayStore.connect()` idempotently;
    - call `loadInitialData()`.
  - `stopAuthenticatedSession()`:
    - call `gatewayStore.disconnect()`;
    - call `reset()` on `server`, `category`, `channel`, and `message` stores.
  - `loadInitialData()`:
    - run `serverStore.fetchServers()`, `categoryStore.fetchCategories()`, and `channelStore.fetchChannels()` in `Promise.all`.
  - `login(username: string, password: string)`:
    - delegate to `authStore.login(...)`;
    - call `startAuthenticatedSession()`.
  - `logout()`:
    - call `stopAuthenticatedSession()`;
    - call `authStore.logout()`;
    - preserve `isReady = true` for the current public session state.
- Refactor `frontend/src/stores/auth.ts`:
  - Remove `isInitialized` in favor of `sessionStore.isReady`.
  - Rename `initialize()` to `fetchCurrentUser()`.
  - Add `login(username: string, password: string)` using `api.post('/auth/login', { username, password })`, throwing usable errors for `401` and non-OK responses, then `fetchCurrentUser()`.
  - Make `logout()` call `POST /auth/logout` and always clear `this.user = null` in `finally`.
- Refactor `frontend/src/stores/app.ts`:
  - Remove imports of auth/gateway/business stores and the `initialize()` orchestration.
  - Keep `baseurl: 'http://localhost:8080'` unless a later cleanup moves it to config.
- Refactor `frontend/src/stores/gateway.ts`:
  - Keep WebSocket-only responsibilities: `connect`, `disconnect`, `send`, `handleMessage`, status tracking.
  - Make `connect()` return early for `connecting` and `connected`.
  - Remove `window.dispatchEvent('gateway:connected')`.
  - Add an internal intentional-close guard or equivalent so `disconnect()` does not trigger `scheduleReconnect()`.
- Add reset actions:
  - `server.ts`: `servers = []`.
  - `category.ts`: `categories = []`.
  - `channel.ts`: `channels = []`, `loading = false`, `error = null`.
  - `message.ts`: `messages = []`.
- Update startup/routing/UI:
  - `frontend/src/main.ts`: import `useSessionStore`, call `await sessionStore.bootstrap()`, then mount.
  - `frontend/src/router/index.ts`: import `useSessionStore`; replace `authStore.isInitialized/authStore.initialize()` with waiting for `sessionStore.isReady` or `await sessionStore.bootstrap()`; keep auth/admin decisions in terms of `authStore.isAuthenticated` and `authStore.isAdmin`.
  - `frontend/src/pages/auth/login.vue`: remove direct `useApi()` and `useAuthStore()` login flow; call `sessionStore.login(username.value, password.value)` and redirect to `/`.
  - Search for any direct logout usages; replace them with `sessionStore.logout()` and route to `/auth/login` where present.

### Backend Security Check
- Confirm `src/routes/gateway/handlers.rs` keeps `CurrentUser(user): CurrentUser` in the WebSocket handler.
- Confirm global middleware order in `src/http/server.rs` continues to inject `RequestContext` and optional auth before `/ws/gateway` handlers run.
- If testing shows unauthenticated WebSocket upgrade succeeds, explicitly layer `middleware::require_auth` onto `ws_routes` in `src/routes/mod.rs` or equivalent.

# Testing

### Validation Approach
- Run frontend type checking/build validation using the existing frontend scripts where available (`npm run type-check`, and build if needed).
- Run targeted manual browser/network validation for bootstrap, login, logout, and routing flows.
- Run or compile backend checks only if backend route/middleware code changes are required.

### Key Scenarios
- **Unauthenticated visitor:** `GET /api/auth/me` is attempted, no `/ws/gateway` connection is opened, no private data endpoints are loaded, and protected routes redirect to `/auth/login`.
- **Authenticated page load:** `GET /api/auth/me` succeeds, one `/ws/gateway` connection opens, initial `servers/categories/channels` loads once, and protected routes render.
- **Login:** login page calls `sessionStore.login()`, user becomes authenticated, gateway connects, initial data loads, and the user is redirected to `/`.
- **Logout:** gateway closes without reconnecting, business stores are empty, `authStore.user` is `null`, and the user is redirected to a public route.
- **Double bootstrap / navigation:** repeated guard invocations or main startup do not create duplicate gateway connections or duplicate initial data loads.

### Regression Checks
- `gateway:connected` and similar global event usages are absent from `frontend/src` after refactor.
- `authStore.initialize` and `authStore.isInitialized` references are absent after migration.
- Router admin checks continue to use `authStore.isAdmin` after session readiness.

# Delivery Steps

### ✓ Step 1: Introduce session lifecycle store
A new `sessionStore` owns bootstrap, authenticated startup, initial data loading, and teardown.

- Add `frontend/src/stores/session.ts` as a Pinia store named `session`.
- Implement `isBootstrapping` and `isReady` state with idempotent `bootstrap()` behavior.
- Wire `bootstrap()` to `authStore.fetchCurrentUser()` and conditionally `startAuthenticatedSession()`.
- Implement `startAuthenticatedSession()`, `stopAuthenticatedSession()`, `loadInitialData()`, `login(...)`, and `logout()` using existing auth, gateway, and business stores.
- Ensure initial private data loading uses `Promise.all` for servers, categories, and channels.

### ✓ Step 2: Separate auth, gateway, and app store responsibilities
`authStore`, `gatewayStore`, and `appStore` each have a single responsibility and no longer perform cross-store orchestration.

- Update `frontend/src/stores/auth.ts` by replacing `initialize()`/`isInitialized` with `fetchCurrentUser()` and identity-only state/getters.
- Add `authStore.login(username, password)` that posts to `/auth/login`, handles 401/non-OK errors, then fetches the current user because the backend login response returns a token payload.
- Make `authStore.logout()` call `/auth/logout` and clear `user` in `finally`.
- Update `frontend/src/stores/gateway.ts` so `connect()` is idempotent for both `connecting` and `connected` states.
- Remove `window.dispatchEvent('gateway:connected')` and any event-driven loading from the gateway store.
- Make `disconnect()` intentionally close and clear the socket without scheduling reconnect.
- Simplify `frontend/src/stores/app.ts` to retain only global non-session state such as `baseurl`.

### ✓ Step 3: Add private-data reset support
Business stores can be reliably cleared during logout and user switching.

- Add `reset()` to `frontend/src/stores/server.ts` to clear `servers`.
- Add `reset()` to `frontend/src/stores/category.ts` to clear `categories`.
- Add `reset()` to `frontend/src/stores/channel.ts` to clear `channels`, `loading`, and `error`.
- Add `reset()` to `frontend/src/stores/message.ts` to clear `messages`.
- Use these reset actions from `sessionStore.stopAuthenticatedSession()`.

### ✓ Step 4: Route app startup and auth UI through sessionStore
Application bootstrap, route guards, login, and logout entry points use `sessionStore` as the orchestration boundary.

- Update `frontend/src/main.ts` to create the app, register plugins, call `await useSessionStore().bootstrap()`, then mount.
- Update `frontend/src/router/index.ts` to wait for or trigger `sessionStore.bootstrap()` before auth/admin decisions.
- Keep route authorization checks based on `authStore.isAuthenticated` and `authStore.isAdmin` after session readiness.
- Update `frontend/src/pages/auth/login.vue` to call `sessionStore.login(username.value, password.value)` instead of manually posting with `useApi()` and calling `authStore.initialize()`.
- Search for direct logout usages and route them through `sessionStore.logout()` with redirect to `/auth/login` where UI logout actions exist.

### ✓ Step 5: Verify security and regressions
The refactor is validated against frontend lifecycle behavior and backend WebSocket authentication guarantees.

- Confirm no `gateway:connected`, `window.addEventListener`, or `window.dispatchEvent` orchestration remains in `frontend/src`.
- Confirm no references to `authStore.initialize` or `authStore.isInitialized` remain.
- Run frontend type checking/build validation using existing scripts.
- Manually validate unauthenticated load, authenticated load, login, logout, and double-bootstrap scenarios via browser/network behavior.
- Verify `/ws/gateway` still rejects unauthenticated users through `CurrentUser`; if not, add explicit auth protection to the backend WebSocket route.