# tOS Frontend - Agent Memory

## Project Overview
- **Type**: Enterprise Web Dashboard (Next.js 14+ App Router)
- **Location**: `/home/mehmed/Entwicklung/githubProjekte/tOS/apps/web/`
- **Language**: Code/comments in English, UI in German (default) via i18n

## Tech Stack
- Next.js 14+ with App Router
- TypeScript (strict mode)
- Tailwind CSS + shadcn/ui (new-york style)
- next-themes for dark/light mode
- next-intl for i18n (de default, en supported)
- NextAuth with Keycloak provider
- Framer Motion for animations
- Zustand for client state (sidebar-store, dashboard-store)
- TanStack Query for server state
- TanStack Table for data tables
- Recharts for chart components
- dnd-kit for drag and drop
- date-fns for date formatting
- Lucide React for icons

## File Structure
```
apps/web/src/
  app/[locale]/              # Locale-based routing
    (auth)/                  # Protected routes with sidebar layout
      dashboard/             # Widget-based dashboard
      settings/              # profile/, preferences/, security/, notifications/
      admin/                 # users/, departments/, integrations/ - role protected
      lean/                  # 3s-planning/, morning-meeting/, skill-matrix/
      hr/                    # employees/, time-tracking/, absences/
      integrations/          # Overview + [type]/ dynamic routes
    login/                   # Public login page
  components/
    ui/                      # shadcn/ui + DataTable, Badge, Tabs, Switch, etc.
    layout/                  # Sidebar (collapsible sub-nav), Header
    dashboard/               # Widget system (container, grid, registry)
      widgets/               # clock, welcome, quick-actions, stats, calendar, activity
        integrations/        # orders, chat, tasks, tickets, files, documents
    integrations/            # Shared: status-badge, integration-card, connection-test-button
    charts/                  # bar-chart, line-chart, pie-chart, chart-container
    providers/               # SessionProvider, ThemeProvider, QueryProvider
  hooks/                     # use-toast, use-media-query, use-mounted
    integrations/            # use-orders, use-messages, use-tasks, etc.
  lib/                       # utils, api, auth, motion variants
  stores/                    # sidebar-store, dashboard-store
  types/                     # User, UserRole, Department, WidgetConfig, integrations.ts
```

## Key Patterns

### 1. Server/Client Component Split
- `page.tsx` = Server Component (metadata only)
- `*-content.tsx` = Client Component (receives locale prop)

### 2. Widget System (Phase 2)
- Registry pattern: `widget-registry.ts` defines all widget types
- Drag & drop: dnd-kit with SortableContext
- Persistence: Zustand store with localStorage
- Each widget: WidgetContainer wrapper + specific content

### 3. Role-Based Navigation
- NavItem has optional `requiredRoles: UserRole[]`
- Sidebar filters items via `filterNavItems(items, userRoles)`
- Roles: admin, manager, department_head, employee

### 4. DataTable Pattern
- Generic component: `DataTable<TData, TValue>`
- Use `DataTableColumnHeader` for sortable columns
- Features: search, pagination, column visibility, row selection

### 5. Chart Components
- Wrap Recharts in `ChartContainer` for consistent styling
- Support loading states, empty states
- Theme-aware colors via CSS variables

### 6. Integration Hooks (Phase 3)
- TanStack Query with 30s staleTime
- Mock data for development, TODO comments for API replacement
- Query key factories: `ordersKeys`, `messagesKeys`, etc.
- Optimistic updates for complete/toggle actions

### 7. Integration Widgets
- Widget categories: `integrations` added to registry
- requiredRoles: ['manager', 'admin'] for sensitive widgets
- Each widget uses WidgetContainer + specific hook

## Sidebar Behavior
- Expanded: 240px, Collapsed: 64px
- Collapsible sub-navigation with ChevronDown animation
- Tooltip shows sub-nav when collapsed

## i18n Keys
- Flat structure with nested objects: `widgets.clock.name`
- Use ASCII for German (oe, ae, ue) to avoid encoding issues

## Dependencies Added (Phase 2)
- @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities
- @tanstack/react-table
- @radix-ui/react-checkbox, collapsible, popover, select, tabs
- recharts, date-fns

## Dependencies Added (Phase 3)
- @radix-ui/react-switch (for Switch component)

## Integration Types (Phase 3+)
- `plenty-one`: PlentyONE (e-commerce) - OrdersWidget
- `zulip`: ZULIP (chat) - ChatWidget
- `todoist`: Todoist (tasks) - TasksWidget
- `freescout`: FreeScout (helpdesk) - TicketsWidget
- `nextcloud`: Nextcloud (files) - FilesWidget
- `ecodms`: ecoDMS (documents) - DocumentsWidget
- `gembadocs`: GembaDocs (audits/compliance) - GembaDocsWidget

## LEAN Module Structure

### File Organization
```
apps/web/src/
  app/[locale]/(auth)/lean/
    page.tsx                    # LEAN overview
    s3-planning/
      page.tsx                  # S3 plans overview
      [departmentId]/page.tsx   # Department detail view
    morning-meeting/
      page.tsx                  # Meetings overview + calendar
      morning-meeting-overview-content.tsx
      [departmentId]/
        page.tsx                # Department SQCDM board
        department-meeting-content.tsx
    skill-matrix/
      page.tsx                  # Overview with department cards
      skill-matrix-overview-content.tsx
      [departmentId]/
        page.tsx                # Department matrix grid + gap analysis
        department-skill-matrix-content.tsx
  components/lean/
    s3/                         # S3 Planning components
      index.ts                  # Barrel export
      s3-status-cell.tsx        # Colored week cell
      s3-status-modal.tsx       # Status edit dialog
      s3-category-card.tsx      # Category with week grid
      s3-progress-chart.tsx     # Pie chart stats
      s3-plan-overview.tsx      # Plans list with filters
      s3-department-view.tsx    # Week calendar view
    morning-meeting/            # Morning Meeting components
      index.ts                  # Barrel export
      meeting-board.tsx         # Main board with all 5 SQCDM columns
      sqcdm-column.tsx          # Single S/Q/C/D/M column
      kpi-card.tsx              # KPI with traffic light + trend
      meeting-timer.tsx         # Timer with start/stop, countdown mode
      action-list.tsx           # Action items container with filters
      action-item.tsx           # Single action with status/assignee
  hooks/lean/
    index.ts                    # Barrel export
    use-s3-plans.ts             # Plans CRUD + types
    use-s3-status.ts            # Status updates
    use-meetings.ts             # Meeting CRUD + topics/actions
    use-meeting-timer.ts        # Timer logic (elapsed/countdown)
```

### S3 Status Types & Colors
- `NOT_APPLICABLE` (gray): Not started
- `YELLOW`: In progress
- `GREEN`: Completed
- `RED`: Problem/Issue

### S3 Type Categories
- `SEIRI`: Sort
- `SEITON`: Set in Order
- `SEISO`: Shine

### API Endpoints (Backend)
- `GET /lean/s3/plans` - List with filters (year, month, departmentId)
- `GET /lean/s3/plans/:id` - Single plan with categories/statuses
- `PUT /lean/s3/status/:id` - Update status entry

### Skill Matrix Module
```
components/lean/skill-matrix/
  index.ts                    # Barrel export
  skill-level-badge.tsx       # Level badge with color coding (0-4)
  skill-cell.tsx              # Matrix cell with quick-edit popover
  skill-matrix-grid.tsx       # Full grid (employees x skills)
  skill-gap-chart.tsx         # Bar chart for gap analysis

hooks/lean/
  use-skills.ts               # Skills CRUD + categories
  use-skill-matrix.ts         # Matrix data + gap analysis
```

### Skill Level Colors
- `0` (gray): No knowledge
- `1` (red): Basics
- `2` (yellow): Independent
- `3` (green): Expert
- `4` (blue): Can train

### Skill Matrix API Endpoints (Backend)
- `GET /lean/skills` - List with filters
- `GET /lean/skills/department/:id` - Skills for department
- `GET /lean/skill-matrix/:departmentId` - Full matrix
- `GET /lean/skill-matrix/gaps/:departmentId` - Gap analysis
- `POST /lean/skill-matrix/entries` - Create entry
- `PUT /lean/skill-matrix/entries/:id` - Update entry
- `POST /lean/skill-matrix/entries/bulk` - Bulk upsert

## HR Module (Phase 5)

### File Structure
```
apps/web/src/
  app/[locale]/(auth)/hr/
    page.tsx                    # HR overview with stats
    hr-overview-content.tsx     # Client component
    employees/
      page.tsx                  # Employee list
      employees-content.tsx
      [id]/
        page.tsx                # Employee details
        employee-detail-content.tsx
      new/
        page.tsx                # New employee form
        new-employee-content.tsx
    org-chart/
      page.tsx                  # Organization chart
      org-chart-content.tsx
  components/hr/employees/
    index.ts                    # Barrel export
    employee-card.tsx           # Quick overview card
    employee-list.tsx           # DataTable with filters
    employee-form.tsx           # Create/edit form
    org-chart.tsx               # Hierarchical tree view
  hooks/hr/
    index.ts                    # Barrel export
    use-employees.ts            # CRUD + types + mock data
```

### Employee Types
- `EmploymentStatus`: active, inactive, on_leave, terminated
- `ContractType`: full_time, part_time, mini_job, intern, trainee, freelance
- Full Employee interface with address, emergency contact

### Employee Status Colors
- `active` (green)
- `inactive` (gray)
- `on_leave` (yellow)
- `terminated` (red)

### i18n Keys (hr namespace)
- `hr.title`, `hr.description`
- `hr.employees.*` - List/detail pages
- `hr.stats.*` - Dashboard statistics
- `hr.employeeStatus.*` - Status translations
- `hr.contractType.*` - Contract type translations
- `hr.form.*` - Form sections
- `hr.tabs.*` - Detail view tabs
- `hr.toast.*` - Toast notifications

### Dependencies Added (Phase 5)
- react-day-picker (for Calendar component)
- react-hook-form + zod (already present)
- @radix-ui/react-progress (for Progress component)

## HR Time Tracking Module (Phase 5)

### File Structure
```
apps/web/src/
  app/[locale]/(auth)/hr/
    time-tracking/
      page.tsx                  # Time tracking overview
      time-tracking-content.tsx # Time clock + entries
      [employeeId]/
        page.tsx                # Employee time account
        employee-time-account-content.tsx
    absences/
      page.tsx                  # Absences overview
      absences-content.tsx      # Balance + requests
      calendar/
        page.tsx                # Team calendar view
        absence-calendar-content.tsx
      requests/
        page.tsx                # Manager approval view
        absence-requests-content.tsx
  components/hr/
    time-tracking/
      index.ts                  # Barrel export
      time-clock.tsx            # Web clock (clock in/out, breaks)
      time-entry-list.tsx       # List of time entries
      time-entry-form.tsx       # Correction request dialog
      time-summary.tsx          # Monthly summary with progress
    absences/
      index.ts                  # Barrel export
      absence-calendar.tsx      # Monthly calendar with absences
      absence-request-form.tsx  # Create absence request dialog
      absence-card.tsx          # Single absence with status
      absence-approval-list.tsx # Pending requests for managers
      vacation-balance.tsx      # Vacation quota display
  hooks/hr/
    use-time-tracking.ts        # Clock in/out, entries, summary
    use-absences.ts             # Requests, balance, calendar
  types/hr.ts                   # TimeEntry, Absence, VacationBalance types
```

### Time Tracking Types
- `TimeEntryStatus`: CLOCKED_IN, ON_BREAK, CLOCKED_OUT
- `TimeEntryType`: REGULAR, OVERTIME, CORRECTED
- `TIME_STATUS_INFO`: Color mapping for status badges

### Absence Types
- `AbsenceType`: VACATION, SICK, HOME_OFFICE, SPECIAL_LEAVE, UNPAID_LEAVE, TRAINING
- `AbsenceRequestStatus`: PENDING, APPROVED, REJECTED, CANCELLED
- `ABSENCE_TYPE_INFO`: Color + icon mapping
- `ABSENCE_STATUS_INFO`: Status color mapping

### i18n Keys (hr namespace)
- `hr.timeTracking.*` - Clock, entries, summary
- `hr.absences.*` - Balance, requests, calendar, approvals

## Related Files
- [shared-package.md](./shared-package.md) - @tos/shared integration guide & differences
- [component-patterns.md](./component-patterns.md) - Code examples
