OSIT-AE-App-Svelte/NAMING_CONVENTIONS.md

Aether Project Naming Conventions

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: ae_<module>_stores.ts (e.g., ae_core_stores.ts, ae_journals_stores.ts)
• Svelte Components:
  • Module-specific components: ae_comp__<module>__<component_name>.svelte (e.g., ae_comp__events__event_card.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:
  • id: Primary key for an object (internal use, often a UUID).
  • <object_type>_id: Specific ID for an object (e.g., person_id).
  • <object_type>_id_random: Randomly generated ID for an object (often used for external exposure or URL parameters).
  • 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: Numeric value for ordering.
  • sort: Numeric value for ordering.
  • 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 > 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:
  • ae_core_db
  • <module>
  • <custom>