Hypnoelp

This is a documentation of the app that explains its features, functionality, and development guide

Version 4 • Last Updated: September 9, 2025

Use this tab to jump to specific sections

📋 Overview

This is an innovative app that offers users different courses, each containing audio sessions and workbooks that users can utilize to transform their mindset. The app features an AI voice companion that provides personalized guidance and support. Users can also create custom courses tailored to their private and personal needs. This application leverages the power of AI to positively change and influence the mind through structured courses.

🎵

Dynamic Audio Mixing

Real-time audio compilation with personalized voice and background music for each course

📚

Multiple Courses

Available courses for confidence, habits, wellness, productivity and more that users can purchase, plus ability to create custom courses

🎤

AI Voice Integration

Interactive AI-powered companion that helps users create personalized courses and provides intelligent guidance

📖

Interactive Workbooks

Digital workbooks with exercises, journals, and action plans that complement each course's audio content

👤 User Experience

App Navigation Flow

The app features a clean, intuitive bottom navigation bar with five main tabs:

1. Player Tab (Main Screen)

The heart of the app where users experience their courses:

  • Audio Playback: Professional audio player with play/pause, progress tracking, and volume controls
  • Audio Customization: Choose voice gender, background music, session length, and emergence time
  • Segment Display: Visual representation of session segments (Induction → Deepening → Main Content → Emergence)
  • Workbook Access: Quick access to course workbooks and journals

2. AI Voice Tab

An innovative feature for personalized AI-guided sessions:

  • AI Companion: Interact with an AI chatbot that serves as your personal companion for guidance and support
  • AI Processing: Advanced AI analyzes your input and generates personalized responses
  • Progress Awareness: The AI chatbot tracks user progress by monitoring audio playback time and reading journal responses to provide contextual guidance
  • Visual Feedback: The interface shows visual feedback with animated elements during AI chatbot processing and interactions
  • Usage Tracking: Monitor AI usage minutes based on your subscription plan (time varies by subscription level)

3. Courses Tab (Shop)

Browse and manage your hypnotherapy course library:

  • Course Catalog: Browse courses with icons and detailed descriptions
  • Smart Filtering: Filter by category (Confidence, Habits, Self-care, etc.) or search by keyword
  • Ownership Status: Clear indicators for owned vs. available courses
  • Expandable Cards: Tap courses to reveal detailed descriptions and action buttons
  • Quick Actions: Buy new courses or redownload owned content
  • Course Details: Access comprehensive course benefits and curriculum

4. Help Tab

Comprehensive support and guidance:

  • How to Use: Step-by-step guide for new users
  • FAQs: Answers to common questions about hypnotherapy and the app
  • Get Support: Contact options and troubleshooting guides
  • Disclaimer: Important health and safety information
  • About: Learn about the app's mission and development team

5. General Settings Tab

Configure course and audio preferences:

  • Course Selection: Choose from your owned courses as the current active course
  • Voice Selection: Pick between available voices (Male/Female) for the current course
  • Background Music: Select background music or choose "None" for silence
  • Session Length: Choose between "Long" or "Short" session duration
  • Audio Segments: Customize Induction, Deepening, and Emergence techniques
  • Account Information: View account details and subscription status

First-Time User

  1. Authentication: Sign up with email
  2. Email Verification: Confirm email to activate account
  3. Free Course: Automatic access to one free course (Confidence Building)

✨ Key Features

Audio System

The app's core innovation is its dynamic audio compilation system:

Example Content Library

🎯 Confidence (C14ENB)

Overcome anxiety and build unshakeable self-confidence

  • 5 audio sessions
  • 4 interactive workbooks
  • Daily confidence journal
  • FREE - Included with app

🚭 Quit Smoking (H23ENB)

3-week program to break free from nicotine addiction

  • 6 audio sessions
  • 6 guided workbooks
  • Daily tracking journal
  • Premium course (requires purchase or subscription)

⚡ Productivity (P11ENM)

Master time management and achieve peak performance

  • 3 lecture sessions
  • Focus enhancement techniques
  • Premium course (requires purchase or subscription)

⚖️ Weight Loss (S66ENB)

Transform your relationship with food and body image

  • 4 audio sessions
  • 2 action plan workbooks
  • Food and mood journal
  • Premium course (requires purchase or subscription)

Personalization Features

Offline Capabilities

The app is designed to work offline:

🏗️ Technical Architecture

Technology Stack

Architecture Pattern

lib/
├── screens/          # UI screens and navigation
├── providers/        # State management (Provider pattern)
├── services/         # Business logic and external APIs
├── models/          # Data models
├── utils/           # Shared utilities
├── widgets/         # Reusable UI components
└── constants/       # Theme and configuration

Data Flow

  1. App Launch: SplashScreen → Copy assets → Initialize services
  2. Authentication: Check local profile → Validate with Supabase → Load user data
  3. Content Loading: Read JSON configs → Load course data → Cache audio files
  4. Audio Playback: Compile segments → Mix with background → Stream to player
  5. State Updates: User actions → Provider updates → UI rebuilds

⚙️ Core Services

🔐 SupabaseService

Handles authentication, user management, and cloud database operations. Manages email verification, password resets, and Google OAuth.

🎵 SegmentCompilerService

Dynamically compiles courses by stitching together core segments with course content based on user preferences.

🎚️ AudioMixer

Advanced audio mixing engine that handles real-time voice and background music synchronization with cross-platform support.

🎼 BackgroundMusicService

Manages background ambient sounds, handles looping, caching, and volume control for seamless audio experiences.

📝 WorkbookService

Loads and manages HTML workbook content, handles user responses, and provides offline access to course materials.

⚙️ GeneralSettingsService

Central configuration service that manages user preferences, course settings, and app-wide configurations.

🛍️ ShopService

Handles course catalog, pricing, and purchase workflows. Manages course metadata and download status.

❓ HelpContentService

Provides access to FAQ content, user guides, and support documentation stored as HTML resources.

💾 Data Management

Local Storage Structure

AppData/
├── Audio/
│   ├── core/A00/        # Core segments (induction, deepening, emergence)
│   ├── background/B00/  # Background music files
│   └── [Category]/[CourseCode]/  # Course-specific audio
├── Htmls/
│   ├── WorkBooks/       # Interactive course workbooks
│   ├── Shop/           # Course benefit descriptions
│   └── FAQs/           # Help documentation
├── JSONs/
│   ├── User_Owned_Courses/    # Individual course configurations
│   ├── User_Audio_Usage/      # Play count tracking
│   ├── core_segments.json     # Core audio segment definitions
│   ├── user_profile.json      # User settings and preferences
│   ├── shop.json              # Course catalog
│   └── background.json        # Background music options
└── Icons/               # Course and FAQ icons

User Data Privacy

📋 AppData Documentation

This section defines the complete schema for the Hypnoelp app, including file naming conventions, directory structures, and JSON data formats. The app uses a modular approach where core audio segments are stitched together with course-specific content.

The app is designed to work offline and independently. Most features function without requiring server connections (except for AI chat, user authentication, and purchasing courses). All app data and settings are managed through JSON configuration files located in the AppData/JSONs/ folder.

Course Categories

The app organizes content into 8 main categories, each identified by a single letter code:

💪

C - Confidence

Build self-worth & assertiveness, public speaking mastery, social confidence

⚡

P - Productivity

Boost focus, goals, efficiency, procrastination-busting, time management

💰

W - Wealth

Master money mindset & prosperity, abundance visualization, financial freedom

🔄

H - Habits

Break addictions, craft routines, quit smoking, digital detox

🧘

E - Emotions

Manage stress, heal feelings, anxiety control, anger management

🌱

M - Mindfulness

Cultivate presence & deep calm, meditation, gratitude practice

🌟

S - Self-care

Improve sleep, weight, vitality, insomnia relief, energy boosting

❤️

R - Relationships

Enhance communication & connection, romantic enrichment, family harmony

JSON Files

🔧 core_segments.json

Contains the core audio files that are stitched together with course content. These files use the special code A00EN for English core segments.

{
    "files": {
        "10": {
            "name": "warning",
            "segment_number": 10,
            "audiofiles": {
                "1": {
                    "title": "Warning",
                    "F": {
                        "audiofile_id": "A00ENF101",
                        "duration_seconds": 306,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/F/A00ENF101_13809ef1f684d9db60a326f193cc0bcd.mp3",
                        "file_path": "AppData/Audio/core/A00EN/F/A00ENF101_13809ef1f684d9db60a326f193cc0bcd.mp3",
                        "checksum": "13809ef1f684d9db60a326f193cc0bcd",
                        "file_size_kb": 3123
                    },
                    "M": {
                        "audiofile_id": "A00ENM101",
                        "duration_seconds": 224,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/M/A00ENM101_cc122d54426b13d903bf3cbce520f441.mp3",
                        "file_path": "AppData/Audio/core/A00EN/M/A00ENM101_cc122d54426b13d903bf3cbce520f441.mp3",
                        "checksum": "cc122d54426b13d903bf3cbce520f441",
                        "file_size_kb": 2305
                    }
                }
            }
        },
        "20": {
            "name": "induction",
            "segment_number": 20,
            "audiofiles": {
                "1": {
                    "title": "Countdown",
                    "F": {
                        "audiofile_id": "A00ENF201",
                        "duration_seconds": 306,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/F/A00ENF201_13809ef1f684d9db60a326f193cc0bcd.mp3",
                        "file_path": "AppData/Audio/core/A00EN/F/A00ENF201_13809ef1f684d9db60a326f193cc0bcd.mp3",
                        "checksum": "13809ef1f684d9db60a326f193cc0bcd",
                        "file_size_kb": 3123
                    },
                    "M": {
                        "audiofile_id": "A00ENM201",
                        "duration_seconds": 224,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/M/A00ENM201_cc122d54426b13d903bf3cbce520f441.mp3",
                        "file_path": "AppData/Audio/core/A00EN/M/A00ENM201_cc122d54426b13d903bf3cbce520f441.mp3",
                        "checksum": "cc122d54426b13d903bf3cbce520f441",
                        "file_size_kb": 2305
                    }
                },
                "2": {
                    "title": "Eyefixation",
                    "F": {
                        "audiofile_id": "A00ENF202",
                        "duration_seconds": 288,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/F/A00ENF202_41a4e590e0bbb86afb4c6f9eceafa548.mp3",
                        "file_path": "AppData/Audio/core/A00/F/2_A00F20_3a7b1d64bc92e10f7f4da91e27f43b82.mp3",
                        "checksum": "md5:3a7b1d64bc92e10f7f4da91e27f43b82",
                        "file_size_kb": 670
                    }
                },
                "3": {
                    "title": "Eyefixation",
                    "F": {
                        "audiofile_id": "A00ENF203",
                        "duration_seconds": 288,
                        "download_url": "https://hypnoelp.com/audio/core/A00/F/3_A00F20_59f0ce83d1ad542e1b28f3d9c45e6b7f.mp3",
                        "file_path": "AppData/Audio/core/A00/F/3_A00F20_59f0ce83d1ad542e1b28f3d9c45e6b7f.mp3",
                        "checksum": "md5:59f0ce83d1ad542e1b28f3d9c45e6b7f",
                        "file_size_kb": 560
                    }
                }
            }
        },
        "40": {
            "name": "deepening",
            "segment_number": 40,
            "audiofiles": {
                "1": {
                    "title": "Elevator",
                    "F": {
                        "audiofile_id": "A00ENF401",
                        "duration_seconds": 253,
                        "download_url": "https://hypnoelp.com/audio/core/A00/F/1_A00F30_af13b8c772b3c91e5a27f7b83e65d12c.mp3",
                        "file_path": "AppData/Audio/core/A00/F/1_A00F30_af13b8c772b3c91e5a27f7b83e65d12c.mp3",
                        "checksum": "md5:af13b8c772b3c91e5a27f7b83e65d12c",
                        "file_size_kb": 750
                    }
                },
                "2": {
                    "title": "Fraction",
                    "F": {
                        "audiofile_id": "A00ENF402",
                        "duration_seconds": 245,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/F/A00ENF402_53ef1dccd2a14db8b62e759c2da2796f.mp3",
                        "file_path": "AppData/Audio/core/A00EN/F/A00ENF402_53ef1dccd2a14db8b62e759c2da2796f.mp3",
                        "checksum": "md5:e25b34d9f3e71829a4b53c7f92ad816b",
                        "file_size_kb": 560
                    }
                },
                "3": {
                    "title": "Visual",
                    "F": {
                        "audiofile_id": "A00ENF403",
                        "duration_seconds": 332,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/F/A00ENF403_d8820149ec9a659548e41d053bd82908.mp3",
                        "file_path": "AppData/Audio/core/A00EN/F/A00ENF403_d8820149ec9a659548e41d053bd82908.mp3",
                        "checksum": "md5:7f41c6b841e27c53a19d8e7b24c98f56",
                        "file_size_kb": 560
                    }
                }
            }
        },
        "80": {
            "name": "emerge",
            "segment_number": 80,
            "audiofiles": {
                "1": {
                    "title": "Daytime",
                    "F": {
                        "audiofile_id": "A00ENF801",
                        "duration_seconds": 223,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/F/A00ENF801_8e062225ff31fa60dcb67812e35090f1.mp3",
                        "file_path": "AppData/Audio/core/A00EN/F/A00ENF801_8e062225ff31fa60dcb67812e35090f1.mp3",
                        "checksum": "md5:b5b2v5d4e599",
                        "file_size_kb": 560
                    }
                },
                "2": {
                    "title": "Anytime",
                    "F": {
                        "audiofile_id": "A00ENF802",
                        "duration_seconds": 178,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/F/A00ENF802_5a547c3e5136d32bac31aea4605e249a.mp3",
                        "file_path": "AppData/Audio/core/A00EN/F/A00ENF802_5a547c3e5136d32bac31aea4605e249a.mp3",
                        "checksum": "md5:a1b2c3d4e5f6",
                        "file_size_kb": 750
                    }
                },
                "3": {
                    "title": "Nighttime",
                    "F": {
                        "audiofile_id": "A00ENF803",
                        "duration_seconds": 251,
                        "download_url": "https://hypnoelp.com/audio/core/A00EN/F/A00ENF803_6f6e174098c8946e75f2b59f5b42b640.mp3",
                        "file_path": "AppData/Audio/core/A00EN/F/A00ENF803_6f6e174098c8946e75f2b59f5b42b640.mp3",
                        "checksum": "md5:b5b285d4e599",
                        "file_size_kb": 980
                    }
                }
            }
        }
    }
}

📚 Course JSON Files (e.g., C14ENB.json)

Individual course configuration files containing all course-specific content and metadata. Stored in User_Owned_Courses/ folder.

{
    "course_code": "C14ENB",
    "title": "Confidence",
    "short_description": "Dealing with Anxiety",
    "icon": {
        "download_url": "https://hypnoelp.com/icons/Courses/C14ENB_7c3bfbfd436718553d1884a18b267bc5.png",
        "file_path": "AppData/Icons/Courses/C14ENB_7c3bfbfd436718553d1884a18b267bc5.png",
        "checksum": "7c3bfbfd436718553d1884a18b267bc5",
        "file_size_kb": 1684
    },
    "course_path": "AppData/Audio/C/C14EN",
    "is_free_course": true,
    "voice": "B",
    "audio_files": {
        "1": {
            "title": "How to Use These Confidence Building Sessions",
            "play_segments": "50",
            "F": {
                "audiofile_id": "C14ENF501",
                "duration_seconds": 559,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/F/C14ENF501_051b1febbe1e2d3e01eb31f04a29482b.mp3",
                "file_path": "AppData/Audio/C/C14EN/F/C14ENF501_051b1febbe1e2d3e01eb31f04a29482b.mp3",
                "checksum": "051b1febbe1e2d3e01eb31f04a29482b",
                "file_size_kb": 8742
            },
            "M": {
                "audiofile_id": "C14ENM501",
                "duration_seconds": 558,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/M/C14ENM501_d52bfa2a284fef2e7999b1e931f70b3f.mp3",
                "file_path": "AppData/Audio/C/C14EN/M/C14ENM501_d52bfa2a284fef2e7999b1e931f70b3f.mp3",
                "checksum": "d52bfa2a284fef2e7999b1e931f70b3f",
                "file_size_kb": 8725
            }
        },
        "2": {
            "title": "Release Social Anxiety and Build Inner Strength",
            "play_segments": "10,20,40,50,80",
            "F": {
                "audiofile_id": "C14ENF502",
                "duration_seconds": 445,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/F/C14ENF502_8bd9e1c3b992027b50d6a8f1268c2bd6.mp3",
                "file_path": "AppData/Audio/C/C14EN/F/C14ENF502_8bd9e1c3b992027b50d6a8f1268c2bd6.mp3",
                "checksum": "8bd9e1c3b992027b50d6a8f1268c2bd6",
                "file_size_kb": 6966
            },
            "M": {
                "audiofile_id": "C14ENM502",
                "duration_seconds": 415,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/M/C14ENM502_853dbfc07d1c64e43ee7ff5c0232f63e.mp3",
                "file_path": "AppData/Audio/C/C14EN/M/C14ENM502_853dbfc07d1c64e43ee7ff5c0232f63e.mp3",
                "checksum": "853dbfc07d1c64e43ee7ff5c0232f63e",
                "file_size_kb": 6498
            }
        },
        "3": {
            "title": "Overcome Fear and Embrace Your True Self",
            "play_segments": "10,20,40,50,80",
            "F": {
                "audiofile_id": "C14ENF503",
                "duration_seconds": 540,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/F/C14ENF503_344e3c73ed541c253174a0994fc68ded.mp3",
                "file_path": "AppData/Audio/C/C14EN/F/C14ENF503_344e3c73ed541c253174a0994fc68ded.mp3",
                "checksum": "344e3c73ed541c253174a0994fc68ded",
                "file_size_kb": 8449
            },
            "M": {
                "audiofile_id": "C14ENM503",
                "duration_seconds": 477,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/M/C14ENM503_29234d348acaf59ecab15b2dba67f1ed.mp3",
                "file_path": "AppData/Audio/C/C14EN/M/C14ENM503_29234d348acaf59ecab15b2dba67f1ed.mp3",
                "checksum": "29234d348acaf59ecab15b2dba67f1ed",
                "file_size_kb": 7466
            }
        },
        "4": {
            "title": "Confident Communication and Assertiveness",
            "play_segments": "10,20,40,50,80",
            "F": {
                "audiofile_id": "C14ENF504",
                "duration_seconds": 450,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/F/C14ENF504_f6fe9d878898452c245d7b7da337ee8e.mp3",
                "file_path": "AppData/Audio/C/C14EN/F/C14ENF504_f6fe9d878898452c245d7b7da337ee8e.mp3",
                "checksum": "f6fe9d878898452c245d7b7da337ee8e",
                "file_size_kb": 7036
            },
            "M": {
                "audiofile_id": "C14ENM504",
                "duration_seconds": 422,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/M/C14ENM504_3652113f43262302075bf6c7d17000b7.mp3",
                "file_path": "AppData/Audio/C/C14EN/M/C14ENM504_3652113f43262302075bf6c7d17000b7.mp3",
                "checksum": "3652113f43262302075bf6c7d17000b7",
                "file_size_kb": 6596
            }
        },
        "5": {
            "title": "Maintain Unshakeable Confidence Daily",
            "play_segments": "10,20,40,50,80",
            "F": {
                "audiofile_id": "C14ENF505",
                "duration_seconds": 553,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/F/C14ENF505_f8c2097530f0b8a998c2c4b84c689702.mp3",
                "file_path": "AppData/Audio/C/C14EN/F/C14ENF505_f8c2097530f0b8a998c2c4b84c689702.mp3",
                "checksum": "f8c2097530f0b8a998c2c4b84c689702",
                "file_size_kb": 8647
            },
            "M": {
                "audiofile_id": "C14ENM505",
                "duration_seconds": 526,
                "download_url": "https://hypnoelp.com/audio/C/C14EN/M/C14ENM505_16a8bd418db3c7618db8afbb2af6a7e3.mp3",
                "file_path": "AppData/Audio/C/C14EN/M/C14ENM505_16a8bd418db3c7618db8afbb2af6a7e3.mp3",
                "checksum": "16a8bd418db3c7618db8afbb2af6a7e3",
                "file_size_kb": 8225
            }
        }
    },
    "workbooks": {
        "1": {
            "workbook_id": "C14ENB1",
            "title": "Daily Confidence Journal",
            "description": "Track your daily confidence wins, practice gratitude, and reinforce positive self-talk patterns",
            "download_url": "https://hypnoelp.com/htmls/WorkBooks/C/C14EN/C14ENB1_daedcfd5674150f0c7eaced9be95bbaa.html",
            "file_path": "AppData/Htmls/WorkBooks/C/C14EN/C14ENB1_daedcfd5674150f0c7eaced9be95bbaa.html",
            "checksum": "daedcfd5674150f0c7eaced9be95bbaa",
            "file_size_kb": 14
        },
        "2": {
            "workbook_id": "C14ENB2",
            "title": "Introduction to Confidence Building",
            "description": "Understanding anxiety patterns, setting confidence goals, and preparing your mindset for transformation",
            "download_url": "https://hypnoelp.com/htmls/WorkBooks/C/C14EN/C14ENB2_d74706ae437df9f7e595da49e7c5d1e8.html",
            "file_path": "AppData/Htmls/WorkBooks/C/C14EN/C14ENB2_d74706ae437df9f7e595da49e7c5d1e8.html",
            "checksum": "d74706ae437df9f7e595da49e7c5d1e8",
            "file_size_kb": 14
        },
        "3": {
            "workbook_id": "C14ENB3",
            "title": "Week 1: Identifying Your Anxiety Triggers",
            "description": "Recognize patterns of anxiety, map your triggers, and begin building awareness of confident moments",
            "download_url": "https://hypnoelp.com/htmls/WorkBooks/C/C14EN/C14ENB3_6d08a74e9b12a1e46eb697ce043ce756.html",
            "file_path": "AppData/Htmls/WorkBooks/C/C14EN/C14ENB3_6d08a74e9b12a1e46eb697ce043ce756.html",
            "checksum": "6d08a74e9b12a1e46eb697ce043ce756",
            "file_size_kb": 14
        },
        "4": {
            "workbook_id": "C14ENB4",
            "title": "Action Plan for Challenging Situations",
            "description": "Create personalized strategies for facing fears, practice scenarios, and build your confidence toolkit",
            "download_url": "https://hypnoelp.com/htmls/WorkBooks/C/C14EN/C14ENB4_dcec9b938bb9e9689ef2c2f3ec16f5bc.html",
            "file_path": "AppData/Htmls/WorkBooks/C/C14EN/C14ENB4_dcec9b938bb9e9689ef2c2f3ec16f5bc.html",
            "checksum": "dcec9b938bb9e9689ef2c2f3ec16f5bc",
            "file_size_kb": 14
        }
    }
}

👤 user_profile.json

User-specific settings, preferences, and owned content.

{
    "user_id": "user_test_0090",
    "first_name": "User",
    "last_name": "",
    "user_email": "user_test@example.com",
    "subscription": {
        "expires_at": "250726",
        "type": "free",
        "name": "Free Trial Plan",
        "subscription_id": "sub_id_0090"
    },
    "ai_usage": {
        "limit_minutes": 30,
        "used_minutes": 10,
        "reset_period_days": 7
    },
    "current_selected_course": "C14ENB",
    "last_played_audio_id": "C14ENF501",
    "app_version": "1.0.0",
    "free_course_code": ["C14ENB"],
    "purchased_courses": ["H23ENB", "S66ENB", "P11ENM"],
    "warning_enabled": true,
    "course_preferences": {
        "H23B": {
            "voice": "Female",
            "background": "None",
            "length": "Long",
            "induction": "Randomize",
            "deepening": "Randomize",
            "emerge": "Anytime"
        },
        "C14B": {
            "voice": "Female",
            "background": "None",
            "length": "Long",
            "induction": "Randomize",
            "deepening": "Randomize",
            "emerge": "Anytime"
        }
    },
    "lateral_hand_position": "right"
}

🛍️ shop.json

Store catalog containing all available courses for purchase.

{
    "shop": {
        "categories": ["Confidence", "Productivity", "Wealth", "Habits", "Emotions", "Mindfulness", "Self-care", "Relationships"],
        "courses": {
            "1": {
                "course_code": "H23EN",
                "voices_available": ["M", "F"],
                "category": "H",
                "category_name": "Habits",
                "title": "Quit Smoking",
                "short_description": "Learn to manage stress and quit smoking using effective hypnotherapy methods",
                "icon": {
                    "download_url": "https://hypnoelp.com/icons/Courses/H23ENS_d0652ddd5601724735fbb3c651727d9a.png",
                    "file_path": "AppData/Icons/Shop/H23ENS_d0652ddd5601724735fbb3c651727d9a.png",
                    "checksum": "d0652ddd5601724735fbb3c651727d9a",
                    "file_size_kb": 1713
                },
                "html": {
                    "download_url": "https://hypnoelp.com/htmls/Shop/H23ENS_baeca65a06fd17be2814c5affb0c0884.html",
                    "file_path": "AppData/Htmls/Shop/H23ENS_baeca65a06fd17be2814c5affb0c0884.html",
                    "checksum": "baeca65a06fd17be2814c5affb0c0884",
                    "file_size_kb": 31
                },
                "price": 29,
                "product_id": "prod_1234567890",
                "audio_count": 6,
                "workbook_count": 2,
                "is_new": true
            },
            "2": {
                "course_code": "C14EN",
                "voices_available": ["M", "F"],
                "category": "C",
                "category_name": "Confidence",
                "title": "Confidence",
                "short_description": "Dealing with Anxiety",
                "icon": {
                    "download_url": "https://hypnoelp.com/icons/Courses/C14ENS_7c3bfbfd436718553d1884a18b267bc5.png",
                    "file_path": "AppData/Icons/Shop/C14ENS_7c3bfbfd436718553d1884a18b267bc5.png",
                    "checksum": "7c3bfbfd436718553d1884a18b267bc5",
                    "file_size_kb": 1684
                },
                "html": {
                    "download_url": "https://hypnoelp.com/htmls/Shop/C14ENS_baeca65a06fd17be2814c5affb0c0884.html",
                    "file_path": "AppData/Htmls/Shop/C14ENS_baeca65a06fd17be2814c5affb0c0884.html",
                    "checksum": "baeca65a06fd17be2814c5affb0c0884",
                    "file_size_kb": 31
                },
                "price": 19,
                "product_id": "prod_1234567890",
                "audio_count": 5,
                "workbook_count": 4,
                "is_new": false
            }
        }
    }
}

🎵 background.json

Available background sounds for the audio player.

{
    "backgrounds": {
        "1": {
            "resource_id": "B001",
            "name": "Rain",
            "duration_seconds": 30,
            "download_url": "https://hypnoelp.com/audio/background/B00/B001_aaae3a218c1e01f1beffe3f89273856b.mp3",
            "file_path": "AppData/Audio/background/B00/B001_aaae3a218c1e01f1beffe3f89273856b.mp3",
            "checksum": "aaae3a218c1e01f1beffe3f89273856b",
            "file_size_kb": 597
        },
        "2": {
            "resource_id": "B002",
            "name": "Theta Waves",
            "duration_seconds": 30,
            "download_url": "https://hypnoelp.com/audio/background/B00/B002_3a482a66d9775c5daca1e45dcda0823b.mp3",
            "file_path": "AppData/Audio/background/B00/B002_3a482a66d9775c5daca1e45dcda0823b.mp3",
            "checksum": "3a482a66d9775c5daca1e45dcda0823b",
            "file_size_kb": 704
        },
        "3": {
            "resource_id": "B003",
            "name": "Tibetan Monks",
            "duration_seconds": 30,
            "download_url": "https://hypnoelp.com/audio/background/B00/B003_42248b9f5ed69a634cb4f417873cf359.mp3",
            "file_path": "AppData/Audio/background/B00/B003_42248b9f5ed69a634cb4f417873cf359.mp3",
            "checksum": "42248b9f5ed69a634cb4f417873cf359",
            "file_size_kb": 704
        }
    }
}

❓ FAQs.json

Help content and documentation resources.

{
    "resources": {
        "1": {
            "resource_id": "FAQEN1",
            "title": "How To Use This App",
            "description": "Learn how to use this app to get the most out of your hypnosis courses",
            "icon": {
                "download_url": "https://hypnoelp.com/icons/FAQs/FAQEN1_9f39dad73f2df6e9415e71abc4bd1a80.png",
                "file_path": "AppData/Icons/FAQs/FAQEN1_9f39dad73f2df6e9415e71abc4bd1a80.png",
                "checksum": "9f39dad73f2df6e9415e71abc4bd1a80",
                "file_size_kb": 1182
            },
            "html": {
                "download_url": "https://hypnoelp.com/htmls/FAQs/FAQEN1_e8178c0fef222d92b91aa687fabf3be1.html",
                "file_path": "AppData/Htmls/FAQs/FAQEN1_e8178c0fef222d92b91aa687fabf3be1.html",
                "checksum": "e8178c0fef222d92b91aa687fabf3be1",
                "file_size_kb": 27
            }
        },
        "2": {
            "resource_id": "FAQEN2",
            "title": "FAQs",
            "description": "Frequently Asked Questions about this app",
            "icon": {
                "download_url": "https://hypnoelp.com/icons/FAQs/FAQEN2_f0d62baea56d1ef8a4eae98f3ef6d4d3.png",
                "file_path": "AppData/Icons/FAQs/FAQEN2_f0d62baea56d1ef8a4eae98f3ef6d4d3.png",
                "checksum": "f0d62baea56d1ef8a4eae98f3ef6d4d3",
                "file_size_kb": 1200
            },
            "html": {
                "download_url": "https://hypnoelp.com/htmls/FAQs/FAQEN2_e8178c0fef222d92b91aa687fabf3be1.html",
                "file_path": "AppData/Htmls/FAQs/FAQEN2_e8178c0fef222d92b91aa687fabf3be1.html",
                "checksum": "e8178c0fef222d92b91aa687fabf3be1",
                "file_size_kb": 27
            }
        },
        "3": {
            "resource_id": "FAQEN3",
            "title": "Get Support",
            "description": "Get support and assistance.",
            "icon": {
                "download_url": "https://hypnoelp.com/icons/FAQs/FAQEN3_af9d1a0bc5d5638bf278df45e91916fb.png",
                "file_path": "AppData/Icons/FAQs/FAQEN3_af9d1a0bc5d5638bf278df45e91916fb.png",
                "checksum": "af9d1a0bc5d5638bf278df45e91916fb",
                "file_size_kb": 1177
            },
            "html": {
                "download_url": "https://hypnoelp.com/htmls/FAQs/FAQEN3_e8178c0fef222d92b91aa687fabf3be1.html",
                "file_path": "AppData/Htmls/FAQs/FAQEN3_e8178c0fef222d92b91aa687fabf3be1.html",
                "checksum": "e8178c0fef222d92b91aa687fabf3be1",
                "file_size_kb": 27
            }
        }
    }
}

📢 ads.json

Advertisement and promotional content configuration.

{
    "ads": {
        "1": {
            "id": "ADEN1",
            "title": "Quit Smoking",
            "type": "course",
            "priority": 1,
            "download_url": "https://hypnoelp.com/htmls/Ads/ADEN1_44164cd50cfe10a3cfeca2296a0a4500.html",
            "file_path": "AppData/Htmls/Ads/ADEN1_44164cd50cfe10a3cfeca2296a0a4500.html",
            "checksum": "44164cd50cfe10a3cfeca2296a0a4500",
            "file_size_kb": 7,
            "audience": {
                "tier": ["free", "monthly", "quarterly", "yearly"],
                "has_course": ["C14B"]
            },
            "start": "250820",
            "end": "251220",
            "max_views": 5,
            "min_hours_between_views": 3,
            "rotation_group": "holiday_promos",
            "close_button_delay_ms": 3000
        },
        "2": {
            "id": "ADEN2",
            "title": "Creating A Wealth Mindset",
            "type": "course",
            "priority": 2,
            "download_url": "https://hypnoelp.com/htmls/Ads/ADEN2_3fe1762487063409194748cbc2efeda3.html",
            "file_path": "AppData/Htmls/Ads/ADEN2_3fe1762487063409194748cbc2efeda3.html",
            "checksum": "3fe1762487063409194748cbc2efeda3",
            "file_size_kb": 10,
            "audience": {
                "tier": ["free", "monthly", "quarterly", "yearly"],
                "has_course": ["any"]
            },
            "start": "250807",
            "end": "251220",
            "max_views": 10,
            "min_hours_between_views": 3,
            "rotation_group": "new_courses",
            "close_button_delay_ms": 3000
        }
        "2": {
            "id": "2_AD",
            "title": "Creating A Wealth Mindset",
            "type": "course",
            "priority": 2,
            "download_url": "https://hypnoelp.com/htmls/Ads/2_AD_af13b8c772b3c91e5a27f7b83e65d12c.html",
            "file_path": "AppData/Htmls/Ads/2_AD_af13b8c772b3c91e5a27f7b83e65d12c.html",
            "checksum": "...",
            "file_size_kb": 92,
            "audience": {
                "tier": ["free", "monthly", "quarterly", "yearly"],
                "has_course": ["any"]
            },
            "start": "250807",
            "end": "251220",
            "max_views": 10,
            "min_hours_between_views": 1,
            "rotation_group": "new_courses",
            "close_button_delay_ms": 5000
        },
        "3": {
            "id": "3_AD",
            "title": "Premium Features",
            "type": "promotion",
            "priority": 3,
            "download_url": "https://hypnoelp.com/htmls/Ads/3_AD_e25b34d9f3e71829a4b53c7f92ad816b.html",
            "file_path": "AppData/Htmls/Ads/3_AD_e25b34d9f3e71829a4b53c7f92ad816b.html",
            "checksum": "...",
            "file_size_kb": 78,
            "audience": {
                "tier": ["free"],
                "has_course": ["any"]
            },
            "start": "250901",
            "end": "251231",
            "max_views": 3,
            "min_hours_between_views": 24,
            "rotation_group": "premium_upgrade",
            "close_button_delay_ms": 3000
        }
    }
}

Audio Segment System

The app uses a modular audio system where sessions are constructed by combining segments:

⚠️

10 - Warning

Safety notification played at the beginning of sessions. Common to all courses and can be switched off globally in user settings.

🌙

20 - Induction

Guides the listener into a relaxed state. Selected from core_segments based on user preference.

⬇️

40 - Deepening

Deepens the hypnotic state. Selected from core_segments based on user preference.

🎯

50 - Main Content

Course-specific therapeutic content. Contains the actual course material and suggestions.

☀️

80 - Emergence

Brings listener back to normal awareness. Selected based on time preference (Daytime/Nighttime/Anytime).

⚠️ Implementation Notes

  • Audio Stitching: Core segments are stitched with course-specific content based on the play_segments field
  • Voice Consistency: Ensure the same voice (M/F) is used across all segments in a session
  • File Validation: Always validate checksums before playing audio files
  • Background Audio: Background sounds should loop seamlessly during playback
  • Offline Support: Core segments and free course content should be bundled with the app

📁 AppData Folder Structure

The AppData folder contains all app assets, configurations, and user data. This structure is mirrored both in the app bundle and local device storage.

Complete Directory Structure (Updated Format)

AppData/
├── Audio/
│   ├── C/                              # Confidence Category
│   │   └── C14EN/                      # Confidence Course (English)
│   │       ├── F/                      # Female Voice Files
│   │       │   ├── C14ENF501_051b1febbe1e2d3e01eb31f04a29482b.mp3
│   │       │   ├── C14ENF502_8bd9e1c3b992027b50d6a8f1268c2bd6.mp3
│   │       │   ├── C14ENF503_344e3c73ed541c253174a0994fc68ded.mp3
│   │       │   ├── C14ENF504_f6fe9d878898452c245d7b7da337ee8e.mp3
│   │       │   └── C14ENF505_f8c2097530f0b8a998c2c4b84c689702.mp3
│   │       └── M/                      # Male Voice Files
│   │           ├── C14ENM501_d52bfa2a284fef2e7999b1e931f70b3f.mp3
│   │           ├── C14ENM502_853dbfc07d1c64e43ee7ff5c0232f63e.mp3
│   │           ├── C14ENM503_29234d348acaf59ecab15b2dba67f1ed.mp3
│   │           ├── C14ENM504_3652113f43262302075bf6c7d17000b7.mp3
│   │           └── C14ENM505_16a8bd418db3c7618db8afbb2af6a7e3.mp3
│   ├── H/                              # Habits Category
│   │   └── H23EN/                      # Quit Smoking Course (English)
│   │       ├── F/                      # Female Voice Files
│   │       │   ├── H23ENF501_ce67f98b7d6f0397d9779d93a8cd2447.mp3
│   │       │   ├── H23ENF502_4d2c08a26db4d77cc03c1fd96e771275.mp3
│   │       │   ├── H23ENF503_06b7b4b28c2891e68afe8f5728c2b75b.mp3
│   │       │   ├── H23ENF504_b40ec580843110778ccc25acd7df5112.mp3
│   │       │   ├── H23ENF505_484182f60752ae194e95ba35f3e31d4a.mp3
│   │       │   └── H23ENF506_2f7c7a6886fd3c34f7d08396da57cd12.mp3
│   │       └── M/                      # Male Voice Files
│   │           ├── H23ENM501_5ce119305a15d6724ab86b61bbe9bee3.mp3
│   │           ├── H23ENM502_e0c896b1efc10a8fbfb48daa5e008349.mp3
│   │           ├── H23ENM503_a4367770aaefbff729916dd7fefb1512.mp3
│   │           ├── H23ENM504_ed7bc996e9e58f61f9499bbbf2cb652a.mp3
│   │           ├── H23ENM505_4605ab49ba8045b4e7727728d3c47efc.mp3
│   │           └── H23ENM506_48099c35d2f7ad339e8287e032b4577c.mp3
│   ├── P/                              # Productivity Category
│   │   └── P11EN/                      # Productivity Course (English)
│   │       └── M/                      # Male Voice Only
│   │           ├── P11ENM501_2f2e9ca2718a1b79a0c55c655d6d7a8e.mp3
│   │           ├── P11ENM502_6117eca6ebf8df43e6b11b860660cbc2.mp3
│   │           └── P11ENM503_509361ce78c9a98c0a7298cd83769660.mp3
│   ├── S/                              # Self-care Category
│   │   └── S66EN/                      # Weight Loss Course (English)
│   │       ├── F/                      # Female Voice Files
│   │       │   ├── S66ENF501_a335acaf53ada0da666dab706d42d21e.mp3
│   │       │   ├── S66ENF502_82aeadab9874685652251e400c999cd8.mp3
│   │       │   ├── S66ENF503_e9594a8c69527ef4fd7d6376ca2af750.mp3
│   │       │   └── S66ENF504_e09f2dc9033d953141ac798f0aced01f.mp3
│   │       └── M/                      # Male Voice Files
│   │           ├── S66ENM501_c5914c3125c64b3507d6d8ec3d448dde.mp3
│   │           ├── S66ENM502_3ac756878a4afcc07a5164ab287f6733.mp3
│   │           ├── S66ENM503_b00294b13c3c8f43f382b57120456f69.mp3
│   │           └── S66ENM504_0667919cea7f982b2bd6cf2c88712e1b.mp3
│   ├── background/                     # Background Music Files
│   │   └── B00/
│   │       ├── B001_aaae3a218c1e01f1beffe3f89273856b.mp3
│   │       ├── B002_3a482a66d9775c5daca1e45dcda0823b.mp3
│   │       └── B003_42248b9f5ed69a634cb4f417873cf359.mp3
│   └── core/                           # Core Segment Files
│       └── A00EN/
│           ├── F/                      # Female Core Segments
│           │   ├── A00ENF101_13809ef1f684d9db60a326f193cc0bcd.mp3        # Warning
│           │   ├── A00ENF201_13809ef1f684d9db60a326f193cc0bcd.mp3        # Countdown (Induction)
│           │   ├── A00ENF202_41a4e590e0bbb86afb4c6f9eceafa548.mp3        # Relaxation (Induction)
│           │   ├── A00ENF203_1bdc19d520c6ecc5f854e00c26cac48d.mp3        # Eyefixation (Induction)
│           │   ├── A00ENF401_0984630b6ecea12a2b937975821274c5.mp3        # Elevator (Deepening)
│           │   ├── A00ENF402_53ef1dccd2a14db8b62e759c2da2796f.mp3        # Fraction (Deepening)
│           │   ├── A00ENF403_d8820149ec9a659548e41d053bd82908.mp3        # Visual (Deepening)
│           │   ├── A00ENF801_8e062225ff31fa60dcb67812e35090f1.mp3        # Daytime (Emergence)
│           │   ├── A00ENF802_5a547c3e5136d32bac31aea4605e249a.mp3        # Anytime (Emergence)
│           │   └── A00ENF803_6f6e174098c8946e75f2b59f5b42b640.mp3        # Nighttime (Emergence)
│           └── M/                      # Male Core Segments
│               ├── A00ENM101_cc122d54426b13d903bf3cbce520f441.mp3        # Warning
│               ├── A00ENM201_cc122d54426b13d903bf3cbce520f441.mp3        # Countdown (Induction)
│               ├── A00ENM202_7a88e5aa67cb7073f8714089797a944a.mp3        # Relaxation (Induction)
│               ├── A00ENM203_f7e37df6502c9ded9a47aad0024daff2.mp3        # Eyefixation (Induction)
│               ├── A00ENM401_928ab5347e3bbe99e0cef84ef370ede2.mp3        # Elevator (Deepening)
│               ├── A00ENM402_fce41e608de3d735575d8daf690ac995.mp3        # Fraction (Deepening)
│               ├── A00ENM403_9eb0d88582a51f3a8ae9cffad064d8b7.mp3        # Visual (Deepening)
│               ├── A00ENM801_e981df16ca14212a936c97f3ea571488.mp3        # Daytime (Emergence)
│               ├── A00ENM802_caa25b6b5b50893f03a82bbf377f9e09.mp3        # Anytime (Emergence)
│               └── A00ENM803_02225bb555a94e33e632db681e1094c6.mp3        # Nighttime (Emergence)
├── Htmls/                              # HTML Content Files
│   ├── Ads/                            # Advertisement HTML Files
│   │   ├── ADEN1_44164cd50cfe10a3cfeca2296a0a4500.html
│   │   └── ADEN2_3fe1762487063409194748cbc2efeda3.html
│   ├── FAQs/                           # Help Documentation
│   │   ├── FAQEN1_e8178c0fef222d92b91aa687fabf3be1.html
│   │   ├── FAQEN2_e8178c0fef222d92b91aa687fabf3be1.html
│   │   ├── FAQEN3_e8178c0fef222d92b91aa687fabf3be1.html
│   │   ├── FAQEN4_e8178c0fef222d92b91aa687fabf3be1.html
│   │   └── FAQEN5_e8178c0fef222d92b91aa687fabf3be1.html
│   ├── Shop/                           # Course Benefit Pages
│   │   ├── C14ENS_baeca65a06fd17be2814c5affb0c0884.html
│   │   ├── H23ENS_baeca65a06fd17be2814c5affb0c0884.html
│   │   ├── P11ENS_baeca65a06fd17be2814c5affb0c0884.html
│   │   ├── S66ENS_baeca65a06fd17be2814c5affb0c0884.html
│   │   └── W22ENS_baeca65a06fd17be2814c5affb0c0884.html
│   └── WorkBooks/                      # Interactive Course Workbooks
│       ├── C/                          # Confidence Workbooks
│       │   └── C14EN/
│       │       ├── C14ENB1_daedcfd5674150f0c7eaced9be95bbaa.html
│       │       ├── C14ENB2_d74706ae437df9f7e595da49e7c5d1e8.html
│       │       ├── C14ENB3_6d08a74e9b12a1e46eb697ce043ce756.html
│       │       └── C14ENB4_dcec9b938bb9e9689ef2c2f3ec16f5bc.html
│       ├── H/                          # Habits Workbooks
│       │   └── H23EN/
│       │       ├── H23ENB1_daedcfd5674150f0c7eaced9be95bbaa.html
│       │       ├── H23ENB2_2ce8ca8859ad5d80b515a6487a98a23e.html
│       │       ├── H23ENB3_30d985264905d39a7b54702dc43bc343.html
│       │       ├── H23ENB4_200652017c6731dd2e0ad891306cd096.html
│       │       ├── H23ENB5_3ebb0fcb9b8f5cd37b0f3c25ad39f295.html
│       │       └── H23ENB6_650ebc2c8c795ec0a8233cd55b7a52aa.html
│       └── S/                          # Self-care Workbooks
│           └── S66EN/
│               ├── S66ENB1_64b2a0ec6c84917ffb540d163debcf12.html
│               └── S66ENB2_a0431b253edf38fad3dff3a28d99bfe0.html
├── Icons/                              # Visual Assets
│   ├── Courses/                        # Course Icon Files
│   │   ├── C14ENB_7c3bfbfd436718553d1884a18b267bc5.png
│   │   ├── H23ENB_d0652ddd5601724735fbb3c651727d9a.png
│   │   ├── P11ENM_ee448ab7e57e9ce79a95b104018f3990.png
│   │   └── S66ENB_65e9a65f91707231e72c690492a5aefc.png
│   ├── FAQs/                           # FAQ Icon Files
│   │   ├── FAQEN1_9f39dad73f2df6e9415e71abc4bd1a80.png
│   │   ├── FAQEN2_f0d62baea56d1ef8a4eae98f3ef6d4d3.png
│   │   ├── FAQEN3_af9d1a0bc5d5638bf278df45e91916fb.png
│   │   ├── FAQEN4_a5fd994e713b1972af7acdae39e15fc6.png
│   │   └── FAQEN5_b05ec5170ae12a4671e2bf94d6909f83.png
│   └── Shop/                           # Shop Icon Files
│       ├── C14ENS_7c3bfbfd436718553d1884a18b267bc5.png
│       ├── H23ENS_d0652ddd5601724735fbb3c651727d9a.png
│       ├── P11ENS_ee448ab7e57e9ce79a95b104018f3990.png
│       ├── S66ENS_65e9a65f91707231e72c690492a5aefc.png
│       └── W22ENS_3d70685586919df329bbfaecad11003c.png
├── Images/
│   └── lucidflow_logo.png
└── JSONs/                              # Configuration Files
    ├── User_Audio_Usage/               # Audio Play Tracking
    │   ├── C14ENB_Usage.json
    │   ├── H23ENB_Usage.json
    │   ├── P11ENM_Usage.json
    │   └── S66ENB_Usage.json
    ├── User_Owned_Courses/             # Course Configurations
    │   ├── C14ENB.json                 # Confidence Course Config
    │   ├── H23ENB.json                 # Quit Smoking Course Config
    │   ├── P11ENM.json                 # Productivity Course Config
    │   └── S66ENB.json                 # Weight Loss Course Config
    ├── User_Workbook_Responses/        # User Response Data (when completed)
    ├── ads.json                        # Advertisement Configuration
    ├── background.json                 # Background Music Configuration
    ├── core_segments.json              # Core Audio Segments Configuration
    ├── FAQs.json                       # Help Content Configuration
    ├── shop.json                       # Course Catalog Configuration
    └── user_profile.json               # User Settings and Preferences

File Organization Principles

📂

Category-Based Organization

Audio files are organized by category (C, H, P, S, etc.) and then by course number for easy navigation and management.

🎤

Voice Separation

Male (M) and Female (F) voice files are stored in separate folders to enable quick voice switching without file conflicts.

📋

JSON Configuration

All app behavior is controlled through JSON files, making it easy to update content without app updates.

💾

User Data Separation

User-specific data (usage, responses, preferences) is separated from app content for privacy and easy backup.

File Naming Patterns

🔤 Updated File Naming Convention

All files now follow an enhanced naming system with language codes and MD5 checksums:

  • Audio Files: [CourseCode][Language][Voice][Segment][Position]_[32-digit-md5].mp3
  • Core Audio: A00[Language][Voice][Segment][Position]_[32-digit-md5].mp3
  • Background: B00[Position]_[32-digit-md5].mp3
  • Workbook Files: [CourseCode][Language]B[Position]_[32-digit-md5].html
  • Icon Files: [Type][Language][Position/Code]_[32-digit-md5].png
  • Shop/FAQ/Ad Files: [Type][Language][Position]_[32-digit-md5].html
  • JSON Files: [CourseCode][Language][Voice].json or standard names

🔢 Enhanced Naming System

  • Language Codes: EN (English), ES (Spanish), FR (French), etc.
  • Voice Types: F (Female), M (Male), B (Both)
  • Segment Numbers:
    • 10 - Warning segment
    • 20 - Induction segments
    • 40 - Deepening segments
    • 50 - Main course content
    • 80 - Emergence segments
  • Position: Sequential number (01, 02, 03...) for multiple files of same type
  • MD5 Checksum: 32-character hexadecimal string for file integrity
  • Examples:
    • Course: C14ENF501_... = Confidence, English, Female, Content, Position 1
    • Core: A00ENM201_... = Core, English, Male, Induction, Position 1
    • FAQ: FAQEN1_... = FAQ, English, Position 1

💳 Payment Integration

The app uses Google Play Billing for Android purchases and handles both individual course purchases and subscription-based access. There is separate accounting for different payment types.

Payment Models

🆓

Free Tier

New users get access to one free course and a 1-month trial subscription

  • Confidence Building Course (C14) - FREE
  • 1-month free subscription trial
  • Limited AI usage minutes
  • Access to basic features
🛒

Individual Course Purchase

Users can buy specific courses and access them as long as subscription is active

  • One-time purchase per course
  • Access to purchased course as long as subscription is active
  • Requires active subscription
💎

Premium Subscription

Monthly or annual subscription providing access to all courses

  • Access to all purchased courses
  • Enhanced AI usage minutes
⏰

Subscription Expiry

When subscription expires, users lose access to their purchased courses

  • Lose access to all purchased courses
  • AI usage returns to free tier limits
  • Can renew subscription anytime

Google Play Billing Integration

🔧 Technical Implementation

  • Platform: Google Play Billing API for Android purchases
  • Product Types: Both one-time purchases (courses) and subscriptions
  • Verification: Server-side receipt validation through Google Play Console
  • Account Separation: Individual course purchases tracked separately from subscriptions
  • Offline Support: Cached purchase status for offline functionality

Purchase Flow

🛍️ Course Purchase Flow

  1. Browse Catalog: User views available courses in the Courses Tab
  2. Select Course: User taps on a premium course they want to purchase
  3. Payment Dialog: Google Play Billing dialog appears with course price
  4. Payment Processing: Google handles payment authentication and processing
  5. Receipt Validation: App validates purchase receipt with backend server
  6. Course Unlock: Course is added to user's owned courses list
  7. Download Content: Course audio and workbook files are downloaded
  8. Access Granted: User can now access the purchased course indefinitely

💎 Subscription Flow

  1. Subscription Offer: User sees subscription options in app settings or when accessing premium features
  2. Plan Selection: User chooses monthly or annual subscription plan
  3. Google Play Dialog: Google Play Billing handles subscription signup
  4. Subscription Activation: Backend validates subscription and updates user status
  5. Content Unlock: All premium courses become accessible
  6. AI Features Unlocked: User gets unlimited AI usage minutes
  7. Auto-Renewal: Google Play handles automatic subscription renewal

User Journey Examples

🆓 Free User Journey

New user experience with free content and trial:

  • Day 1: Sign up → Get free Confidence course + 1-month trial subscription
  • Week 1-4: Access all courses with trial subscription
  • Trial Ending: Receive notifications about trial expiration
  • After Trial: Lose access to premium courses, keep free Confidence course
  • Purchase Decision: Can buy individual courses or subscribe to premium

🛒 Course Buyer Journey

User who prefers individual course purchases:

  • Browse: User finds specific course they need (e.g., Quit Smoking)
  • Purchase: Buy course individually for one-time payment
  • Access: Can access their purchased courses as long as subscription is active
  • Additional Courses: Can purchase more courses as needed

⚠️ Implementation Considerations

  • Google Play Policies: Ensure compliance with Google Play billing and content policies
  • Receipt Validation: Implement secure server-side validation to prevent fraud
  • Offline Access: Handle purchase verification when users are offline
  • Subscription Management: Provide easy cancellation and subscription management
  • Platform Consistency: Ensure consistent pricing and features across platforms
  • Tax Compliance: Handle different tax requirements for digital goods globally

🛠️ Development Guide

Prerequisites

Quick Start

# Clone the repository
git clone [repository-url]

# Navigate to project directory
cd lucidflow

# Install dependencies
flutter pub get

# Run the app using emulator
# In Android Studio, run your preferred emulator
# In terminal, enter "flutter devices" and run "flutter run -d [your emulator code]"

Common Development Tasks

Adding a New Course

  1. Create course JSON in AppData/JSONs/User_Owned_Courses/[CourseCode].json
  2. Add audio files to AppData/Audio/[Category]/[CourseCode]/
  3. Create workbook HTMLs in AppData/Htmls/WorkBooks/[Category]/[CourseCode]/
  4. Update shop.json with course metadata
  5. Add course icon to AppData/Icons/Courses/

Modifying Audio Segments

  1. Update core_segments.json for core segments
  2. Test compilation with SegmentCompilerService
  3. Verify cross-platform playback in AudioMixer
  4. Update checksums and file sizes in manifest

UI/UX Updates

  1. Follow theme constants in lib/constants/theme.dart
  2. Use Provider pattern for state management
  3. Test on multiple screen sizes and orientations
  4. Ensure offline functionality is maintained

Building for Production

Android Build

# Build APK for release
flutter build apk --release

# The APK will be in:
build/app/outputs/flutter-apk/app-release.apk

Web Build (Coming Soon)

# Build for web deployment
flutter build web

# Output will be in:
build/web/

iOS Build (Coming Soon)

# Build for iOS (requires macOS)
flutter build ios --release

# Build with Xcode
cd ios
xcodebuild -workspace Runner.xcworkspace \
           -scheme Runner \
           -configuration Release

Environment Configuration

Required Environment Variables

Debugging Tips

Debugging the APK on Real Device

To debug the release APK on a real Android device and view logs in real-time:

  1. Enable Developer Options: On your Android device, go to Settings → About Phone → Tap "Build Number" 7 times to enable Developer Options
  2. Enable USB Debugging: Go to Settings → Developer Options → Enable "USB Debugging"
  3. Set USB Configuration: In Developer Options → "Default USB Configuration" → Select "File Transfer" or "MTP"
  4. Connect Device: Connect your Android device to PC via USB cable
  5. Install and Launch APK: Install your built APK on the device and launch the app
  6. View Logs: On your PC, open Command Prompt and enter:
# View Flutter logs in real-time
adb logcat | findstr flutter

# Alternative: Filter by your app package name
adb logcat | findstr hypnoelp

# View all system logs (more verbose)
adb logcat

Note: Make sure ADB (Android Debug Bridge) is installed and accessible from your command line. It comes bundled with Android Studio SDK tools.

Git Version Control

Branch Structure

🌟 master

Main branch where all finalized, production-ready commits are saved

📱 temp

Temporary branch for Android codebase development and testing

🍎 temp_ios

Temporary branch for iOS codebase development and testing

Commit Format

Format: m.dd.version.time. Description

Example: 8.13.1.12:18. Updated Homescreen

  • m: Month (e.g., 8 for August)
  • dd: Day (e.g., 13)
  • version: Version number (e.g., 1)
  • time: Time in HH:MM format (e.g., 12:18)
  • Description: Brief description of changes

Git Workflow

# Initialize repository (first time only)
git init

# Check current status
git status

# Add all changes
git add .

# Commit with proper format
git commit -m "8.13.1.12:18. Updated Homescreen"

# Switch to appropriate branch (choose one):
git checkout -b master     # For finalized commits
git checkout -b temp       # For Android development
git checkout -b temp_ios   # For iOS development

# Push to remote repository
git push origin [branch-name]

# Alternative: Set upstream and push
git push -u origin [branch-name]

📋 Complete Workflow Steps:

  1. Check Status: git status - See what files have changed
  2. Stage Changes: git add . - Add all changes to staging
  3. Commit: git commit -m "format" - Commit with proper message format
  4. Switch Branch: git checkout -b [branch] - Create/switch to appropriate branch
  5. Push: git push origin [branch] - Push to remote repository

✅ Best Practices:

  • Always check status before committing to see what files are modified
  • Use descriptive commit messages that explain what was changed
  • Commit frequently with small, logical changes
  • Push to temp branches for testing before merging to master
  • Keep master clean - only merge thoroughly tested code

📝 Important Notes

⚠️ Critical Considerations

  • Audio Files: Large files stored in internal storage, not Flutter assets
  • Offline Support: App must function with cached data when network unavailable
  • Authentication: Complex flow due to email confirmation and deep links
  • Storage Permissions: Required for Android to access downloaded content

🔮 Future Enhancements

  • iOS platform support with native optimizations
  • Progressive Web App (PWA) functionality
  • Advanced AI personalization features
  • Social features and progress sharing
  • Additional language support
  • Integration with health tracking apps

✅ Best Practices

  • Always test on real devices before release
  • Maintain backward compatibility with older app versions
  • Keep user data privacy as top priority
  • Document all API changes and migrations
  • Use semantic versioning for releases
  • Regular security audits and dependency updates