User Data Model

Relevant source files

The following files were used as context for generating this wiki page:

• src/types.ts
• src/hooks.ts
• src/convex.ts
• src/middleware.ts
• README.md

The User Data Model in the @pcstyle/auth SDK provides a unified structure for representing identity and session state across PCSTYLE services. It acts as an abstraction layer over WorkOS AuthKit, ensuring consistent user attributes and authentication states are available to both frontend components and backend integrations like Convex.

The model is primarily designed to support cross-subdomain authentication within the .pcstyle.dev ecosystem. It defines the core User object, the AuthState for session tracking, and a specialized ConvexUser record for database persistence.

Sources: src/types.ts:1-68, README.md:1-15

Core Data Structures

The system utilizes three primary interfaces to manage user information and authentication status.

The User Object

The User interface represents the standard identity profile retrieved from WorkOS. It contains unique identifiers, contact information, and metadata regarding the account's lifecycle.

Field	Type	Description
id	string	Unique identifier for the user.
email	string	Primary email address.
firstName	string | null	User's first name.
lastName	string | null	User's last name.
profilePictureUrl	string | null	URL to the user's avatar image.
createdAt	string	ISO timestamp of account creation.
updatedAt	string	ISO timestamp of last update.

Sources: src/types.ts:4-12

AuthState

The AuthState interface tracks the current session's progress and the availability of user data.

Field	Type	Description
user	User | null	The current user object, or null if unauthenticated.
isLoading	boolean	Flag indicating if the auth state is being fetched.
isAuthenticated	boolean	Boolean check for a valid active session.

Sources: src/types.ts:17-21

Convex User Record

For backend persistence within Convex, the ConvexUser type maps WorkOS identities to database records, including application-specific fields like roles.

Field	Type	Description
_id	string	Internal Convex document ID.
authId	string	External WorkOS user ID.
email	string	User email address.
name	string (Optional)	Full name of the user.
avatarUrl	string (Optional)	Profile image URL.
role	string	Application-specific permissions role.
createdAt	number	Unix timestamp of record creation.

Sources: src/types.ts:44-53

Data Flow and Relationships

The user data model facilitates the flow of identity information from the WorkOS provider through the SDK hooks and into the application state.

The diagram above shows how the core User interface serves as the bridge between external WorkOS data, the internal React context state, and the Convex database schema.

Sources: src/types.ts:4-53, src/hooks.ts:18-24

Authentication Logic

The SDK provides React hooks to access the data model and helper functions to manage the authentication lifecycle.

State Retrieval

The useAuth() hook transforms the raw WorkOS state into the project's AuthState structure. If a user is required, the useUser() hook provides a strict access pattern that throws an error if the session is missing.

This flowchart illustrates the standard logic flow when a component consumes the user data model via the useAuth hook.

Sources: src/hooks.ts:18-45

URL Management

User navigation is handled through sign-in and sign-out URL generators. The sign-in process supports an optional returnTo parameter, which is encoded into a Base64 state string to preserve user context after redirection.

• Sign-Out URL: Hardcoded to https://auth.pcstyle.dev/signout.
• Sign-In URL: Defaults to https://auth.pcstyle.dev, with state persistence for redirects.

Sources: src/hooks.ts:50-63

Middleware and Configuration

The user data model is protected at the edge via Next.js middleware, which uses AuthMiddlewareOptions to define public versus protected access.

export interface AuthMiddlewareOptions {
    publicPaths?: string[];
    redirectUri?: string;
    signInUrl?: string;
}

Sources: src/types.ts:26-40, src/middleware.ts:21-27

Configuration Defaults

The SDK assumes a shared domain model for cross-subdomain cookie sharing.

Option	Default Value
authDomain	https://auth.pcstyle.dev
cookieDomain	.pcstyle.dev

Sources: src/types.ts:58-68

Convex Integration Schema

To support the data model in backend functions, the createConvexAuthConfig function configures JWT validation. It expects two distinct issuers from WorkOS: the standard API issuer and a user management issuer specific to the WORKOS_CLIENT_ID.

Sources: src/convex.ts:11-34

Summary

The User Data Model provides a strictly typed environment for handling identity. By centralizing the User and AuthState definitions, the SDK ensures that components, middleware, and database schemas remain synchronized with the underlying WorkOS AuthKit provider while maintaining custom requirements for the PCSTYLE ecosystem.