# Aether Project Naming Conventions

**Last Updated:** 2026-06-12

## 1. General Principles

- **Clarity:** Names should clearly convey their purpose and meaning.
- **Consistency:** Adhere strictly to these guidelines across the entire codebase.
- **Readability:** Prioritize names that are easy to read and understand.
- **Conciseness:** Avoid unnecessary verbosity, but not at the expense of clarity.

## 2. File Naming

- **Logic/Service Files:** `ae_<module>__<concept>.ts` (e.g., `ae_core__account.ts`, `ae_events__event.ts`)
- **Database Definition Files:** `db_<module>.ts` (e.g., `db_core.ts`, `db_journals.ts`)
- **Svelte Store Files:** Follow existing module names. Svelte 5 `PersistedState` files use a `.svelte.ts` suffix and are imported via the `.svelte` module path (for example, `ae_events_stores__badges.svelte.ts`).
- **Svelte Components:**
    - **Route-level components:** `ae_comp__<component_name>.svelte`.
    - **Module-specific components:** `ae_<module>_comp__<component_name>.svelte` (for example, `ae_events_comp__session_list.svelte`).
    - **Generic/reusable components:** `element_<component_name>.svelte` (e.g., `element_input_file.svelte`, `element_qr_scanner_v2.svelte`)
- **SvelteKit Routes:** Follow SvelteKit's standard routing conventions (e.g., `+page.svelte`, `+layout.svelte`, `[id]/+page.svelte`).
- **CSS Files:** `ae-<module>-<purpose>.css` (e.g., `ae-c-idaa-light.css`, `ae-osit-default.css`)

## 3. Function and Variable Naming

- **Style:** Strictly `snake_case` for all function and variable names.
    - **Deprecated:** `camelCase` should be refactored to `snake_case`.
- **Prefixes:**
    - `load_ae_obj_id__<object_type>`: For loading a single Aether object by ID.
    - `load_ae_obj_li__<object_type>`: For loading a list of Aether objects.
    - `create_ae_obj__<object_type>`: For creating an Aether object.
    - `update_ae_obj__<object_type>`: For updating an Aether object.
    - `delete_ae_obj_id__<object_type>`: For deleting an Aether object by ID.
    - `db_save_ae_obj_li__<object_type>`: For saving a list of Aether objects to IndexedDB.
    - `db_update_ae_obj_id__<object_type>`: For updating an Aether object in IndexedDB.
    - `process_ae_obj__<object_type>_props`: For module-specific data transformation functions.
    - **Deprecated:** Ambiguous `handle_` prefixes should be replaced with more descriptive `snake_case` names (e.g., `handle_submit_form` -> `submit_form`).

## 4. Object and Property Naming

- **Singularity:** Use singular nouns for objects and properties (e.g., `example.id`, not `examples.id`).
- **IDs:**
    - `<object_type>_id`: Canonical randomized string ID returned by V3 (for example, `person_id`).
    - `id`: Generic randomized string alias when V3 returns one; never assume it is an integer autonumber.
    - `<object_type>_id_random`: Legacy alias; do not introduce new usage.
    - `account_id`, `site_id`, `user_id`, etc.: Foreign keys.
- **Common Properties:**
    - `code`: Short, unique identifier.
    - `name`: Display name.
    - `description`: Longer text description.
    - `enable`: Boolean for active/inactive status.
    - `hide`: Boolean for visibility.
    - `priority`: Boolean/tinyint(1) ordering flag used by the object model.
    - `sort`: Numeric value for ordering within a priority group.
    - `group`: Categorization string.
    - `notes`: General notes/comments.
    - `created_on`: Timestamp of creation.
    - `updated_on`: Timestamp of last update.
- **Special Use Properties:** `for_type`, `for_id`, `archive_on`, `passcode`, `external_id`.
- **Config/JSON Properties:** `cfg_json`, `data_json`, `linked_li_json`.
- **Special Generated Fields (Client-side):** `tmp_sort_1`, `tmp_sort_2`, `tmp_sort_3` (for client-side sorting).

## 5. List Suffixes

- **Simple Arrays:** Use `_li` suffix for simple, unordered arrays (e.g., `user_li`, `hosted_file_id_li`).
- **Key-Value Maps/Objects:** Use `_kv` suffix for key-value objects/maps (e.g., `user_kv`, `hosted_file_obj_kv`).

## 6. Interface and Type Naming

- **Style:** Use `PascalCase` for interface and type names (e.g., `Account`, `HostedFile`, `GenericCrudArgs`).

## 7. Constants

- **Style:** Use `SCREAMING_SNAKE_CASE` for constants (e.g., `MAX_RETRIES`, `DEFAULT_TIMEOUT`).

## 8. CSS Classes and IDs

- **Style:** Use `kebab-case` for CSS classes and IDs (e.g., `my-component-class`, `main-header-id`).

## 9. Data Sorting

- **Standard Order:** `group > priority (flag) > sort > updated_on/created_on`
- **Specific Order:** `type > start_date/time > code or name`

## 10. Local Storage and IndexedDB Keys

- **Local Storage:**
    - `api`
    - `app` (global)
    - `core` (core modules)
    - `<module>` (extended modules)
    - `<custom>` (custom modules)
- **IndexedDB:**
    - `db_core`
    - `db_<module>` (for example, `db_events`, `db_journals`)
    - `<custom>`
