feat(#37-41): Add domains, ideas, relationships, agents, widgets schema
Schema additions for issues #37-41: New models: - Domain (#37): Life domains (work, marriage, homelab, etc.) - Idea (#38): Brain dumps with pgvector embeddings - Relationship (#39): Generic entity linking (blocks, depends_on) - Agent (#40): ClawdBot agent tracking with metrics - AgentSession (#40): Conversation session tracking - WidgetDefinition (#41): HUD widget registry - UserLayout (#41): Per-user dashboard configuration Updated models: - Task, Event, Project: Added domainId foreign key - User, Workspace: Added new relations New enums: - IdeaStatus: CAPTURED, PROCESSING, ACTIONABLE, ARCHIVED, DISCARDED - RelationshipType: BLOCKS, BLOCKED_BY, DEPENDS_ON, etc. - AgentStatus: IDLE, WORKING, WAITING, ERROR, TERMINATED - EntityType: Added IDEA, DOMAIN Migration: 20260129182803_add_domains_ideas_agents_widgets
This commit is contained in:
Jason Woltje
249
docs/web-ui-implementation.md
Normal file
249
docs/web-ui-implementation.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# API Connection
|
||||
NEXT_PUBLIC_API_URL=http://localhost:3001
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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:**
|
||||
```typescript
|
||||
// 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:**
|
||||
```typescript
|
||||
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](https://nextjs.org/docs)
|
||||
- [TailwindCSS Documentation](https://tailwindcss.com/docs)
|
||||
- [React Testing Library](https://testing-library.com/react)
|
||||
- [Mosaic Stack Project](../README.md)
|
||||
- [PDA-Friendly Design Principles](./DESIGN-PRINCIPLES.md)
|
||||
Reference in New Issue
Block a user