Fetch city location suggestions from AstroMatrix or Google Places API. Summary: Retrieves a list of possible birth location suggestions matching the provided query string. Uses Google Places Autocomplete API when useGoogleAPI is true, otherwise uses AstroMatrix API.

Fetch city locations from AstroMatrix API (default implementation)

Fetch city locations from Google Places Autocomplete API

Fetch detailed city information from AstroMatrix or Google Places Details API. Summary: Requests detailed metadata for a given town name (e.g., coordinates, timezone hints). Uses Google Places Details API when useGoogleAPI is true, otherwise uses AstroMatrix API.

Fetch city info from AstroMatrix API (default implementation)

Fetch city info from Google Geocoding API

Fetch timezone data from Google Timezone API or TimeZoneDB. Summary: Retrieves timezone information for a given geographic coordinate and timestamp. The implementation selects between Google Timezone API and TimeZoneDB based on the `useGoogleAPI` flag.

Get planet positions for ephemeris table (month view). Summary: Fetches daily planet positions for a given month and year. Returns positions for all planets (inner and outer) at midnight UTC for each day of the month.

Calculate chart positions by sending chart payload to the CalcPositions endpoint. Summary: Sends a ChartPayload to the astrology calculation endpoint and returns the computed chart data.

Reverse geocode coordinates to get formatted address/town name

Calculate horoscopes based on provided chart data. Summary: Sends computed chart data to the horoscope calculation endpoint to generate horoscope text/entries.

Generate AI-based report for a given chart. Summary: Sends a chart payload and desired report type to the AI report endpoint and returns the generated report content.

Dispose resources used by the AstroApiService. Summary: Placeholder for cleanup logic. Currently a no-op but provided for lifecycle parity.

Returns the singleton instance of [DeviceService].

Initialize device information by fetching the device ID and platform.

Determines and caches the device ID based on the current platform.

Retrieves the iOS vendor identifier using device_info_plus. Returns a fallback string on failure.

Retrieves the Android ID using the android_id plugin. Returns a fallback string on failure.

Returns a normalized platform name for the current OS.

Returns timezone information containing the timezone name and offset in minutes. The `timeZoneOffset` value is the negated offset in minutes from UTC.

Allow backend override for testing or alternative implementations

Generate a completion from a simple text prompt

Helper method for quick questions with default settings

Helper method for creative content generation

Helper method for analytical/factual responses

Translate text from one language to another If fromLanguage is null, auto-detects source language

Allow backend override for testing or alternative implementations

Generate a completion from a simple text prompt

Helper method for quick questions with default settings

Helper method for creative content generation

Helper method for analytical/factual responses

Translate text from one language to another If fromLanguage is null, auto-detects source language

Allow backend override for testing or alternative implementations

Generate a completion from a simple text prompt

Helper method for quick questions with default settings

Helper method for creative content generation

Helper method for analytical/factual responses

Translate text from one language to another If fromLanguage is null, auto-detects source language

=============================================================== CACHE EXPIRY HELPERS ===============================================================

Calculate expiry timestamp from duration Returns null if duration is null (no expiry)

Check if a record is expired

=============================================================== ADVANCED EXPIRY METHODS (for granular control) ===============================================================

Create record with specific expiry (bypasses defaultExpiry)

Update record and refresh its expiry time

=============================================================== STANDARD CRUD METHODS ===============================================================

Get all records for a parent key

Get single record by ID

Create a new record Uses JsonStorageService.defaultExpiry for cache expiry (null = never expires)

Update existing record Keeps existing expiry unless record is new/recreated

Delete record (soft delete - marks as deleted)

=============================================================== INVALIDATION METHODS ===============================================================

Invalidate all records for a specific parent key Example: When user's birth data changes, invalidate all their charts

Invalidate specific record by ID Example: Invalidate a single chart

Invalidate all records in a namespace Use sparingly! Only for logout or complete refresh

Invalidate records older than a certain age Example: Delete transits older than 30 days

Invalidate (soft delete) expired records Returns the count of records invalidated

=============================================================== SYNC METHODS ===============================================================

Get unsynced records for background sync

Mark record as synced (optionally replace local ID with server ID)

OPTIMIZED: Sync records from server using batch operations This prevents database locks by using transactions Uses JsonStorageService.defaultExpiry for cache expiry

=============================================================== CLEANUP METHODS ===============================================================

Hard delete synced deletions (cleanup after successful sync)

Hard delete expired records (cleanup) Returns the count of records deleted

Clear all records for a namespace (hard delete)

Clear all data (for testing or logout)

=============================================================== STATISTICS & DEBUGGING ===============================================================

Get statistics for debugging

Returns the singleton instance of [LanguageService].

Initializes the service by loading the saved language from persistent storage and ensuring the corresponding translation table is available.

Sets the active language, persists it, and reloads the translation table.

Ensures the translation table for the current language is loaded; no-op if already available.

Fetches the language table for the current language from the remote API and caches it for synchronous lookups; does nothing for English.

Loads translation table from local storage cache.

Saves translation table to local storage cache.

Clears the cache for a specific language or all languages.

Loads the skip list from persistent storage. Called during initialization to restore previously saved skip list.

Saves the skip list to persistent storage. Called automatically whenever the skip list is modified.

Checks if a text should be skipped from translation. Returns true if the text matches patterns that indicate it shouldn't be translated (e.g., dates, numbers, URLs, emails, names, etc.)

Adds a string to the skip list so it will never be translated. Useful for names, proper nouns, or other content that should remain unchanged. The skip list is automatically persisted to storage.

Adds multiple strings to the skip list. The skip list is automatically persisted to storage.

Removes a string from the skip list. The skip list is automatically persisted to storage.

Clears the entire skip list. The skip list is automatically persisted to storage.

Returns a translated string for [name] using the cached language table or the original text if no translation exists. If translation is missing, triggers a background GPT translation that will be available on next call. Supports simple transformation modes via [type] ('split' to translate each space-separated token, 'time' to translate only the first token). **Performance Note:** This method NEVER calls the API. It only reads from the in-memory cache (_languageItems). The cache is: - Loaded from local storage on app startup (fast) - Fetched from API only if cache is missing or stale (>7 days) - Updated in memory and persisted to storage after API fetch You can call getLang() thousands of times per second with zero API calls.

Triggers a background GPT translation without blocking. Uses debouncing and batching to optimize API calls.

Processes the translation queue by batching all pending strings into one API call. Respects rate limiting to prevent API overload.

Performs batch GPT translation for multiple strings in one API call. This is much more efficient than individual calls.

Creates a batch translation prompt that GPT can process. Format: "Translate these English strings to [Language]. Return JSON format: {\"string1\": \"translation1\", \"string2\": \"translation2\"}"

Parses the batch translation response from GPT. Expects JSON format: {"original": "translation", ...} Handles various response formats GPT might return.

Fallback: Translate strings individually if batch fails. Only used as last resort.

Performs the actual GPT translation and caches the result. @deprecated Use _performBatchGPTTranslation instead for better performance.

Clears the GPT translation cache for the current language

Cancels any pending translation requests and clears the queue. Useful when language changes to prevent stale translations.

Global convenience that delegates to the singleton [LanguageService] for a synchronous translation lookup. Automatically triggers background GPT translation for missing keys.

Factory that returns the singleton [LoggingService] instance.

Sends an error or info log to the Node API or base API depending on `useNode`. Short summary: constructs a payload with uid, message, info, platform and timestamp and POSTs it to the logging endpoint.

Convenience helper that logs an informational message. Calls [logError] with "INFO: " prefixed to the message.

Prints a debug-only message to the console when in debug mode. Short summary: outputs a debug-only message using `debugPrint` when `kDebugMode` is true. Does not perform network I/O.

Static helper to log ad-specific errors under the 'ads' user/category.

Static helper to log ad-specific informational messages under the 'ads' category.

Debug-only ad logging that prints JSON-encoded data when in debug mode.

Logs a metric event with name, type, value, and optional labels to the metrics endpoint. Short summary: builds an event payload and POSTs it to the metrics update endpoint.

Convenience method for logging counter metrics (delegates to [logEvent]).

Convenience method for logging gauge metrics (delegates to [logEvent]).

Get house system display name from code

Build payload from UserProfile(s) for self or relationship charts Parameters: - user1: Primary user (required) - prefs: Chart calculation preferences (house system, orbs, etc.) - chartType: Type of chart ('self', 'relationship', 'birthchart', etc.) - user2: Secondary user for relationship charts (optional) - transitDate: Date for transit calculations (optional) - transitLocation: Location for transit calculations (optional) Returns: ChartPayload ready for API submission

Build payload from BirthForm for chart creation/preview Used when creating a new user or previewing a chart from form data before saving the user profile. Parameters: - form: Birth form data (name, date, time) - location: Birth location data - prefs: Chart calculation preferences - transitDate: Optional transit date - transitLocation: Optional transit location Returns: ChartPayload ready for API submission

Build payload for current planets (no birth data required) Shows current planetary positions without reference to a birth chart. Parameters: - prefs: Chart calculation preferences - date: Date/time for planet positions (defaults to now) - location: Location for calculations (optional) Returns: ChartPayload for current planets

Convert UserProfile to ChartDate format for API payload Extracts all necessary birth data from user profile and formats it according to API requirements. Uses web-compatible format for fullDateStr. Optional location overrides allow changing location without modifying the user profile (useful for relocation charts).

Convert UserProfile to ChartDate format for date2 (minimal fields like web) Web's date2 doesn't include: type, timeHour, timeMinute, timePM, dst, mainUser, selectedTown

Build fullDateStr in web-compatible format Format: "January 11th 2000 5:00 PM" (note: double space before year)

Convert BirthForm + Location to ChartDate format for API payload Parses form data (YYYY-MM-DD date format, various time formats) and combines with location data to create complete ChartDate.

Build transit date ChartDate from DateTime and optional Location Used for transit charts, current planets, progressed charts, etc. Uses 24-hour time format for transit dates.

Build fullDateStr for transit date in web-compatible format Format: "December 24th 2025 12:09" (note: double space before year, 24h time)

Get human-readable type name for chart type

Get API path for chart type

Get house system display name from code

Build payload from UserProfile(s) for self or relationship charts Parameters: - user1: Primary user (required) - prefs: Chart calculation preferences (house system, orbs, etc.) - chartType: Type of chart ('self', 'relationship', 'birthchart', etc.) - user2: Secondary user for relationship charts (optional) - transitDate: Date for transit calculations (optional) - transitLocation: Location for transit calculations (optional) Returns: ChartPayload ready for API submission

Build payload from BirthForm for chart creation/preview Used when creating a new user or previewing a chart from form data before saving the user profile. Parameters: - form: Birth form data (name, date, time) - location: Birth location data - prefs: Chart calculation preferences - transitDate: Optional transit date - transitLocation: Optional transit location Returns: ChartPayload ready for API submission

Build payload for current planets (no birth data required) Shows current planetary positions without reference to a birth chart. Parameters: - prefs: Chart calculation preferences - date: Date/time for planet positions (defaults to now) - location: Location for calculations (optional) Returns: ChartPayload for current planets

Convert UserProfile to ChartDate format for API payload Extracts all necessary birth data from user profile and formats it according to API requirements. Uses web-compatible format for fullDateStr. Optional location overrides allow changing location without modifying the user profile (useful for relocation charts).

Convert UserProfile to ChartDate format for date2 (minimal fields like web) Web's date2 doesn't include: type, timeHour, timeMinute, timePM, dst, mainUser, selectedTown

Build fullDateStr in web-compatible format Format: "January 11th 2000 5:00 PM" (note: double space before year)

Convert BirthForm + Location to ChartDate format for API payload Parses form data (YYYY-MM-DD date format, various time formats) and combines with location data to create complete ChartDate.

Build transit date ChartDate from DateTime and optional Location Used for transit charts, current planets, progressed charts, etc. Uses 24-hour time format for transit dates.

Build fullDateStr for transit date in web-compatible format Format: "December 24th 2025 12:09" (note: double space before year, 24h time)

Get human-readable type name for chart type

Get API path for chart type

Initialize all preferences with defaults on first app start

Upsert preferences (create or update)

Set preference that works even when not logged in (mainly for language)

Save preference locally and sync to server

Sync preference to WebView

Invalidate chart cache if preference affects chart calculations

Get all preferences for current user

Delete a specific preference

Sync to server in background (don't await)

Sync from server FIXED: Uses ApiResult properties

Force sync unsynced preferences to server

Bulk update multiple preferences

Clear all preferences for current user

Export all preferences as JSON

Import preferences from JSON

Normalize raw value to expected type Handles legacy cases where server has "true", "6.0", "1" as strings

Initializes and connects the socket to the server and registers the given user.

Emits a `new_message` event with the provided payload to the server.

Registers a callback for incoming `message_received` events from the server.

Disconnects the socket and releases network resources.

Factory constructor returning the singleton AdsService instance.

Initialize the ads service

Load ads state from SharedPreferences

Enable or disable ads

Hide all ads (called when user subscribes)

Dispose all ad objects

Load and show banner ad

Load and show interstitial ad

Load rewarded interstitial ad

Show rewarded interstitial ad

Check if ads should be shown based on web app request

Update user info

Log error to server

Handle load ad error

Handle show ad error

Dispose all resources

Logs an analytics event to Firebase Analytics, defaulting to 'purchase_completed' and including product_id when provided.

Validates birth information by calculating a chart and extracting the Big Three. Uses ChartService.calculatePositionsForForm() which doesn't require a UserProfile.

Quickly checks whether the provided form and location appear complete for submission.

Validates an ISO-8601 date string for birth date constraints.

Validates a time string in HH:mm format.

Validates the overall birth form for required fields.

Get items for a category Used by ItemCategoryCtrl equivalent in Flutter

Get items for a category Used by ItemCategoryCtrl equivalent in Flutter

Initialize once on app start

Render a single chart

Render multiple pattern charts

Build pattern config - MATCHES NORMAL CHARTS

Build pattern astro data

Generate default houses

Get display label for a chart type Uses the displayName getter from ChartType enum

Build chart render config from chart type and screen size

Transform raw chart result into display-ready planet data

Transform transit planets with display data

Transform houses with display data

Build aspect grid for display (full matrix) Builds from transitData array to match Angular structure: planets[i].aspects[j] = { Aspect, Orb, Item }

Get aspect grid for first 10 planets only (for compact display)

Get aspect grid for asteroids with specific horizontal/vertical layout Horizontal (columns): Lilith, Chiron, Pholus, Ceres, Pallas, Juno, Vesta, Eris, Eros, Psyche Vertical (rows): Lilith, Chiron, Ceres, Pallas, Juno

Get horizontal asteroid planets for grid columns

Get vertical asteroid planets for grid rows

Get chart titles based on chart type

Check if chart type should show transits

Check if chart type should show houses

Check if chart type should show declinations

Check if chart type needs second user

Calculate image width based on screen width

Format declination for display

Format house number as ordinal

Get aspect color for display

Get aspect symbol for display

Get planet image URL

Get sign image URL

Get aspect image URL

Get pattern formations as typed models

Render all aspect patterns from chart data

Check if patterns exist

Get pattern count

Clear pattern cache

Open component view - handles everything Central method for opening component screen from anywhere in the app. Creates MatrixItem and navigates to ComponentScreen. Example: ```dart ComponentService.openComponentView( context, componentName: 'Sun', category: 'Zodiac Planets', ); ```

Create a MatrixItem for navigation to ComponentScreen Helper method to create properly formatted MatrixItem objects for use with ComponentScreen navigation. Example: ```dart final item = ComponentService.createMatrixItem( componentName: 'Sun', category: 'Zodiac Planets', ); Navigator.push( context, MaterialPageRoute( builder: (context) => ComponentScreen(matrixItem: item), ), ); ```

Get component data with automatic traits parsing ✅ Returns both component data AND parsed traits in a single call ✅ Delegates to TarotService for tarot-related categories

Parse traits from GetComponent API response ✅ Automatically called by getItem()

Transform flat array API response into grouped structure ✅ FULLY DYNAMIC - automatically handles ANY trait category from API ✅ No hardcoded categories - add new categories in database without code changes

Get image URL for component ✅ Delegates to ComponentImageHelper for unified image handling Supports both standard components and tarot cards

Get glossary terms Endpoint: /help/get?type=Glossary

Search horoscope items Endpoint: /API/Astrology/GetHoroscopeItems?search={query}

Get glossary terms Endpoint: /help/get?type=Glossary

Search horoscope items Endpoint: /API/Astrology/GetHoroscopeItems?search={query}

Show help for a specific page/section/type Endpoint: /help/get?page={page}&section={section}&type={type}

Initialize the service singleton. Safe to call multiple times - only initializes once. Call this early in main() before runApp().

Internal initialization - loads previously saved users.

Persist user1 ID to preferences.

Persist user2 ID to preferences.

Set primary user for calculations.

Set secondary user for relationship calculations.

Set transit date for transit calculations.

Clear secondary user.

Clear both users (useful for logout scenarios).

Apply visibility preferences to chart data before rendering Reads preferences and sets showPlanet flag on each planet Works with PreferenceService/StorageService preferences Usage: ```dart final chartData = await calculateChart(...); final filteredData = await AstroHelper.applyChartPreferences(chartData); final pngBytes = await renderer.renderChart(filteredData, config); ```

Load chart calculation preferences from PreferenceService.

Calculate chart positions (planets, houses, aspects). Uses current user1 and optionally user2/transitDate. Results are cached by user ID and date.

Calculate positions directly from BirthForm and Location. Used for birth validation before a UserProfile is created. Does not use or affect internal state (user1/user2). Results are NOT cached (no user ID to cache against).

Get ephemeris data (planet positions for a month)

Calculate horoscopes with interpretations.

Internal method to fetch horoscopes from API Extracted to allow request deduplication

Invalidate all cached data for a user. Call this when user's birth data changes.

Invalidate old transit data.

Build cache key from current state.

Build ChartPayload from current state. Build ChartPayload from current state.

Find a chart by its type from the charts list Searches for a chart matching the target type by checking type fields. Returns null if chart not found.

Get chart by type or fall back to index Tries to find chart by type first, falls back to index if not found.

Get LifePath numerology data Parameters: - fromChart: Which chart to get LifePath from - ChartType.birth: Permanent birth life path (default) - ChartType.transit: Daily number (birth + transit date)

Get Big Three (Sun, Moon, Ascendant) from birth chart Returns BigThree with Placement objects for sun, moon, and ascendant Returns null if any of the three are missing

Get extended moon information (always from transit/daily chart)

Get planetary hours data (always from transit/daily chart)

Get chakra balance data

Get all planets Parameters: - fromChart: Which chart type to get planets from - ChartType.birth: Natal planet positions - ChartType.transit: Current planet positions with transit houses (default)

Get specific planet by name

Get Mayan astrology data (always from birth chart)

Get profection data (from transit chart)

Get psychology analysis (short version)

Returns a random ad filtered by type. Call this in widget's initState to get a fresh random ad each time the page is created.

Fetches the live server configuration from the node endpoint, compares it with stored configuration and optionally saves or navigates based on device/SDK constraints and detected changes.

Loads the last saved LiveServerData from SharedPreferences if present.

Persists the given LiveServerData to SharedPreferences as JSON.

Retrieves the daily splash image and quote from the API and stores them in SharedPreferences and global variables for immediate use before app bootstrapping.

Validates an in-app purchase receipt with the backend and logs the validation steps; returns the backend response map on success.

Sends purchase information to the backend, optionally including affiliate details, and logs execution traces for debugging.

Fetches a list of verified affiliate codes from the backend and returns an empty list on error or unexpected response formats.

Check if location service is enabled

Check and request location permissions

Get current GPS coordinates

Complete location flow: check service, permissions, get location

Get current GPS position (just coordinates, no WebView)

Reverse geocode coordinates to get town name

Search for locations with debouncing

Search for locations (no debouncing)

Select location from suggestion

Select location and get full details with timezone

Cancel pending searches

Get all conversations for the current user

Get messages between two users

Validate/approve a user by email

Get current user ID from storage

Format timestamp for display

Send a message and return list of messages to add to UI For support: calls HTTP endpoint and returns [userMessage, autoResponse] For regular: emits via socket and returns [userMessage]

Helper: Navigate directly to a conversation with any user For support: userId = 'support@astromatrix.org' For regular users: userId = their actual ID

Get extended moon information Fetches current moon phase, next moon events, VOC/OOB status, etc. Data comes from the transit chart in HoroscopeService. Returns null if data unavailable or on error.

Get just the current moon phase info

Get next moon phase event

Get next lunar event (eclipse, etc)

Check if moon is currently void of course

Check if moon is currently out of bounds

Calculate moon width based on perigee percentage (matching AngularJS logic)

Determine if this is a Super Moon (>90% perigee)

Determine if this is a Micro Moon (<10% perigee)

Get moon special type (Super/Micro/null)

Build full moon string like "Full Moon in Aries"

Initializes the local notifications plugin and registers a response callback to handle interactions when the app is active.

Subscribes to foreground Firebase messages and triggers local notification display and handlers.

Requests notification permissions from the platform via Firebase Messaging. Prints debug logs about user's decision.

Configures notification topic group and creates notification channels.

Creates an Android notification channel with the given identifiers and importance.

Checks and requests notification permission using the permission_handler package, opening app settings if the permission is denied or permanently denied.

Builds a notification channel and displays a local notification for the given RemoteMessage.

Retrieves the FCM device token for this client.

Subscribes to token refresh events to react when the FCM token is rotated.

Configures handling for notification interactions when the app is backgrounded or terminated.

Handles a notification tap or interaction and performs appropriate in-app navigation or actions.

Configures foreground notification presentation options on iOS so alerts, badges, and sounds are shown.

Factory constructor that returns the singleton instance.

Initialize the purchase service and connect to the platform store.

Update the cached user ID (useful after login changes).

Connect to the platform store, subscribe to purchase stream, and fetch available products and past purchases.

Process incoming purchase updates from the platform purchase stream. Validates receipts (iOS), posts payment info to backend, completes purchases, and logs events; handles pending, restored, error, and purchased statuses.

Convert a PurchaseDetails object into a compact JSON string for storage.

Handle IAP errors (currently logs to debug output).

Initiate purchase flow for a non-consumable product and handle platform specifics such as pending transactions or past purchases.

Query the store for available products, populate local lists, and persist product data to SharedPreferences and webview if available.

Restore or query past purchases from the store, process Android startup purchases, persist results, and log findings.

Persist product JSON to SharedPreferences and optionally send it to the embedded webview client.

Persist purchase JSON to SharedPreferences, send it to webview, and clear affiliate code state if applicable.

Post payment info to backend and call onSuccess when backend confirms.

Check current local subscription status derived from restored purchases.

Public entry to restore purchases (invokes internal restore logic).

Dispose of subscriptions and platform-specific delegates.

Allow continued processing of transactions by default.

Indicate whether price consent UI should be shown; returns false here.

Factory constructor that returns the singleton instance.

Initialize the purchase service and connect to the platform store.

Update the cached user ID (useful after login changes).

Connect to the platform store, subscribe to purchase stream, and fetch available products and past purchases.

Process incoming purchase updates from the platform purchase stream. Validates receipts (iOS), posts payment info to backend, completes purchases, and logs events; handles pending, restored, error, and purchased statuses.

Convert a PurchaseDetails object into a compact JSON string for storage.

Handle IAP errors (currently logs to debug output).

Initiate purchase flow for a non-consumable product and handle platform specifics such as pending transactions or past purchases.

Query the store for available products, populate local lists, and persist product data to SharedPreferences and webview if available.

Restore or query past purchases from the store, process Android startup purchases, persist results, and log findings.

Persist product JSON to SharedPreferences and optionally send it to the embedded webview client.

Persist purchase JSON to SharedPreferences, send it to webview, and clear affiliate code state if applicable.

Post payment info to backend and call onSuccess when backend confirms.

Check current local subscription status derived from restored purchases.

Public entry to restore purchases (invokes internal restore logic).

Dispose of subscriptions and platform-specific delegates.

Allow continued processing of transactions by default.

Indicate whether price consent UI should be shown; returns false here.

Returns the shared QRService singleton used to manage scanning and scan state.

Get camera permission for QR scanning

Scan QR code using the camera

Dispose resources

Generate an astrological report dynamically based on chart type. This method handles all report types using a single interface. It leverages HoroscopeService for payload building to avoid duplication.

Validate inputs based on chart type requirements

Build chart payload using PayloadService Uses PayloadService public methods to build payload for reports. This ensures consistency with chart calculations throughout the app.

Generate AI report from structured data Use this for reports that don't require chart calculations: - Matrix category reports - Tarot readings (future) - Ritual guidance (future) Backend handles: - Prompt template selection - Constraint validation - AI generation - Response logging for AITrainer

Generate Matrix category report Type-safe wrapper for Matrix reports. Takes a MatrixReportRequest which contains all necessary data and metadata. Example: ```dart final request = MatrixReportRequest( category: 'Path & Career', viewFilter: 'foundation', items: filteredItems, userName: user.name, matrixType: MatrixType.self, ); final result = await reportService.generateMatrixReport(request); ```

Convert to JSON for backend

Normalize UI filter names to backend constants 'foundation' → 'foundation' 'journey' → 'journey' 'all aspects' → 'all'

Get degree information including Sabian symbol Example API call: ``` GET https://astromatrix.org/API/Astrology/GetDegreeInfo ?degree=22 &sign=Sagittarius &type=Transit ```

Get degree info from MatrixItem

Get Sabian symbol image URL (REMOTE - use Image.network)

Get Sabian image URL from DegreeInfo

Get tarot card image URL (REMOTE - use Image.network)

Check if a degree is a critical degree ✅ Uses AstroHelper for modality lookup

Convert Princess to Page, Prince to Knight Matches convertTarotTitle() in JS

Get tarot card data from API WITH AUTO-FETCHED TRAITS ✅ Matches getTarotCard() in JS ✅ Automatically fetches and includes traits in result ✅ NO CACHING - ComponentService handles caching when called via getItem() Parameters: - [cardImage]: Card key/image (e.g., "The Fool", "A00", etc.) - [deck]: Deck type ("rider waite", "astrotarot", "1" for reversed, null for default) - [reversed]: Whether card is reversed - [theme]: Card theme (optional) - [timeframe]: Timeframe in seconds (default: 60) - [category]: Trait category for API call (e.g., "Tarot", "Tarot Minor Arcana") - [language]: Language code (default: current language)

Get tarot card as ComponentResult (for ComponentService integration) ✅ Called by ComponentService when category is tarot-related ✅ Returns ComponentResult format with traits included ✅ NO CACHING - ComponentService handles caching

Fetch tarot traits from GetComponentTraits API ✅ Called internally by getTarotCard() ✅ NO CACHING - ComponentService handles caching

Transform flat array API response into grouped structure ✅ FULLY DYNAMIC - automatically handles ANY trait category from API

Open tarot card modal (convenience method) Matches openTarotCard() in JS

Open tarot card from URL link Matches openTarotLink() in JS Parses URL like: /tarot/astrotarot/A00 Extracts card code (A00) and opens with astrotarot deck

Get spread layout array - matches getSpreadBits() in JS Returns array where 0 = empty cell, 1-7 = card position For 3x3 grid spreads, returns 9 elements For linear spreads, returns card count

Get tarot spreads from API Matches getTarotSpreads() in JS Caches results for performance

Get tarot reading from API Matches the GetTarotReading API call in TarotCtrl.js

Get list of cards by section (wands, pentacles, cups, swords, major) Matches getTarotList() in JS

Open tarot card detail screen InputParameters: - [cardName]: Name of the tarot card (e.g., "The Fool") - [context]: BuildContext for navigation For simplicity, this method creates a minimal MatrixItem and navigates to ComponentScreen directly. [category] is derived from the card name.

Clear cached spreads (useful for refresh or logout)

Callback that main.dart will register to rebuild the app

Initialize theme from preferences

Update theme and save to preferences

Diagnostic Test: Form vs UserProfile Calculation This test uses the SAME birth data and calls it two ways: 1. calculatePositionsForForm() - which gives CORRECT results 2. Save as UserProfile, then calculatePositions() - which gives WRONG results We then compare the payloads and results to find the difference.

Application entry point that initializes platform bindings, services, and runs the app. Summary: - Initializes Flutter bindings, language service, integration splash info, and Firebase. - Applies system UI configuration for Android (edge-to-edge status/navigation bar settings). - Initializes privacy/ads (CMP + ATT + MobileAds) via initPrivacyAndAds(). - Registers Firebase messaging background handler. - Prepares WebViewService and initializes AppNavigation for hybrid routing. - Checks and sends affiliate install information. - Initializes ThemeService for dynamic theme switching. - Finally calls runApp to launch the Flutter UI.

Firebase Cloud Messaging background handler used when messages arrive while the app is terminated or in background. Summary: - Ensures Firebase is initialized in the background isolate and logs the incoming message id.

Initialize privacy and ads using CMP (Consent Management Platform) and iOS ATT flow. Summary: - Initializes Google Mobile Ads SDK and handles user consent flow via UMP (User Messaging Platform). - Requests ATT permission on iOS using AppTrackingTransparency. - Ensures MobileAds is initialized after consent state is resolved.

Request consent information update and show the consent form if required by UMP/ConsentInformation. Summary: - Calls ConsentInformation.instance.requestConsentInfoUpdate with the provided params. - If a consent form is available, tries to load and display it using ConsentForm.loadAndShowConsentFormIfRequired. - Completes when the UMP flow is finished or on timeout.

Request Apple App Tracking Transparency (ATT) permission on iOS. Summary: - Uses AppTrackingTransparency.requestTrackingAuthorization to ask for user consent to track across apps/websites for advertising.

Initialize Google Mobile Ads after user consent state is known. Summary: - Checks UMP's canRequestAds state and initializes MobileAds.instance if advertising is permitted. - If canRequestAds is false, attempts a fallback initialization for testing or degraded flows.

Creates an [AppLayoutBase].

Builds the responsive banner area with optional background image, gradient overlay, and centered title/subtitle.

Creates a CompactLayout with a banner (image/gradient/title) and a scrollable content section.

Get current route path from ModalRoute

Creates a StructuredLayout preconfigured with tighter banner and larger content area to accommodate forms and multi-field content.

Get current route path from ModalRoute

Creates a ContentLayout optimized for long-form content with generous padding.

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Desktop layout: 3-column side-by-side with chart dominating Adjusts flex ratios based on screen width for better tablet experience

Mobile layout: Full chart with PageView

Creates a CompactLayout with a banner (image/gradient/title) and a scrollable content section.

Get current route path from ModalRoute

Creates a StructuredLayout preconfigured with tighter banner and larger content area to accommodate forms and multi-field content.

Get current route path from ModalRoute

Creates a ContentLayout optimized for long-form content with generous padding.

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Desktop layout: 3-column side-by-side with chart dominating Adjusts flex ratios based on screen width for better tablet experience

Mobile layout: Full chart with PageView

Creates a CompactLayout with a banner (image/gradient/title) and a scrollable content section.

Get current route path from ModalRoute

Creates a StructuredLayout preconfigured with tighter banner and larger content area to accommodate forms and multi-field content.

Get current route path from ModalRoute

Creates a ContentLayout optimized for long-form content with generous padding.

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Desktop layout: 3-column side-by-side with chart dominating Adjusts flex ratios based on screen width for better tablet experience

Mobile layout: Full chart with PageView

Creates a CompactLayout with a banner (image/gradient/title) and a scrollable content section.

Get current route path from ModalRoute

Creates a StructuredLayout preconfigured with tighter banner and larger content area to accommodate forms and multi-field content.

Get current route path from ModalRoute

Creates a ContentLayout optimized for long-form content with generous padding.

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Desktop layout: 3-column side-by-side with chart dominating Adjusts flex ratios based on screen width for better tablet experience

Mobile layout: Full chart with PageView

Creates a CompactLayout with a banner (image/gradient/title) and a scrollable content section.

Get current route path from ModalRoute

Creates a StructuredLayout preconfigured with tighter banner and larger content area to accommodate forms and multi-field content.

Get current route path from ModalRoute

Creates a ContentLayout optimized for long-form content with generous padding.

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Desktop layout: 3-column side-by-side with chart dominating Adjusts flex ratios based on screen width for better tablet experience

Mobile layout: Full chart with PageView

Creates a CompactLayout with a banner (image/gradient/title) and a scrollable content section.

Get current route path from ModalRoute

Creates a StructuredLayout preconfigured with tighter banner and larger content area to accommodate forms and multi-field content.

Get current route path from ModalRoute

Creates a ContentLayout optimized for long-form content with generous padding.

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Desktop layout: 3-column side-by-side with chart dominating Adjusts flex ratios based on screen width for better tablet experience

Mobile layout: Full chart with PageView

Creates a CompactLayout with a banner (image/gradient/title) and a scrollable content section.

Get current route path from ModalRoute

Creates a StructuredLayout preconfigured with tighter banner and larger content area to accommodate forms and multi-field content.

Get current route path from ModalRoute

Creates a ContentLayout optimized for long-form content with generous padding.

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Get current route path from ModalRoute

Desktop layout: 3-column side-by-side with chart dominating Adjusts flex ratios based on screen width for better tablet experience

Mobile layout: Full chart with PageView

Build the card UI Size is the calculated card size for the grid

Build the card UI Size is the calculated card size for the grid

Build the card UI Size is the calculated card size for the grid

Build the card UI Size is the calculated card size for the grid

Build the card UI Size is the calculated card size for the grid

Build the card UI Size is the calculated card size for the grid

Uncomment below to test MembershipWidget with mock subscription data

Initializes form values from query parameters if in edit mode.

Shows confirmation dialog with Big Three calculation

Saves the user via UserFormController

✅ Navigate to component screen - just pass the item directly

Handle ephemeris cell tap - navigate to planet in sign interpretation

Parse chart type from query parameter

Tap zone that controls page navigation

Sends a password reset email for the entered address, validating input and showing user feedback.

Sends a password reset email for the entered address, validating input and showing user feedback.

Navigate to component screen - just pass the item directly

Handles the login flow: validates inputs, calls the login service, shows feedback, and navigates on success.

Builds the custom tab switcher widget using theme styling

Builds the sign-in form using theme styling

Builds the register form using theme styling

Handles the login flow: validates inputs, calls the login service, shows feedback, and navigates on success.

Builds the custom tab switcher widget using theme styling

Builds the sign-in form using theme styling

Builds the register form using theme styling

Build content for each tab

Generate AI report for a subcategory Called when user taps the report button (⭐) in a subcategory header. Takes ~10 seconds due to AI generation.

Show generated report in draggable bottom sheet modal Provides a clean, full-screen reading experience with: - Draggable sheet (can expand/collapse) - Scrollable content - Selectable text (users can copy insights) - Close button

Build content for each tab

Generate AI report for a subcategory Called when user taps the report button (⭐) in a subcategory header. Takes ~10 seconds due to AI generation.

Show generated report in draggable bottom sheet modal Provides a clean, full-screen reading experience with: - Draggable sheet (can expand/collapse) - Scrollable content - Selectable text (users can copy insights) - Close button

Navigate to component screen

Loads users from the service.

Sorts users: main user first, then alphabetically by name

Set a user as the main user ENSURES: Exactly one main user by updating both local and backend

Delete a user profile ENSURES: Main user can NEVER be deleted

Initialize with query parameters if provided

Initialize with query parameters if provided

Initialize with query parameters if provided

Get price period string based on product ID