# Aether (AE) Event Lead Retrieval Module (v3)

## Overview

This is a major work in progress. It still needs the overall directory and file structure planned, documented, and created.

This module provides a comprehensive solution for event exhibitors to capture and manage leads. It supports exhibitor login, badge scanning for lead capture, manual lead entry, lead qualification (ranking/priority), and data export functionalities. It integrates with the Aether API for data synchronization and utilizes local caching for performance and offline capabilities.

## Key Features

- **Exhibitor Login:** Secure access for exhibitors using a shared passcode or individual license keys (email-based).
- **Lead Capture:** Efficiently add new leads by scanning attendee badge QR codes or through manual data entry.
- **Lead Management:** A dedicated interface for exhibitors to view, sort, and manage their collected leads.
- **Lead Qualification:** Tools to rank and prioritize leads (e.g., sort, star/favorite) for follow-up.
- **Data Export:** Functionality to export collected lead data, typically to an Excel-compatible format.
- **Real-time Synchronization:** Data is synchronized with the backend Aether API.
- **Local Caching:** Utilizes IndexedDB (Dexie.js) for robust local data storage, enabling offline use and faster load times.

## Data Model

The core data structures managed by this module are `Exhibit` and `Exhibit_tracking`. The actual DB table name is event_person_tracking. It was originally intended for generalized "tracking" of a person at an event. This would include other things like session attendance tracking, in addition to exhibitor lead retrieval. However, the initial implementation is focused solely on the lead retrieval use case for exhibitors.

### Exhibit

Represents an exhibitor's presence at an event. It contains configuration for lead retrieval, such as:

- `event_exhibit_id`: Unique identifier for the exhibit (primary key).
- `code`, `name`, `description`: Basic information about the exhibit.
- `staff_passcode`: For staff login.
- `leads_api_access`: Boolean indicating if lead retrieval API access is enabled.
- `leads_custom_questions_json`: Configuration for custom questions asked during lead capture.
- `license_max`, `license_li_json`: Details regarding lead retrieval licenses.

### Exhibit_tracking

Represents a single lead captured by an exhibitor. It links an exhibitor to an attendee (badge) and stores details about the interaction:

- `event_exhibit_tracking_id`: Unique identifier for the captured lead (primary key).
- `event_exhibit_id`: Links to the `Exhibit` that captured the lead.
- `event_badge_id`: Links to the attendee's `Badge` information.
- `exhibitor_notes`: Notes added by the exhibitor about the lead.
- `responses_json`: Responses to custom questions.
- Contains duplicated badge information for convenience (e.g., `event_badge_full_name`, `event_badge_email`, `event_badge_professional_title`, `event_badge_affiliations`) to denormalize data for faster display.

## Routing and Components

### Routes

- `/events/[event_id]/(leads)`: The main entry point for the Leads module within a specific event, typically displays a list of available exhibits.
    - `+page.svelte`: Renders the list of exhibits.
    - `+page.ts`: Loads the data for available exhibits using `events_func.load_ae_obj_li__event_exhibit`.
    - `+layout.svelte`/`+layout.ts`: Provides a common layout and data for the module, including a submenu.
- `/events/[event_id]/(leads)/exhibit/[slug]`: Dynamic route for managing leads for a specific exhibitor within an event. The `[slug]` corresponds to `event_exhibit_id`.
    - `+page.svelte`: The primary interface for an exhibitor, orchestrating lead capture and management components.
    - `+page.ts`: Loads specific `Exhibit` data and associated `Exhibit_tracking` (leads) using `events_func.load_ae_obj_id__event_exhibit` and `events_func.load_ae_obj_li__event_exhibit_tracking`.

### Core Components (within `src/routes/events/[event_id]/(leads)/exhibit/[slug]/`)

- `leads_add_scan.svelte`: Handles the process of adding new leads, either by scanning QR codes (badge) or manual entry.
- `leads_list.svelte`: Displays a sortable and filterable list of captured leads for the current exhibitor.
- `leads_manage.svelte`: Provides functionalities for managing individual leads, potentially including editing notes or qualification status.
- `leads_payment.svelte`: (If applicable) Component related to handling payment or license activation for lead retrieval features.
- `leads_view_lead.svelte`: Displays detailed information for a selected lead.

## Technical Implementation

- **Svelte v5 with Runes:** The module adheres to Svelte v5's reactivity model, utilizing `$state` and `$derived` for reactive state management.
- **ID Convention (`id`):** All frontend operations, including routing and data fetching, consistently use the string-based `event_exhibit_id` and `event_exhibit_tracking_id` as primary identifiers, rather than numeric `id` values.
- **API Interaction:** Data is fetched and synchronized with the backend FastAPI application through functions exposed in `src/lib/ae_events_functions.ts`.
- **Local Database (Dexie.js):** Data for `Exhibit` and `Exhibit_tracking` is cached in the browser's IndexedDB using Dexie.js, defined in `src/lib/ae_events/db_events.ts`. This ensures data persistence and fast retrieval, especially for offline scenarios.
- **Styling:** The UI is primarily styled using Tailwind CSS, having migrated from Skeleton UI to resolve previous rendering issues.