Auth Split Technical

Documentation for Sessions

Auth Split: Technical Documentation

Purpose: Comprehensive technical reference for the @auth-core / @auth-ui refactor (S220–S222).

1. Architecture Overview

Library Split

Library	Path	Purpose
@auth-core	`libs/libs-foundational/auth-core/`	Always-loaded auth infrastructure
@auth-ui	`libs/libs-ui/auth-ui/`	Lazy-loaded auth UI components

Import Rules

@auth-core  →  AuthService, GuestAuthService, VittoAuthSyncService, authGuard, guards,
               authInterceptor, AUTH_LOGIN_ROUTE, UserMenuComponent, User, RegisterFormConfig, etc.

@auth-ui    →  LoginComponent, RegisterComponent, UnauthorizedPageComponent, UserPreferencesComponent,
               ConnectChannelComponent, AuthPanelComponent, ProtectedShellComponent, DesktopOAuthService,
               UserPreferencesService, AuthPanelService

2. What Lives Where

@auth-core (Always Loaded)

Models: auth.types.ts, user-menu.types.ts (User, AuthState, etc.)
Services: AuthService, GuestAuthService, VittoAuthSyncService
Guards: authGuard, strictAuthGuard, loginPageGuard, adminGuard, developerGuard
Interceptors: authInterceptor
Components: UserMenuComponent, UserMenuDropdownComponent
Constants: AUTH_LOGIN_ROUTE, AUTH_REDIRECT_STRATEGY

@auth-ui (Lazy Loaded)

Components: LoginComponent, RegisterComponent, UnauthorizedPageComponent, UserPreferencesComponent, ConnectChannelComponent, AuthPanelComponent, ProtectedShellComponent
Services: UserPreferencesService, AuthPanelService, DesktopOAuthService

3. Files Modified

New Library

libs/libs-foundational/auth-core/ — Created, contains extracted services

Auth-UI Refactor

libs/libs-ui/auth-ui/ — Removed services/guards; now components + DesktopOAuthService, UserPreferencesService, AuthPanelService

Import Updates (30+ files)

Area	Files
`core-angular`	space.service.ts, space-api.service.ts, sync-engine.service.ts, realtime-sync.service.ts, pages.service.ts, user-journey-tracker.service.ts, space.guard.ts
`theme-runtime`	simple-theme-storage.service.ts
`space-map-lib`	universal-asset-registry.service.ts, space-ai.service.ts, universe-context-banner.component.ts
`vitto-hub`	webhook-builder, vitto-settings, vitto-command-hub, visual-scheduler, observatory-audit, observatory-approvals, identity-viewer, channel-manager
`vitto-core`	brain-context.service.ts
`gograb-ai-lib`	vitto-hub.component.ts, realtime-sync.service.spec.ts
Apps	gograb-space, gograb-ai, gograb-admin, gograb-dev, docs-angular, space-admin

Route Changes

Auth routes use loadComponent: () => import('@auth-ui').then(m => m.X) for route components
Guards and interceptors imported from @auth-core

Space Guard

Dynamic imports changed from @libs-ui/auth-ui to @auth-core for AuthService and GuestAuthService

4. Key Fixes

User Model

Added roles?: string[] to the User interface for backend compatibility (role resolution)

Auth Service

Replaced (user as Record<string, unknown>).roles with Array.isArray(user.roles) ? user.roles : []

DesktopOAuthService

Import from @auth-core for AuthService
Exported from auth-ui public API

Auth-UI Dependencies

Added @libs-foundational/auth-core to auth-ui implicitDependencies so build order is correct

5. ESLint

Removed auth-ui and auth-core from checkDynamicDependenciesExceptions
Only vitto-hub remains (for provideObservatoryTabs())

6. Verification

yarn nx build auth-core — passes
yarn nx build auth-ui — passes (after dependency fix)
yarn serve:gograb-dev, yarn serve:gograb-ai — run after yarn nx reset if build cache issues persist

7. Conventions for Future Work

Always import AuthService from @auth-core — never from @auth-ui
Use loadComponent for auth-ui in routes — keeps auth-ui lazy
User, RegisterFormConfig — from @auth-core

Date: 2026-03-14 | Session: S222