stack/docs/web-ui-implementation.md

Web UI Implementation

Overview

The Mosaic Stack web UI provides a PDA-friendly interface for managing tasks and events with Authentik OIDC authentication.

Features

Authentication

• Login Page: Clean landing page with Authentik OIDC integration
• Session Management: Automatic session refresh and validation
• Protected Routes: Automatic redirect for unauthenticated users
• Logout: Clean session termination

Task Management

• Task List View: Grouped by date (Today, Tomorrow, This Week, etc.)
• PDA-Friendly Language: No demanding terms like "overdue" or "urgent"
• Status Indicators: Visual emoji-based status (🟢 In Progress, ⚪ Not Started, etc.)
• Priority Badges: Calm, non-aggressive priority display

Calendar

• Event List View: Chronological event display
• Time Display: Clear start/end times with location
• Date Grouping: Same grouping as tasks for consistency
• All-Day Events: Proper handling of all-day events

Navigation

• Fixed Header: Always accessible navigation
• Active Route Highlighting: Clear visual indication
• User Display: Shows logged-in user name/email
• Responsive: Mobile-friendly design

PDA-Friendly Design Principles

Language

• ❌ Never Use: OVERDUE, URGENT, CRITICAL, MUST DO, REQUIRED
• ✅ Always Use: Target passed, Approaching target, High priority, Recommended

Status Indicators

• 🟢 In Progress / Active
• 🔵 Not Started / Upcoming
• ⏸️ Paused / On hold
• 💤 Archived / Inactive
• ✅ Completed
• ⚪ Default/Other

Visual Design

• 10-second scannability: Key info immediately visible
• Visual chunking: Clear sections with headers
• Single-line items: Compact, scannable lists
• Progressive disclosure: Details available on interaction
• Calm colors: No aggressive reds or warnings

Technology Stack

• Framework: Next.js 16 with App Router
• UI: TailwindCSS + Shadcn/ui
• State: React Context + Hooks
• Data Fetching: @tanstack/react-query (prepared)
• Date Handling: date-fns
• Type Safety: TypeScript with @mosaic/shared types
• Testing: Vitest + React Testing Library

File Structure

apps/web/src/
├── app/
│   ├── (auth)/
│   │   ├── login/          # Login page
│   │   └── callback/       # OAuth callback handler
│   ├── (authenticated)/
│   │   ├── layout.tsx      # Protected route wrapper
│   │   ├── tasks/          # Task list page
│   │   └── calendar/       # Calendar page
│   ├── layout.tsx          # Root layout with AuthProvider
│   └── page.tsx            # Home redirect
├── components/
│   ├── auth/               # Login/Logout buttons
│   ├── tasks/              # TaskList, TaskItem
│   ├── calendar/           # Calendar, EventCard
│   └── layout/             # Navigation
├── lib/
│   ├── auth/               # Auth context and hooks
│   ├── api/                # API clients (tasks, events)
│   └── utils/              # Date formatting utilities
└── middleware.ts           # (Future: Route protection)

API Integration

Authentication Endpoints

• GET /auth/session - Get current session
• POST /auth/sign-out - Logout
• GET /auth/callback/authentik - OIDC callback

Future Endpoints (Mock Data Ready)

• GET /api/tasks - List tasks
• GET /api/events - List events

Environment Variables

# API Connection
NEXT_PUBLIC_API_URL=http://localhost:3001

Development

# Install dependencies
pnpm install

# Run development server
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Run with coverage
pnpm test:coverage

Testing

Test Coverage

• API Client: 100% coverage
• Auth Context: Comprehensive tests
• Date Utilities: All functions tested
• Components: Tests for all major components

Running Tests

# All tests
pnpm test

# Watch mode
pnpm test:watch

# With coverage
pnpm test:coverage

Usage

For Users

1. Login:

   • Visit /login
   • Click "Sign In with Authentik"
   • Authenticate via Authentik
   • Redirected to tasks page

2. View Tasks:

   • Navigate to "Tasks"
   • See tasks grouped by date
   • View status and priority
   • Note: PDA-friendly language throughout

3. View Calendar:

   • Navigate to "Calendar"
   • See events grouped by date
   • View event times and locations

4. Logout:

   • Click "Sign Out" in navigation
   • Session cleared
   • Redirected to login

For Developers

Adding a New Component:

1. Create component in appropriate directory
2. Write tests FIRST (TDD)
3. Implement component
4. Use PDA-friendly language
5. Export from index if needed

Connecting Real API:

// Replace mock data with real API call
import { useQuery } from "@tanstack/react-query";
import { fetchTasks } from "@/lib/api/tasks";

const { data: tasks, isLoading } = useQuery({
  queryKey: ["tasks"],
  queryFn: fetchTasks,
});

Using Shared Types:

import type { Task, Event, AuthUser } from "@mosaic/shared";
import { TaskStatus, TaskPriority } from "@mosaic/shared";

Accessibility

• Semantic HTML structure
• Proper heading hierarchy
• ARIA labels for status indicators
• Keyboard navigation support
• Screen reader friendly

Performance

• Static page generation where possible
• Code splitting with Next.js App Router
• Optimized images and assets
• Minimal bundle size

Security

• Session-based authentication
• CSRF protection via cookies
• Protected routes
• No sensitive data in client
• Type-safe API integration

Known Limitations

1. Mock Data: Tasks and events currently use mock data. Backend endpoints pending.
2. CRUD Operations: Currently read-only. Create/Update/Delete pending.
3. Real-time Updates: No WebSocket integration yet.
4. Offline Support: No PWA features yet.

Future Enhancements

• Task creation/editing UI
• Event creation/editing UI
• Real-time updates via WebSockets
• Drag-and-drop task reordering
• Calendar month view
• Search and filters
• Mobile app (React Native)
• Offline support (PWA)
• Notifications
• Collaboration features

Resources

• Next.js Documentation
• TailwindCSS Documentation
• React Testing Library
• Mosaic Stack Project
• PDA-Friendly Design Principles