Settings & Authentication UI
Relevant source files
The following files were used as context for generating this wiki page:
The Settings & Authentication UI in OpenPoke provides the interface for user personalization and third-party integration management. It primarily handles the configuration of the user's timezone and the OAuth-based connection to Gmail via the Composio platform. This module ensures that the assistant has the necessary permissions and temporal context to perform tasks like email drafting, searching, and scheduling.
The system is built as a Next.js client-side modal component supported by specialized API routes that proxy requests to a backend FastAPI server. It manages local state persistence using localStorage to maintain session continuity and connection status.
Core Components and State Management
Settings Hook and Persistence
The useSettings custom hook serves as the primary mechanism for managing user-specific configuration. It initializes settings from localStorage and provides a persist function to update values both in React state and local storage.
Sources: web/components/SettingsModal.tsx:10-31
| State Field | Type | Description |
|---|---|---|
timezone | string | The IANA timezone string (e.g., "America/New_York"). |
openpoke_user_id | string | A unique identifier for the web session, generated via crypto.randomUUID or a fallback. |
gmail_connected | boolean | Flag indicating if a valid Gmail connection exists. |
gmail_email | string | The email address of the connected Gmail account. |
Sources: web/components/SettingsModal.tsx:125-180
User Identification
To maintain a consistent identity across sessions without a formal login system, the UI generates and stores a userId. If no ID is found in localStorage, the system generates a new one prefixed with web-.
The diagram shows the logic for ensuring a unique user identifier is present for API calls.
Sources: web/components/SettingsModal.tsx:142-162
Timezone Configuration
Timezone management is critical for the assistant's ability to interpret relative time phrases and schedule triggers accurately.
- Detection: On initial load, the
Pagecomponent usesIntl.DateTimeFormat().resolvedOptions().timeZoneto detect the browser's timezone. - Synchronization: The detected timezone is sent to the
/api/timezoneroute, which proxies the update to the backend. - Manual Override: Users can manually edit the timezone string within the
SettingsModal.
Sources: web/app/page.tsx:82-108, web/app/api/timezone/route.ts:4-39
Gmail Integration Workflow
The Gmail integration utilizes Composio for OAuth orchestration. The UI manages a multi-step process: initiating a connection, handling a redirect to a new tab for authorization, and polling/refreshing status.
Connection Flow
When a user clicks "Connect Gmail," the system requests a redirect_url and a connection_request_id from the backend.
The sequence diagram illustrates the handoff between the frontend, the proxy API, the backend server, and the external OAuth provider.
Sources: web/components/SettingsModal.tsx:206-242, web/app/api/gmail/connect/route.ts:5-30
Status Monitoring and Metadata Retrieval
The refreshGmailStatus function is triggered automatically when the modal opens and can be called manually. It retrieves connection status and profile metadata (total messages, threads, and history ID).
Sources: web/components/SettingsModal.tsx:244-311, web/app/api/gmail/status/route.ts:5-34
Data Extraction Logic
Because the payload returned by various identity providers can vary, the deriveEmailFromPayload utility recursively searches for email strings within the response data. It checks common fields like emailAddress, user.email, and nested profile objects.
Sources: web/components/SettingsModal.tsx:44-98
API Proxy Architecture
The frontend communicates with the Python backend through Next.js Route Handlers. This provides a clean abstraction and allows for server-side environment variable injection (e.g., PY_SERVER_URL).
| Endpoint | Method | Purpose | Key Parameters |
|---|---|---|---|
/api/gmail/connect | POST | Initiates OAuth flow. | userId |
/api/gmail/status | POST | Polls connection state. | userId, connectionRequestId |
/api/gmail/disconnect | POST | Revokes integration. | userId, connectionRequestId |
/api/timezone | POST | Updates user timezone. | timezone |
Sources: web/app/api/gmail/connect/route.ts, web/app/api/gmail/status/route.ts, web/app/api/gmail/disconnect/route.ts, web/app/api/timezone/route.ts
Termination and Cleanup
Disconnecting Gmail involves a confirmation dialog and a call to the /api/gmail/disconnect endpoint. Upon success, the UI clears all Gmail-related keys from localStorage and resets the local state to prevent unauthorized access or stale data display.
Sources: web/components/SettingsModal.tsx:313-352, web/app/api/gmail/disconnect/route.ts:5-37
The Settings & Authentication UI serves as the configuration hub of OpenPoke, bridging the gap between local user context (timezone, browser ID) and external cloud services (Gmail via Composio). By leveraging a proxy architecture and persistent local state, it provides a seamless authentication experience that remains consistent across browser sessions.