teOS/.claude/agent-memory/frontend-specialist/MEMORY.md

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 - @tos/shared integration guide & differences
• component-patterns.md - Code examples