:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Architecture
Directory map
products/mobile/
app/ Expo Router routes. Thin: read params, mount a screen.
_layout.tsx Providers (gesture handler, safe area, keyboard, TanStack Query), auth gate,
push registration, notification routing, analytics, error boundary
+native-intent.tsx Drops the Android OAuth callback deep link so it never opens a screen, and opens a web
link to one issue or recording at /errors/<id> or /replay/<id> (webLinkTarget)
index.tsx Redirect to /inbox (demo mode or signed in) or /sign-in
sign-in.tsx -> src/auth/SignInScreen
(tabs)/ Inbox and Chats share one tab navigator, so the bottom bar stays put when the tab changes
_layout.tsx -> src/features/tabs/TabsLayout
inbox.tsx -> src/features/inbox/InboxScreen
chats.tsx -> src/features/chats/ChatsScreen
errors.tsx -> src/features/errors/ErrorsListScreen chrome="tab" (a slot only while pinned)
replay.tsx -> src/features/replay/ReplayListScreen chrome="tab" (a slot only while pinned)
report/[id]/index.tsx -> src/features/report/ReportScreen (`/report/<id>`, as deep links and notifications open it)
report/[id]/details.tsx -> src/features/report/details/ReportDetailsScreen (the full report)
(stack)/errors/index.tsx -> src/features/errors/ErrorsListScreen chrome="stack" (pushed from the Views Browse row)
errors/[id].tsx -> src/features/errors/IssueScreen (`/errors/<id>`, `from` names the source for analytics)
(stack)/replay/index.tsx -> src/features/replay/ReplayListScreen chrome="stack" (pushed from the Views Browse row)
replay/[sessionId].tsx -> src/features/replay/SessionScreen (`/replay/<id>?t=<seconds>&source=<entry>`)
chat.tsx -> src/features/chat/ChatSheet (transparent modal, draws its own sheet;
no params starts a new chat, `taskId` and `runId` open one, `reportId` attaches a report)
settings.tsx -> src/features/settings/SettingsScreen
src/
api/ client.ts (fetch wrapper: base URL, bearer, refresh on 401, mobile header),
sse.ts (event-stream parser and reader), queryClient.ts, and one typed
module per backend domain: users, reports, today, tasks,
pushTokens. Each module declares the response fields it reads and names
the serializer it mirrors.
errorTracking.ts holds the error tracking reads and writes ([API.md](API.md#error-tracking)).
recordings.ts and replayVision.ts hold the session replay reads and Summarize
([API.md](API.md#session-replay)).
auth/ oauth.ts (PKCE flow, refresh, revoke), tokens.ts (secure store),
account.ts (@me and projects), regions.ts (hosts and client ids),
authStore.ts (zustand), useViewer, SignInScreen
model/ types.ts (the view-model contract), sources.ts, agent.ts, queryStates.ts,
adapters/ (Today and signals responses -> view models)
demo/ briefings.ts (raw prototype data), fixtures.ts (view models), derive.ts,
demoMode.ts (zustand store), hooks.ts (demo query hooks),
sessionThreads.ts (demo session run logs)
features/
tabs/ TabsLayout (Inbox, Chats and Views tab navigator), BottomBar and TabsHeader (each
rendered once), tabHeaderStore (each tab's header state), NavMenu (the More menu),
navPinStore (Errors and Sessions pinned to the nav pill, a device preference),
navPinRoutes (openNavTarget: the explicit (tabs) route when pinned, (stack) when not;
both keep the public /errors and /replay URLs, without selecting a hidden native tab),
navPinActions (pin change with toast and Undo), NavPinMenu (the Views row menu)
inbox/ InboxScreen, InboxRow, InboxListFooter, hooks,
prefetchPlan (prefetch window and queue), usePrefetchReports
report/ ReportScreen, TopChrome, Headline, HeadlineTitle, ReportMeta, ReportByline, TextLinkRow,
Evidence*, ReplayRow, Facts, Activity,
hooks, queries (query options shared by the screen and the inbox prefetch)
metrics/ ObservationCard, ImpactMetrics, ReportCharts, OpenInsightLink, query and value hooks
details/ ReportDetailsScreen (the full report) and its sections, ReportMarkdown, chartRefs
(markdown-it plugin), openDetailsLink
handoff/ ActionBar and its cards, HandoffSheet, actionBarState, kickoff, prompt,
runStream (reducer), toolPolicy, permissionRequest, commands, useTaskRun,
useReportWithLiveRun, handoffStore, hooks
snooze/ SnoozeSheet, CustomSnoozePicker (.web.tsx for web), snoozeTimes,
snoozeStore, snoozeEntries, reminders, hooks
verdict/ VerdictSheet (Resolve and Dismiss), verdictCopy, hooks; reasons in model/verdictReasons
reviewers/ AssigneeSheet, hooks
priority/ PrioritySheet, hooks
chat/ ChatSheet, Composer, ContextChip, MentionPopover, ChatEmptyState, ChatOptionsSheet,
chatRunOptions (model and mode), ChatMarkdown, ChatErrorBubble, ChatProgressLine,
UserBubble, contextPrompt, chatErrors, webLinks (reply links),
objectContext and ObjectContextChip (an issue or recording as chat context)
session/ useSession (create, follow, send, resume, stop, answer), sessionRun (request bodies
and the set_config_option plan), sessionReducer, sessionDisplay, SessionThread and its
rows, SessionDecisionPanel
errors/ ErrorsListScreen, IssueListRow, IssueScreen, IssueSections, IssueActionBar, IssueAssigneeSheet,
SuppressSheet, IssueBadges, AssigneeAvatar,
hooks (react-query reads, optimistic status and assign), issueModel (pure adapters: rows,
badges, frames, sessions, breakdowns, web links, empty copy), analytics
replay/ ReplayListScreen, SessionListRow, SessionScreen, SessionChrome (Back, Open full replay, More),
SummaryCard, ChapterList, FrameSheet, FrameImage (signed frame URLs),
SessionTimelineSection, SessionSkeleton, hooks (recording, timeline, summary flow with
Summarize and polling, frames, list), sessionAdapters (pure: person labels, timeline,
summary, list rows), replayModel (view types), replayLinks (web URLs, `t`), replayAnalytics
views/ The Views tab and its screens, see VIEWS.md
screen/ Shared screen chrome: ViewChrome, ViewScreenFrame, ViewTitle, HeaderMenu (the More menu
of a pushed screen: a view, an issue, a session), ViewMoreSheet, ViewErrorState, ViewSkeleton
chats/ ChatsScreen, ChatRow, ChatRowMenu (long-press Archive),
chatGroups (day labels, grouping, search), sessionStatus, hooks
notifications/ pushSupport, pushStore, pushRegistration, usePushRegistration,
notificationRouting, taskLookup, useNotificationRouting
settings/ SettingsScreen, ProjectSwitcher, PushStatusGroup, SignOutSection, appInfo,
EnvironmentGroup (internal builds), LegalGroup, SettingsLinkRow, SettingsRadioRow,
DefaultPageGroup, defaultPageStore (the tab the app opens on)
widgets/ chartWidgetSync (session copy and pin catalog for the Chart home screen widget),
chartWidgetCatalog (buildCatalog), useChartWidgetSync, useWidgetOpenedEvent;
see modules/chart-widget/README.md
lib/ analytics, posthogClient, dates, errors, haptics, markdownIt (the shared safe parser),
deepLinkKind (link kind for analytics, webLinkTarget for issue and recording links),
richText, useAsyncAction, useNow,
environment (build variant, host kind, update id), appVariants (+ .json), legalLinks
ui/ tokens.ts, primitives (SearchField, StateView, ...), icons/
plugins/ Expo config plugins (withIosSceneLifecycle: UIScene life cycle for Xcode 27)
.argent/flows/ Argent flows that drive the app on a simulator (see TESTING.md)
assets/ app icon (shared with PostHog Desktop), adaptive icon, splash, favicon, badged dev and
preview icons
scripts/ eas-build.sh, make_variant_icons.py
Data flow
route (app/) -> feature screen -> feature hooks -> useDataMode()
├─ 'loading' -> loading QueryState
├─ 'demo' -> src/demo (fixtures + useDemoMode store)
└─ 'live' -> src/api fetchers + TanStack Query
-> src/model/adapters -> view models
Screens render only the types in src/model/types.ts.
Every data hook returns QueryState<T>, which TanStack Query's UseQueryResult<T> satisfies.
useDataMode() waits for the persisted demo flag to load, so a cold start never flashes an error.
The report screen reads useReportWithLiveRun(id), which takes useReport(id) and overlays the
live task run (status, stage, pending question, PR URL) and the hand-off prompt.
The footer reads independent execution, attention and PR state from the pure
actionBarStateFor(report, local) in features/handoff/actionBarState.ts. The focused report
polls lightweight report/artefact/task snapshots in the foreground; stream changes trigger
throttled invalidations without refetching on message chunks.
The full report reads useReport(id) without polling. It shares the report screen's cache,
so it renders at once and refreshes once when it opens.
Mutations go through useAsyncAction, which exposes a pending flag and drops a second call
while one is in flight. Buttons read the flag to disable and show progress.
Hand-off and decision actions resolve on failure and surface the error through
useHandoffNotice, so the footer shows one line instead of an alert.
Live data sources
| Need | Source | Fallback |
|---|---|---|
| Inbox rows | GET signals/reports/?view=for_you&sort=priority&limit=20&offset= one page at a time |
Loads more while the response has a next link |
| Report page | GET signals/reports/{id}/, /signals/, /artefacts/, GET today/reports/{id}/page/ |
Signals only when the Today page is unavailable |
| Selected PR checks | GET signals/reports/{id}/pr_checks/?pull_request_id={canonicalPrId} |
No id or failed/missing checks stay unavailable; focused foreground polling at 30 seconds |
| Current run | GET tasks/{taskId}/ then GET .../runs/{runId}/stream/ (SSE) |
Bounded reconnects and focused foreground task polling, including later resumes |
| New chat | POST tasks/ then POST tasks/{id}/run/ (mode: interactive) |
A refused run deletes the new task |
| Follow-up | POST tasks/{id}/runs/{run}/command/ (set_config_option for changed options, then user_message) |
POST tasks/{id}/run/ with resume_from_run_id when the run ended |
| Chats list | GET tasks/?created_by={user id}&ordering=-last_activity_at&basic=true&limit=30 |
A 403 or 404 means no sessions |
| Chat thread | GET tasks/{id}/ then GET tasks/{id}/runs/{run}/logs/ for an ended run, or GET tasks/{id}/runs/{run}/stream/ for a live one |
A failed load shows Try again; demo sessions come from src/demo/sessionThreads.ts |
| Reviewers | GET signals/reports/available_reviewers/, PUT signals/reports/{id}/reviewers/ |
none |
| Priority | POST signals/reports/{id}/artefacts/ (priority_judgment) |
none |
| Snooze | POST signals/reports/{id}/state/ for "until more signals"; on-device store for times |
none |
| Read state | POST signals/reports/read_state/ |
none |
| Push | POST /api/users/@me/push_tokens/ |
unavailable on web and Expo Go |
Details per domain: DATA.md, HANDOFF.md, CHAT.md, PUSH.md.
Hook surface
| Hook | File | Returns |
|---|---|---|
useInboxItems() |
features/inbox/hooks.ts |
InboxQueryState: QueryState<InboxItem[]> plus hasMore, isLoadingMore, loadMoreFailed, loadMore |
useMarkReadAction(id), useMarkReadOnOpen(id) |
features/inbox/hooks.ts |
AsyncAction<[]>, void |
usePrefetchReports(items) |
features/inbox/usePrefetchReports.ts |
{ onViewableItemsChanged, viewabilityConfig } for the inbox FlatList |
useReport(id) |
features/report/hooks.ts |
QueryState<ReportView> |
useReportWithLiveRun(id) |
features/handoff/useReportWithLiveRun.ts |
QueryState<ReportView> with the live run merged in |
useReportActions(id) |
features/report/hooks.ts |
ReportActions (handOff, answerDecision, undoDecision, snooze, setReviewers, setPriority, markRead, pending) |
useReportNeighbors(inbox, id) |
features/report/hooks.ts |
{ previousId, nextId }, wrapping only when every page is loaded; loads the next page on the last loaded report |
useMetricSeries(data), useMetricAggregate(data) |
features/report/metrics/hooks.ts |
QueryState<MetricSeries>, QueryState<number> from the query endpoint or fixture data |
useMetricValue(metric) |
features/report/metrics/useMetricValue.ts |
MetricValueState: the live value, else the snapshot with its measured time |
useChartPoints(data, fallback?) |
features/report/metrics/useChartPoints.ts |
{ points, isLoading, isError } for MetricChart, from live buckets or the snapshot series |
useHandoffActions(id), useDecisionAnswer(id), useHandoffNotice(id) |
features/handoff/hooks.ts |
actions, the device-side answer, the footer error line |
usePullRequestChecks(reportId?, pullRequestId?, enabled?) |
features/handoff/usePullRequestChecks.ts |
status, local observedAt, isRefreshing |
useTaskRun(reportId, target, enabled, onRefresh?, onTaskSnapshot?) |
features/handoff/useTaskRun.ts |
void; follows the current run into the report store, with scoped connection state |
useSnoozeAction(id), useSnoozeEntries() |
features/snooze/hooks.ts |
AsyncAction<[SnoozeChoice]>, active snoozes |
useAvailableReviewers(query) |
features/reviewers/hooks.ts |
QueryState<Person[]> |
useSetReviewersAction(id) |
features/reviewers/hooks.ts |
AsyncAction<[string[]]> (full replace) |
useSetPriorityAction(id) |
features/priority/hooks.ts |
AsyncAction<[ReportPriority]> |
useSession({ taskId?, runId? }) |
features/chat/session/useSession.ts |
Session: taskId, runId, title, items, invocations, phase, history, decision, runConfig, notice, unsentText, isSending, isStopping, start(text, context, options?), send(text, context, options?), stop, answer, reset, reloadHistory |
useChatList() |
features/chats/hooks.ts |
QueryState<ChatListItem[]> |
useArchiveChat() |
features/chats/hooks.ts |
ChatArchiveActions (archive, restore), both optimistic on the cached list |
usePushRegistration(), useNotificationRouting() |
features/notifications/ |
registers the device, routes taps |
useViewer() |
auth/useViewer.ts |
{ name, projectName } |
Stores
useAuthStore(src/auth/authStore.ts, zustand, non-secret state persisted with AsyncStorage, tokens in the secure store):status,signedIn,region,host,clientId,method,user,organizations,projects,projectId,projectName,signedOutReason; actionsrestore,signIn,signInWithPersonalApiKey(dev builds),selectProject,reloadAccount,signOut. It installs the auth provider thatsrc/api/client.tsuses for the base URL, bearer token and refresh.useDemoMode(src/demo/demoMode.ts, persists onlyenabled): in-memory demo state for hand-offs, decisions, snoozes, read flags, reviewers and the activity log.useSnoozeStore(src/features/snooze/snoozeStore.ts, persisted): time and signal-count snoozes keyed by host, project and report, with expiry.useHandoffStore(src/features/handoff/handoffStore.ts): the task and run a hand-off started on this device, pending answers and the footer notice.usePushStore(src/features/notifications/pushStore.ts, persisted): permission state and the registered token.
Offline read cache
src/features/offlineCache.ts scopes persistence to the verified account and project.
src/api/readCache.ts restores and tracks eligible TanStack queries.
src/api/readCacheStore.ts enforces limits and stores each entry through src/lib/secureStorage.ts.
Native builds use SecureStore; the web preview uses memory.
The allowlist covers aggregate Views and the first 20 Inbox rows, including signal counts. It excludes report bodies, transcripts, actor rows, searches, SQL results, and mutations. Inbox snapshots use a separate read-only query.
- Limits: 24-hour TTL, 24 entries per project, 32 KiB per entry, 128 KiB per project, and eight projects per account. Size limits measure UTF-8 JSON.
- Freshness: Preserve successful capture times across failed refreshes, metadata updates, and pagination. Query garbage collection leaves disk entries intact.
- Restoration: Require the matching host, user, and project. Keep newer live data. Retry failed reads before replacement saves resume.
- Access: Evict denied data from its original project, including late responses after a project switch. Missing Views scopes purge Views across the account. Sign-out clears the account cache.
- Storage: Write only changed entries. Serialize operations per key and journal unfinished chunks until cleanup succeeds. The adapter is shared with chat drafts; cache eviction preserves drafts.
Module boundaries
app/imports screens only.src/uiholds generic primitives and imports nothing fromfeatures,demo,authorapi. It imports theAccenttype fromsrc/model.src/model/types.tsimports nothing.src/model/adaptersimports the API types insrc/apiand helpers insrc/lib, and nothing fromfeatures.src/apiimports nothing fromfeatures,demoorauth(the auth provider is injected).src/features/*may importsrc/model,src/ui,src/lib,src/apiand other features' hooks. The app's shared screen chrome is the exception:src/features/views/screen/*,ViewsToastandViewsReauthStatemay be imported by other features. Fixtures reach screens only through hooks. Screens import theuseDemoModestore directly only to turn demo mode on or off.src/demoimportssrc/modeland nothing fromfeatures.