# Troubleshooting

## Overview

This guide collects the most likely failure areas based on the current architecture and code paths.

## Quick symptom map

| Symptom | Likely area | First files to inspect |
| --- | --- | --- |
| App opens to auth after previously being signed in | token persistence or `401` session clear | `CurrentSessionProviderImpl.kt`, `JvmSecureTokenStore.kt`, `ThulurHttpClientFactory.kt` |
| Browser auth starts but app never finishes sign-in | browser callback flow | `BrowserPasskeyAuthenticator.jvm.kt` |
| Feed loads but articles do not reflect local read state | in-memory read cache merge | `InMemoryReadArticlesCache.kt`, `RemoteThulurApiRepository.kt`, `DailyFeedViewModel.kt` |
| Thread discussion button behaves unexpectedly | subscription tier gating | `AppRootScreenModel.kt`, `ThreadHistoryScreen` in `AppRouter.kt` |
| Settings change appears then reverts | optimistic patch failed | `SettingsViewModel.kt`, settings API methods |
| Chat feels slower than other requests | chat timeout is intentionally longer | `ThulurApiConfig.kt`, `GeneralChatMethod.kt`, `ThreadChatMethod.kt` |
| Article reader fails to render | JCEF runtime or web-view bridge | `JcefBrowserRuntime.jvm.kt`, `PlatformArticleWebView.jvm.kt`, article reader screen/ViewModel |

## Authentication issues

## Sign-in browser did not open

Check:

- whether the current desktop supports `Desktop.Action.BROWSE`
- `SystemBrowserLauncher` inside `BrowserPasskeyAuthenticator.jvm.kt`

If browser launching is unsupported, desktop auth cannot begin.

## Callback never arrives

The desktop auth flow depends on a temporary local HTTP server bound to:

- host: `127.0.0.1`
- path: `/auth/callback`

Inspect:

- whether the local server was able to bind
- whether the browser completed the passkey flow
- whether the callback `state` matches the expected generated value

## User is signed out unexpectedly

The Ktor client clears the current session on `401 Unauthorized`.

Inspect:

- `thulur_api/client/ThulurHttpClientFactory.kt`
- the failing backend endpoint
- whether the stored token is stale or invalid

## Token persistence issues

On JVM, secure persistence is preferred but not guaranteed.

Behavior:

- if secure token storage is available and truly secure, it is used
- otherwise the app falls back to `InMemorySecureTokenStore`

Consequence:

- users may stay signed in only for the current process lifetime on machines where secure storage is unavailable

Inspect:

- `domain/session/PlatformSecureTokenStore.jvm.kt`
- `data/session/JvmSecureTokenStore.kt`

## Daily feed and thread-history issues

## Wrong day, missing articles, or thread jump issues

Inspect:

- `DailyFeedViewModel.kt`
- `GetDailyFeedUseCase.kt`
- `DailyFeedMethod.kt`

Relevant behavior:

- feed navigation is day-based
- "more articles" can jump to another day and request focus for a thread
- thread history resolves the visible day from the originating feed day

## Read state looks inconsistent

Read state comes from two places:

- backend article `isRead`
- local in-memory read cache

Inspect:

- `RemoteThulurApiRepository.kt`
- `InMemoryReadArticlesCache.kt`
- `ArticleReaderViewModel.kt`

Remember that the read cache is in-memory only and is cleared when the session is cleared.

## Settings issues

## Settings revert after interaction

App settings use optimistic updates. A visible change can revert if the patch request fails.

Inspect:

- `SettingsViewModel.mutateAppSettings`
- `PatchUserSettingsUseCase.kt`
- `PatchSettingsMethod.kt`

## Account sessions do not refresh after termination

Inspect:

- `TerminateAuthSessionUseCase.kt`
- `SettingsViewModel.onTerminateSessionClick`
- `GetAuthSessionsMethod.kt`

## Feed follow/unfollow state looks stale

Inspect:

- `SettingsViewModel.onFollowFeedClick`
- `SettingsViewModel.onUnfollowFeedClick`
- `GetUserFeedsMethod.kt`
- `GetAllFeedsMethod.kt`

## Chat issues

## General chat or thread chat returns an error bubble

The UI intentionally replaces the pending assistant message with an error-flavored assistant message when the request fails.

Inspect:

- `ChatViewModel.kt`
- `SendGeneralChatMessageUseCase.kt`
- `SendThreadChatMessageUseCase.kt`
- chat transport methods

## Chat links open the wrong article mode

Inspect:

- `resolveChatArticleReaderTarget`
- `ChatArticleReaderTarget.kt`
- `ArticleReaderLaunchMode.kt`

The result may intentionally be browser fallback if the app cannot map a link to a tracked article.

## Article reader issues

## Reader opens but progress/rating is not sent

Submission is intentionally skipped when:

- launch mode is browser fallback
- no rating is set
- article is already marked read
- a submission is already in progress

Inspect:

- `ArticleReaderViewModel.submitRate`

## JCEF startup problems

Inspect:

- `jvmMain/presentation/dailyfeed/article_reader/JcefBrowserRuntime.jvm.kt`
- runtime directory under the user home folder: `.thulur/jcef-runtime`

The app prewarms JCEF at startup and disposes it at shutdown.

## Testing and navigation regressions

## Route-related breakages

Whenever screen identity or parameters change, run the route key tests in `jvmTest`.

Focus on:

- `DailyFeedRouteKeyTest.kt`
- `ThreadHistoryRouteKeyTest.kt`
- `ChatRouteKeyTest.kt`
- `SettingsRouteKeyTest.kt`
- `ArticleReaderScreenKeyTest.kt`

## Shared logic breakages

If a refactor touches repository mapping, DTOs, or use cases, prioritize:

- relevant `commonTest` transport method tests
- `RemoteThulurApiRepositoryTest.kt`
- affected use case tests
