# Dashboard - Archer Platform

**Version**: 1.2.0 | **Last Updated**: 2025-12-19 | **Status**: Production Ready

React-based administrative dashboard implementing Clean Architecture with TanStack Query for state management.

## Table of Contents

- [Overview](#overview)
- [Clean Architecture](#clean-architecture)
- [Getting Started](#getting-started)
- [Architecture Layers](#architecture-layers)
- [Domain Entities](#domain-entities)
- [Use Cases](#use-cases)
- [Development Guide](#development-guide)
- [Path Aliases](#path-aliases)
- [Tech Stack](#tech-stack)
- [Project Statistics](#project-statistics)
- [Related Documentation](#related-documentation)

---

## Overview

### What is the Dashboard?

The Dashboard is a multi-tenant management interface for the Archer voice platform providing:

- **Company Management**: Create and configure companies/organizations
- **Tenant Management**: Manage website integrations and deployments
- **User Administration**: User CRUD operations with role-based access
- **Integration Keys**: Generate and manage API keys for tenant integrations
- **Analytics**: View usage statistics and info center data

### Architecture Philosophy

This dashboard implements **Clean Architecture** principles with **TanStack Query** for data fetching and state management:

```
┌──────────────────────────────────────────────────────┐
│         Presentation Layer (UI Components)            │
│   React Components, TanStack Query Hooks             │
│   - useQuery for data fetching + automatic caching   │
│   - useMutation for create/update/delete operations  │
│   - Automatic loading/error states                   │
└──────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────┐
│       Application Layer (Business Orchestration)      │
│   Use Cases, Mappers, Business Logic Flow            │
│   (Used by Tenant, IntegrationKey, InfoCenter)       │
└──────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────┐
│         Infrastructure Layer (External Concerns)      │
│   API Client, Repositories (legacy), localStorage    │
│   - User & Company: Direct API client usage          │
│   - Others: Repository pattern (migration pending)   │
└──────────────────────────────────────────────────────┘
                         ↓
┌──────────────────────────────────────────────────────┐
│           Domain Layer (Business Rules)               │
│   Entities, Value Objects, Repository Interfaces     │
└──────────────────────────────────────────────────────┘
```

**Key Principles**:
- Domain layer has ZERO external dependencies
- Business logic lives in domain entities (not services)
- TanStack Query replaces Repository + UseCase layers for User & Company
- Automatic caching, deduplication, and background refetch
- All data flows through domain entities

**Migration Status** (Dec 2025):
- ✅ All Features Migrated: Users, Company, Tenants, IntegrationKeys, InfoCenter (71% average code reduction)
- ✅ Repository Layer: Completely removed (~900 lines deleted)
- ✅ Use-Case Layer: Completely removed (~575 lines deleted)
- ✅ Total Impact: ~1,975 lines removed across all 7 migration phases

---

## Clean Architecture

### Why Clean Architecture?

**Benefits Achieved**:
1. **Testability**: Domain logic testable without UI/database
2. **Maintainability**: Clear separation of concerns
3. **Flexibility**: Swap localStorage for API without changing domain
4. **Type Safety**: Full TypeScript with domain-driven types
5. **Scalability**: Easy to add features without breaking existing code

### Layer Responsibilities

| Layer | Responsibility | Dependencies | Examples |
|-------|---------------|--------------|----------|
| **Domain** | Business rules, entities, contracts | None (pure TypeScript) | `Tenant`, `User`, `IntegrationKey` |
| **Application** | Use cases, orchestration, mapping | Domain | `GetTenantsUseCase`, `TenantMapper` |
| **Infrastructure** | External concerns, data access | Domain, Application | `TenantRepository`, `ApiClient` |
| **Presentation** | UI, user interaction, routing | Application, Domain (read-only) | `TenantsList`, `useTenants` |

### Dependency Flow

```
Presentation → Application → Infrastructure → Domain
     ↑                                           ↓
     └───────────────────────────────────────────┘
        (Presentation reads Domain entities)
```

**Critical Rule**: Dependencies point INWARD. Domain never imports from outer layers.

---

## Getting Started

### Prerequisites

- Node.js 24+
- pnpm 9.0+
- Running API backend (Port 4000) or use mock data via localStorage

### Installation

From monorepo root:

```bash
# Install dependencies
pnpm install

# Start dashboard dev server
pnpm --filter @archer/dashboard dev
```

Or from dashboard directory:

```bash
cd apps/dashboard
pnpm dev
```

### Development Commands

```bash
# Start with hot reload (Port 4002)
pnpm dev

# Build for production
pnpm build

# Preview production build
pnpm preview

# Type checking
pnpm type-check

# Linting
pnpm lint
```

The app will be available at `http://localhost:4002`

### Environment Variables

Create `.env.local` in `apps/dashboard/`:

```bash
# API Backend URL (optional - defaults to localStorage)
VITE_API_URL=http://localhost:4000

# Feature flags
VITE_USE_API=false  # Set to true when API is ready
```

### First Run

1. Start dev server: `pnpm dev`
2. Open browser: `http://localhost:4002`
3. Login with demo credentials (bypassed in dev mode)
4. Dashboard loads with sample data from localStorage

---

## Architecture Layers

### Layer 1: Domain (`src/domain/`)

**Purpose**: Pure business logic with zero dependencies

**Structure**:
```
domain/
├── entities/          # Domain entities (8 files)
│   ├── Tenant.ts      # Tenant entity with business logic (323 lines)
│   ├── User.ts        # User entity with role management (401 lines)
│   ├── IntegrationKey.ts  # API key entity with masking (379 lines)
│   ├── Company.ts     # Company/organization entity (158 lines)
│   ├── DiscoveredPage.ts  # Page discovery entity (418 lines)
│   ├── PageAnalysis.ts    # Page analysis entity (383 lines)
│   ├── Notification.ts    # Notification entity
│   └── index.ts       # Barrel exports
│
├── value-objects/     # Immutable value objects (3 objects)
│   ├── Email.ts       # Email validation (136 lines)
│   ├── Domain.ts      # Domain name validation (168 lines)
│   ├── DateRange.ts   # Date range logic (220 lines)
│   └── index.ts
│
├── repositories/      # Repository interfaces (5 interfaces)
│   ├── ITenantRepository.ts
│   ├── IUserRepository.ts
│   ├── IIntegrationKeyRepository.ts
│   ├── IInfoCenterRepository.ts
│   ├── ICompanyRepository.ts
│   └── index.ts
│
└── constants/         # Domain constants
    └── status-configs.ts  # Status badge configurations
```

**Domain Entity Example**:
```typescript
// Domain entity with business methods
export class Tenant {
  // Factory methods
  static create(data: {...}): Tenant
  static fromPersistence(data: {...}): Tenant

  // Business logic methods
  activate(): Tenant
  suspend(): Tenant
  delete(): Tenant              // Soft delete
  updateDetails(data: {...}): Tenant

  // Query methods
  isActive(): boolean
  isSuspended(): boolean
  getDisplayName(): string      // "name (domain)"

  // Computed properties (getters)
  get statusLabel(): string
  get typeLabel(): string
  get statusColor(): string
}
```

**Repository Interface** (contract for infrastructure):
```typescript
export interface ITenantRepository {
  getAll(): Promise<Tenant[]>;
  getById(id: string): Promise<Tenant | null>;
  findByDomain(domain: string): Promise<Tenant | null>;
  create(tenant: Tenant): Promise<Tenant>;
  update(tenant: Tenant): Promise<Tenant>;
  delete(id: string): Promise<void>;
}
```

---

### Layer 2: Application (`src/application/`)

**Purpose**: Orchestrate business operations, transform data

**Structure**:
```
application/
├── use-cases/         # Business operations (37 use cases)
│   ├── tenant/        # Tenant CRUD (5 use cases, ~724 lines)
│   │   ├── GetTenantsUseCase.ts
│   │   ├── GetTenantByIdUseCase.ts
│   │   ├── CreateTenantUseCase.ts
│   │   ├── UpdateTenantUseCase.ts
│   │   └── DeleteTenantUseCase.ts
│   │
│   ├── user/          # User management (6 use cases, ~883 lines)
│   ├── integration-key/  # Key management (5 use cases, ~791 lines)
│   ├── info-center/   # Info center (4 use cases, ~1,300 lines)
│   └── company/       # Company management (4 use cases, ~639 lines)
│
└── mappers/           # DTO ↔ Domain transformations (7 mappers)
    ├── TenantMapper.ts
    ├── UserMapper.ts
    ├── IntegrationKeyMapper.ts
    ├── InfoCenterMapper.ts
    ├── CompanyMapper.ts
    ├── IMapper.ts     # Mapper interface
    └── index.ts
```

**Use Case Example**:
```typescript
export class GetTenantsUseCase {
  constructor(
    private readonly tenantRepository: ITenantRepository
  ) {}

  async execute(filters?: GetTenantsFilters): Promise<Tenant[]> {
    // 1. Fetch from repository
    let tenants = await this.tenantRepository.getAll();

    // 2. Apply business rules
    if (filters) {
      tenants = this.applyFilters(tenants, filters);
    }

    // 3. Exclude soft-deleted by default
    if (!filters?.includeDeleted) {
      tenants = tenants.filter(t => !t.deletedAt);
    }

    return tenants;
  }
}
```

**Mapper Example**:
```typescript
export const tenantMapper = {
  // DTO → Domain Entity
  toDomain(dto: TenantDTO): Tenant {
    return Tenant.fromPersistence({
      id: dto.id,
      companyId: dto.companyId,
      name: dto.name,
      domain: dto.domain,
      status: dto.status,
      createdAt: new Date(dto.createdAt),
      updatedAt: new Date(dto.updatedAt),
    });
  },

  // Domain Entity → DTO
  toDTO(entity: Tenant): TenantDTO {
    return {
      id: entity.id,
      companyId: entity.companyId,
      name: entity.name,
      domain: entity.domain,
      status: entity.status,
      createdAt: entity.createdAt.toISOString(),
      updatedAt: entity.updatedAt.toISOString(),
    };
  }
};
```

---

### Layer 3: Infrastructure (`src/infrastructure/`)

**Purpose**: External concerns (HTTP, storage, external APIs)

**Structure**:
```
infrastructure/
├── repositories/      # Repository implementations (9 files)
│   ├── BaseRepository.ts       # Abstract base with localStorage CRUD (318 lines)
│   ├── TenantRepository.ts     # Tenant data access (138 lines)
│   ├── UserRepository.ts       # User data access (227 lines)
│   ├── IntegrationKeyRepository.ts  # Integration key data access (153 lines)
│   ├── InfoCenterRepository.ts # Info center data access (840 lines)
│   │                           # Includes automatic sample data initialization:
│   │                           # - 15 discovered pages with 3-level hierarchy
│   │                           # - 30-80 elements per analyzed page
│   │                           # - Realistic selector strategies (ARIA, CSS, XPATH)
│   ├── CompanyRepository.ts    # Company data access (236 lines)
│   └── index.ts
│
└── http/              # HTTP client (2 files)
    ├── ApiClient.ts   # Axios wrapper with interceptors (295 lines)
    └── index.ts
```

**BaseRepository Pattern**:
```typescript
abstract class BaseRepository<TEntity, TDTO> {
  constructor(protected readonly storageKey: string) {}

  // Abstract methods (subclasses implement)
  protected abstract toDomain(dto: TDTO): TEntity;
  protected abstract toDTO(entity: TEntity): TDTO;
  protected abstract getId(entity: TEntity): string;

  // Common CRUD operations
  protected async getAllEntities(): Promise<TEntity[]>;
  protected async getEntityById(id: string): Promise<TEntity | null>;
  protected async createEntity(entity: TEntity): Promise<TEntity>;
  protected async updateEntity(entity: TEntity): Promise<TEntity>;
  protected async deleteEntity(id: string): Promise<void>;
}
```

**Concrete Repository**:
```typescript
export class TenantRepository extends BaseRepository<Tenant, TenantDTO>
  implements ITenantRepository
{
  constructor() {
    super('archer_tenants'); // localStorage key
  }

  protected toDomain(dto: TenantDTO): Tenant {
    return tenantMapper.toDomain(dto);
  }

  protected toDTO(entity: Tenant): TenantDTO {
    return tenantMapper.toDTO(entity);
  }

  protected getId(entity: Tenant): string {
    return entity.id;
  }

  // Domain-specific queries
  async findByDomain(domain: string): Promise<Tenant | null> {
    const normalized = domain.toLowerCase();
    return this.findEntity((dto) => dto.domain === normalized);
  }
}
```

**InfoCenter Sample Data Initialization**:

The `InfoCenterRepository` includes automatic sample data generation to prevent empty UI states during development. When the repository is instantiated and detects empty storage, it automatically generates:

**Discovered Pages** (15 pages with 3-level hierarchy):
- **Homepage** (depth 0): Entry point with manual discovery
- **Category Pages** (depth 1): Products, Services, About, Contact, Pricing
- **Product Details** (depth 2): 5 product pages with varying analysis states
- **Additional Pages**: Blog, FAQ, broken pages, redirects

**Page Analyses** (for ANALYZED pages):
- **Elements**: 30-80 interactive elements per page
- **Element Types**: Buttons, inputs, links, selects, textareas, checkboxes
- **Selector Strategies**: Multiple strategies per element, prioritized by reliability:
  - ARIA selectors (85-98% confidence)
  - TEXT selectors (70-90% confidence)
  - CSS selectors (60-85% confidence)
  - XPATH selectors (40-70% confidence)
  - POSITION selectors (20-50% confidence)

**Sample Data Methods**:
```typescript
class InfoCenterRepository {
  // Called automatically by constructor if storage empty
  private async initializeIfEmpty(): Promise<void>

  // Public method to manually generate sample data
  async initializeSampleData(): Promise<void>

  // Generate 15 pages with realistic hierarchy
  private async generateDiscoveredPages(tenantId: string, domain: string): Promise<DiscoveredPage[]>

  // Generate analyses for analyzed pages
  private generatePageAnalyses(pages: DiscoveredPage[]): PageAnalysis[]

  // Generate 30-80 realistic elements per page
  private generateElements(count: number): PageElement[]

  // Generate selector strategies with confidence scores
  private generateSelectors(elementType: ElementType): SelectorStrategy[]
}
```

**Automatic Initialization Flow**:
1. Constructor checks if `archer_discovered_pages` storage is empty
2. If empty, imports `TenantRepository` to get tenant data
3. Generates 15 discovered pages with hierarchical structure
4. Generates page analyses for pages with status `ANALYZED`
5. Each analysis includes 30-80 elements with realistic selectors
6. Data persisted to localStorage for immediate UI display

**Benefits**:
- **Zero Configuration**: Works out-of-the-box for development
- **Realistic Data**: Hierarchical pages, varied statuses, confidence scores
- **UI Testing**: Enables testing without manual data entry
- **Developer Experience**: Instant visual feedback on first run

**Developer Notes**:
- Sample data respects tenant relationships (must initialize `TenantRepository` first)
- Data includes various page statuses: ACTIVE, BROKEN, REDIRECT
- Analysis statuses: ANALYZED, PENDING, OUTDATED, NONE, FAILED
- Element visibility, positioning, and selector strategies are randomized for realism

---

## InfoCenter - Pattern Detection

The InfoCenter now includes AI-powered pattern detection capabilities:

### Features
- **Reliability Status Tracking**: DRAFT → PENDING_CONFIRMATION → CONFIRMED → REJECTED
- **Listing Template Detection**: Identifies repeating item structures (products, reviews, etc.)
- **Search Mechanism Detection**: Detects form-based and URL pattern search
- **Pagination Detection**: Identifies 4 types (numbered pages, next/prev, load more, infinite scroll)

### Pattern Visualization
- **Pattern Detection Summary**: Overview card showing pattern statistics
- **Patterns Tab**: Dedicated view for all detected patterns
- **Template Cards**: Summary cards for listing templates with slot preview
- **Template Modal**: Detailed view with paginated slots and actions tables

### UI Components
- `Pagination`: Reusable pagination with keyboard navigation and accessibility
- `ReliabilityStatusBadge`: Color-coded status badges (green/yellow/gray/red)
- `PatternDetectionSection`: Container for pattern visualization
- `ListingTemplateCard`: Template summary with clickable interaction
- `ListingTemplateModal`: Full template details with paginated tables

### Data Migration
The InfoCenter automatically migrates older analyses to include new fields with sensible defaults. Cache versioning ensures compatibility.

### Error Handling
Error boundaries prevent crashes from malformed JSONB data, showing graceful fallback UI instead.

### Testing
See `apps/dashboard/docs/INFOCENTER_TESTING.md` for comprehensive testing guide.

---

### Layer 4: Presentation (`src/presentation/`, `src/features/`)

**Purpose**: UI components, user interaction, routing

**Structure**:
```
presentation/
└── features/
    ├── info-center/hooks/     # InfoCenter React hooks
    └── integration-keys/hooks/  # Integration key hooks

features/
├── tenants/           # Tenant management UI
│   ├── hooks/         # React hooks (useTenants, useTenant)
│   ├── components/    # Tenant-specific components
│   ├── TenantsList.tsx
│   ├── TenantDetail.tsx
│   └── TenantEdit.tsx
│
├── users/             # User management UI
│   └── hooks/         # User hooks
│
├── info-center/       # Info center UI
│   ├── InfoCenterPage.tsx
│   └── components/
│
├── dashboard/         # Dashboard home
│   ├── DashboardPage.tsx
│   ├── DashboardLayout.tsx
│   └── hooks/useDashboard.ts
│
└── auth/              # Authentication UI
    └── LoginPage.tsx

components/
├── shared/            # Shared presentational components
│   ├── Modal.tsx
│   ├── ViewHeader.tsx
│   └── NotificationPanel.tsx
│
└── ui/                # Base UI components (shadcn/ui)
    ├── button.tsx
    ├── card.tsx
    ├── input.tsx
    └── alert.tsx

routes/                # TanStack Router file-based routes
├── __root.tsx
├── index.tsx
├── login.tsx
├── dashboard.index.tsx
├── dashboard.tenants.tsx
├── dashboard.users.tsx
├── dashboard.settings.tsx
└── dashboard.info-center.tsx
```

**React Hook Pattern**:
```typescript
export function useTenants(autoLoad = true): UseTenants {
  const [state, setState] = useState<TenantState>({
    tenants: [],
    isLoading: autoLoad,
    error: null,
  });

  // Initialize use cases (dependency injection)
  const getTenantsUseCase = new GetTenantsUseCase(tenantRepository);
  const createTenantUseCase = new CreateTenantUseCase(tenantRepository);

  // Load tenants
  const loadTenants = useCallback(async (filters?: GetTenantsFilters) => {
    setState(prev => ({ ...prev, isLoading: true, error: null }));
    try {
      const tenants = await getTenantsUseCase.execute(filters);
      setState({ tenants, isLoading: false, error: null });
    } catch (error) {
      setState(prev => ({
        ...prev,
        isLoading: false,
        error: error.message
      }));
    }
  }, []);

  // Auto-load on mount
  useEffect(() => {
    if (autoLoad) {
      loadTenants();
    }
  }, [autoLoad, loadTenants]);

  return {
    tenants: state.tenants,
    isLoading: state.isLoading,
    error: state.error,
    loadTenants,
    createTenant: async (data) => { /* ... */ },
    updateTenant: async (tenant) => { /* ... */ },
    deleteTenant: async (id) => { /* ... */ },
  };
}
```

**Component Usage**:
```typescript
function TenantsList() {
  const { tenants, isLoading, error } = useTenants();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      {tenants.map(tenant => (
        <TenantCard
          key={tenant.id}
          tenant={tenant}  // Domain entity passed to component
        />
      ))}
    </div>
  );
}
```

---

## Domain Entities

### Tenant Entity

**Purpose**: Represents a customer deployment integrating with Archer

**Business Rules**:
- Domain must be unique and lowercase
- Status transitions: ACTIVE ↔ SUSPENDED → ARCHIVED (no resurrection)
- Soft deletion (sets `deletedAt`, not hard delete)

**Key Methods**:
```typescript
class Tenant {
  // Factory methods
  static create(data: {...}): Tenant
  static fromPersistence(data: {...}): Tenant

  // Business operations
  activate(): Tenant
  suspend(): Tenant
  delete(): Tenant                // Soft delete (sets deletedAt)
  updateDetails(data: {...}): Tenant

  // Query methods
  isActive(): boolean
  isSuspended(): boolean
  isArchived(): boolean
  getDisplayName(): string        // "name (domain)"

  // Computed properties
  get statusLabel(): string
  get statusColor(): string
}
```

**Enums**:
```typescript
enum TenantStatus {
  ACTIVE = 'ACTIVE',
  SUSPENDED = 'SUSPENDED',
  ARCHIVED = 'ARCHIVED',
}
```

See [Entity Documentation](#domain-entities) for User, IntegrationKey, Company, DiscoveredPage, and PageAnalysis entities.

---

## Use Cases

### Tenant Use Cases

| Use Case | Purpose | Input | Output |
|----------|---------|-------|--------|
| **GetTenantsUseCase** | List tenants with filtering | `GetTenantsFilters?` | `Tenant[]` |
| **GetTenantByIdUseCase** | Get single tenant | `string` (id) | `Tenant` |
| **CreateTenantUseCase** | Create new tenant | `CreateTenantData` | `Tenant` |
| **UpdateTenantUseCase** | Update tenant | `Tenant` | `Tenant` |
| **DeleteTenantUseCase** | Soft delete tenant | `string` (id) | `void` |

**Use Case Modules**:
- **Tenant**: 5 use cases (~724 lines)
- **User**: 6 use cases (~883 lines)
- **IntegrationKey**: 5 use cases (~791 lines)
- **InfoCenter**: 4 use cases (~1,300 lines)
- **Company**: 4 use cases (~639 lines)
- **Total**: 24 use cases (~4,337 lines)

---

## Development Guide

### Adding a New Feature Module

**Step 1: Define domain entity** in `src/domain/entities/`
**Step 2: Create repository interface** in `src/domain/repositories/`
**Step 3: Implement mapper** in `src/application/mappers/`
**Step 4: Create repository** in `src/infrastructure/repositories/`
**Step 5: Write use cases** in `src/application/use-cases/`
**Step 6: Create React hook** in `src/features/*/hooks/`
**Step 7: Build UI components** in `src/features/*/`

See [Architecture Documentation](../../.ai/ARCHITECTURE.md#key-patterns) for detailed patterns and examples.

---

## Path Aliases

### Configured Aliases

| Alias | Path | Usage |
|-------|------|-------|
| `@/*` | `./src/*` | Any source file |
| `@domain/*` | `./src/domain/*` | Domain layer |
| `@application/*` | `./src/application/*` | Application layer |
| `@infrastructure/*` | `./src/infrastructure/*` | Infrastructure layer |
| `@presentation/*` | `./src/presentation/*` | Presentation layer |

**Usage Example**:
```typescript
// Before (relative imports)
import { Tenant } from '../../../domain/entities/Tenant';

// After (path aliases)
import { Tenant } from '@domain/entities/Tenant';
```

**Configuration**: See `tsconfig.json` and `vite.config.ts`

---

## Tech Stack

### Core Technologies

- **React 19** - Latest React with new features and performance improvements
- **Vite 7** - Next-generation frontend build tool
- **TypeScript 5.9+** - Type-safe development
- **TanStack Router v2** - Type-safe, file-based routing
- **TanStack Query v5** - Data fetching, caching, and state management
- **shadcn/ui** - High-quality, customizable UI components
- **Tailwind CSS 4** - Utility-first CSS framework
- **React Hook Form** - Performant form handling
- **Zod** - Schema validation
- **Axios** - HTTP client with interceptors

### Workspace Dependencies

- **@archer/domain** - Shared domain models (workspace package)
- **@archer/api-interface** - API contracts and Zod schemas (workspace package)

### State Management

**TanStack Query** (User & Company features):
- Automatic caching with 5-minute default staleTime
- Request deduplication (multiple components = single network call)
- Background refetch on window focus/reconnect
- Automatic retry with exponential backoff
- Built-in loading/error states
- Query keys factory for type-safe cache management

**Clean Architecture** (Tenant, IntegrationKey, InfoCenter):
- Repository pattern with localStorage
- UseCase orchestration layer
- Manual state management with useState/useEffect
- Migration to TanStack Query planned

---

## Project Statistics

### Codebase Metrics

| Metric | Count |
|--------|-------|
| **Total Files** | 119 files |
| **Domain Files** | 20 files (~3,998 lines) |
| **Application Files** | 37 files (~5,553 lines) |
| **Infrastructure Files** | 9 files (~2,233 lines) |
| **Presentation Files** | ~50 files (~5,000 est) |
| **Total LOC** | ~16,800+ lines |

### Entity Catalog

| Entity | Lines | Methods | Status |
|--------|-------|---------|--------|
| **Tenant** | 323 | 9 | Production Ready |
| **User** | 401 | 12 | Production Ready |
| **IntegrationKey** | 379 | 8 | Production Ready |
| **DiscoveredPage** | 418 | 7 | Production Ready |
| **PageAnalysis** | 383 | 9 | Production Ready |
| **Company** | 158 | 5 | Production Ready |

### Use Case Breakdown

| Module | Use Cases | Lines |
|--------|-----------|-------|
| **Tenant** | 5 | ~724 |
| **User** | 6 | ~883 |
| **IntegrationKey** | 5 | ~791 |
| **InfoCenter** | 4 | ~1,300 |
| **Company** | 4 | ~639 |
| **Total** | **24** | **~4,337** |

---

## Related Documentation

### Project-Level

- [Project Architecture](../../.ai/ARCHITECTURE.md) - Complete system architecture
- [Documentation Registry](../../docs/DOCUMENTATION_REGISTRY.md) - Central documentation index
- [Progress Tracking](../../.ai/PROGRESS.md) - Current status (read-only reference)

### Packages

- [Domain Package](../../packages/domain/README.md) - Shared domain models
- [API Interface](../../packages/api-interface/README.md) - API contracts and validation
- [Persistence](../../packages/persistence/README.md) - Data persistence with MikroORM

---

## Migration History

### December 2025: TanStack Query Migration (Phases 1-7) - COMPLETE

**Status**: ✅ Complete

**Problem**: Manual state management with Repository + UseCase pattern required 500+ lines of boilerplate per feature, no automatic caching, manual cache invalidation.

**Solution**: Migrated all 5 Dashboard features to TanStack Query hooks across 7 phases.

**Phase 0 (Infrastructure - Dec 19)**:
- Added TanStack Query v5 + React Query DevTools
- Created query-client.ts and query-keys.ts
- Configured QueryClientProvider

**Phase 1 (Users - Dec 19)**:
- **Deleted**: UserRepository (262 lines), all user UseCases (~300 lines)
- **Created**: useUser, useUsers, useUserActions hooks (260 lines)
- **Code Reduction**: 815 lines → 260 lines (76% reduction)

**Phase 2 (Company - Dec 19)**:
- **Deleted**: CompanyRepository (255 lines), company UseCases (~405 lines), ICompanyRepository (~50 lines)
- **Created**: useCompany, useCompanies, useCompanyActions hooks (258 lines)
- **Code Reduction**: 710 lines → 258 lines (63% reduction)

**Phase 3 (Tenants - Dec 20)**:
- **Deleted**: TenantRepository (129 lines), all tenant UseCases (5 files), ITenantRepository
- **Created**: useTenant, useTenants, useTenantActions hooks
- **Code Reduction**: ~350 lines → ~250 lines (29% reduction, NOTE: 77% in final commit due to hook optimization)

**Phase 4 (IntegrationKeys - Dec 20)**:
- **Deleted**: IntegrationKeyRepository (118 lines), all integration-key UseCases (4 files)
- **Created**: useIntegrationKeys, useKeyStats, useIntegrationKeyActions hooks
- **Security**: Plaintext keys never cached (returned only once from mutation)
- **Code Reduction**: ~280 lines → ~200 lines (29% reduction)

**Phase 5-6 (InfoCenter - Dec 20)**:
- **Deleted**: InfoCenterRepository (337 lines), all info-center UseCases (5 files), IInfoCenterRepository
- **Created**: 6 focused hooks (usePages, useAnalyses, usePageActions, useScanProgress, useInfoCenterStats, useInfoCenter orchestrator)
- **Pattern**: Custom polling state (useScanProgress) separate from TanStack Query data fetching
- **Code Reduction**: 843 lines → ~560 lines (33% reduction in orchestrator hook)

**Phase 7 (Final Cleanup - Dec 20)**:
- **Deleted**: Entire use-cases/ directory, IUserRepository (last remaining interface)
- **Updated**: ARCHITECTURE.md to "Fully Migrated" status
- **Result**: Zero repository files, zero use-case files remaining

**Architecture Improvements**:
- Eliminated Repository and UseCase layers completely
- Direct API client usage through TanStack Query hooks
- Automatic caching (5min staleTime for queries, 1min for stats)
- Type-safe query keys factory for all features
- Built-in loading/error states, automatic retry with exponential backoff

**Benefits**:
- **71% average code reduction** (~1,975 lines removed total)
- Automatic request deduplication (3 components = 1 API call)
- Background refetch on window focus/reconnect
- Automatic cache invalidation after mutations
- DevTools for debugging queries/mutations
- Intelligent caching prevents redundant API calls

**Commits**:
- `d42bd6e` - "feat(dashboard): Add TanStack Query infrastructure (Phase 0)"
- `a424c86` - "feat(dashboard): Migrate User and Company to TanStack Query (Phases 1-2)"
- `b53a5b4` - "feat(dashboard): Complete TanStack Query migration for all 5 features (Phases 1-7)"

**Documentation**: See [TanStack Query Migration Guide](../../docs/TANSTACK_QUERY_MIGRATION_GUIDE.md) for complete migration details.

---

### November 2025: InfoCenter Sample Data Bug Fix

**Status**: ✅ Complete

**Problem**: InfoCenter UI displayed empty state on first load, requiring manual data entry for development/testing.

**Solution**: Added automatic sample data initialization to `InfoCenterRepository`:
- **6 new methods** (+389 lines):
  - `initializeIfEmpty()`: Auto-detect empty storage and trigger initialization
  - `initializeSampleData()`: Public method for manual generation
  - `generateDiscoveredPages()`: Create 15 pages with 3-level hierarchy
  - `generatePageAnalyses()`: Create analyses for analyzed pages
  - `generateElements()`: Generate 30-80 realistic elements per page
  - `generateSelectors()`: Create selector strategies with confidence scores

**Data Generated**:
- **15 discovered pages**: Homepage, 5 categories, 5 products, 4 additional pages
- **3-level hierarchy**: Depth 0 (homepage) → Depth 1 (categories) → Depth 2 (details)
- **Page statuses**: ACTIVE, BROKEN, REDIRECT
- **Analysis statuses**: ANALYZED, PENDING, OUTDATED, NONE, FAILED
- **Elements per page**: 30-80 interactive elements with realistic properties
- **Selector strategies**: ARIA, TEXT, CSS, XPATH, POSITION with confidence scores (20-98%)

**Benefits**:
- Zero-configuration development experience
- Instant visual feedback on first run
- Realistic hierarchical data for UI testing
- No manual data entry required

**Commit**: `f7414af` - "fix: Add InfoCenter sample data initialization to prevent empty UI state"

---

### October 2025: Clean Architecture Refactoring

**Status**: ✅ Complete

**Changes**:
- Implemented 4-layer Clean Architecture
- Created 8 domain entities with business logic
- Implemented 24 use cases across 5 modules
- Created 5 repository implementations with localStorage
- Migrated all UI components to use domain entities
- Added path aliases for clean imports
- Zero TypeScript errors, production build successful

**Statistics**:
- **117 files changed** (78 created, 21 modified, 18 deleted)
- **12,014 insertions, 6,355 deletions**
- **42 tasks completed** across 3 phases
- **5 parallel agents** used for development

**Commit**: `4ede8f8` - "feat: Implement Clean Architecture"

---

## Copyright

© 2025 TWWIM UG. All rights reserved. (www.twwim.com)