Controller Scripts

Overview

This document lists the controller scripts/functions needed to execute various operations in LBH Educate.

Controllers are organized by functional domain to separate concerns between Journal Mode (reactive) and Ideas Mode (proactive).

Core Controllers

Data Import & Seeding Controllers

importSkillsFromCSV(csvFilePath)

• Parses Skills-Skills.csv and imports into Skills table
• Handles hierarchical structure (Category → Sub-category → Skill)
• Stores alternative names for matching flexibility
• Returns import summary (count of skills imported, any errors)

importBehavioursFromCSV(csvFilePath)

• Parses Behaviours-Table 1.csv and imports into Behaviours table
• Stores alternative names for matching flexibility
• Returns import summary

importKnowledgeAreasFromCSV(csvFilePath, category)

• Parses knowledge area CSVs (e.g., Household-Cooking.csv, Society-Table 1.csv)
• Extracts knowledge domains and sub-domains
• Links knowledge areas to related skills
• Returns import summary

importActivitiesFromCSV(csvFilePath, knowledgeAreaId)

• Parses activity ideas from CSV files
• Creates Activity records linked to knowledge areas
• Handles "Skills used" column by matching to Skills table
• Stores progression level (1-3 scale)
• Returns import summary with skill matching report

matchSkillNameToTaxonomy(skillNameString)

• Fuzzy matching function to link activity "skills used" to Skills table
• Handles variations in skill naming between CSVs
• Returns matched Skill ID or null if no match found

seedDatabase()

• Orchestrates full database seeding from all CSV files
• Calls all import functions in correct order
• Handles dependencies (Skills must be imported before Activities)
• Returns comprehensive import report

Authentication Controllers

initiateOAuthFlow(provider)

• Initiates OAuth authentication flow with specified provider (Google, Apple, or Microsoft)
• Handles provider-specific configuration

handleOAuthCallback(authToken, provider)

• Processes OAuth callback from provider
• Validates authentication token
• Creates or updates user record in database

getCurrentUser()

• Retrieves currently authenticated user from session

signOut()

• Ends user session and clears authentication state

Child Profile Controllers

createChildProfile(userId, childData)

• Creates new child profile linked to authenticated user
• Validates and stores child information (name, DOB, interests, curriculum approach)

updateChildProfile(childId, updatedData)

• Updates existing child profile information
• Handles photo uploads if profile picture changed

getChildrenForUser(userId)

• Retrieves all child profiles associated with a user
• Returns array of child records

getChildById(childId)

• Retrieves single child profile with full details

transferChildOwnership(childId, newOwnerId)

• Transfers child profile ownership to another user (e.g., child taking ownership)
• Maintains access history for original creator

archiveChild(childId)

• Marks child profile as inactive without deleting data

Photo & Media Controllers

capturePhoto()

• Opens device camera for photo capture
• Returns photo data/reference

selectPhotoFromLibrary()

• Opens photo library picker
• Returns selected photo data/reference

uploadPhoto(photoData, childId)

• Uploads photo to cloud storage
• Returns cloud storage URL/reference
• Handles compression and optimization

deletePhoto(photoUrl)

• Removes photo from cloud storage
• Handles cleanup when entry is deleted

Journal Entry Controllers

createJournalEntry(childId, photoUrl, notes, entryDate)

• Creates new journal entry record
• Stores basic entry information before AI processing

updateJournalEntry(entryId, updatedData)

• Updates existing journal entry (notes, skills, photo, etc.)

deleteJournalEntry(entryId)

• Deletes journal entry and associated records
• Triggers photo deletion
• Updates skill progress calculations

getEntriesForChild(childId, filters, pagination)

• Retrieves journal entries for a child
• Supports filtering by date range, skills, keywords
• Returns paginated results

getEntryById(entryId)

• Retrieves single journal entry with full details

searchEntries(userId, searchQuery, filters)

• Full-text search across journal entries
• Searches notes, skills, dates
• Returns matching entries

AI Analysis Controllers

analyzePhoto(photoUrl, contextNotes)

• Sends photo and optional context to AI service
• Returns AI analysis data (detected activities, environments, objects, people, interactions)

suggestTemplate(aiAnalysisData, childAge)

• Takes AI analysis and child context
• Returns most appropriate template suggestions
• Ranked by confidence/relevance

suggestSkills(templateId, aiAnalysisData, childAge)

• Suggests specific skills demonstrated based on template and AI analysis
• Returns array of skills with confidence levels
• Considers child's age and developmental stage

suggestBehaviours(templateId, aiAnalysisData, childAge)

• Suggests character traits demonstrated based on template and AI analysis
• Returns array of behaviours with confidence levels
• Analyzes social interactions, emotional responses, initiative-taking

learnFromUserCorrections(entryId, aiSuggestions, userSelections)

• Tracks when users accept/reject/modify AI suggestions (skills + behaviours)
• Feeds data back to improve future suggestions
• Updates AI model training data

Template Controllers

getTemplateById(templateId)

• Retrieves template with associated skills

searchTemplates(searchQuery)

• Searches templates by name, keywords, associated skills

getTemplatesForActivity(activityKeywords)

• Finds templates matching activity description
• Used by AI suggestion engine

getCuratedTemplates()

• Returns developer-curated "sure-fire win" templates
• Prioritized for new users

Skill & Behaviour Tagging Controllers

getAllSkills()

• Retrieves complete skill taxonomy (64 core skills across 6 categories)
• Returns hierarchical skill tree with Category → Sub-category → Skill structure

getSkillsByCategory(category)

• Filters skills by category (Literacy, Communication, Numeracy, Motor skills, Analytical, Cognitive)

searchSkills(searchQuery)

• Searches skill names, descriptions, and alternative names
• Returns matching skills for quick-add

getAllBehaviours()

• Retrieves complete behaviours taxonomy (22 character traits)
• Returns flat list of behavioural attributes

searchBehaviours(searchQuery)

• Searches behaviour names, descriptions, and alternative names
• Returns matching behaviours for quick-add

addSkillsToEntry(entryId, skillsArray)

• Links multiple skills to a journal entry
• Creates EntrySkill junction records with confidence levels

addBehavioursToEntry(entryId, behavioursArray)

• Links multiple character traits to a journal entry
• Creates EntryBehaviour junction records with confidence levels

removeSkillFromEntry(entryId, skillId)

• Removes skill association from entry
• Updates skill progress calculations

removeBehaviourFromEntry(entryId, behaviourId)

• Removes behaviour association from entry

createCustomSkill(userId, skillName, category)

• Allows users to add custom skills beyond the 64 core skills
• Flags as user-generated for potential review/incorporation

createCustomBehaviour(userId, behaviourName)

• Allows users to add custom behaviours beyond the 22 core character traits
• Flags as user-generated for potential review/incorporation

Skill Progress Controllers

calculateSkillProgress(childId, skillId)

• Analyzes all journal entries demonstrating a skill
• Calculates current proficiency level (age-relative)
• Determines trend (improving/stable/declining)
• Updates SkillProgress record

getProgressForChild(childId)

• Retrieves all skill progress records for a child
• Returns categorized progress summary

getProgressForSkill(childId, skillId)

• Retrieves detailed progress for specific skill
• Includes timeline, all related entries, trend analysis

identifySkillGaps(childId)

• Analyzes child's skill progress
• Identifies "dead zones" (skills not demonstrated recently or ever)
• Returns prioritized list of gap areas
• Considers age-appropriateness

getProgressTimeline(childId, dateRange)

• Returns chronological progress data for charting
• Shows skill development over time

Ideas Mode - Knowledge Area & Activity Controllers

getAllKnowledgeAreas()

• Retrieves all knowledge areas (Household, Society, Well-being, Travel, etc.)
• Returns categorized structure

getKnowledgeAreasByCategory(category)

• Filters knowledge areas by category (e.g., all Household knowledge areas)

getActivitiesForKnowledgeArea(knowledgeAreaId, progressionLevel)

• Retrieves activities for a specific knowledge area
• Optionally filters by progression level (1-3)

getAllActivities()

• Retrieves all available activity suggestions from database
• Includes knowledge area context and progression levels

getActivitiesForSkill(skillId, childAge)

• Finds activities targeting specific skill
• Filters by age appropriateness and progression level
• Returns activities from multiple knowledge areas

searchActivities(searchQuery, filters)

• Searches activities by name, description, skills, knowledge areas
• Applies filters (time, location, materials, progression level)
• Returns filtered and sorted results

getCuratedActivities()

• Returns developer-curated activity suggestions
• "Sure-fire wins" for skill development across knowledge areas

Ideas Mode - Recommendation Controllers

generatePersonalizedSuggestions(childId)

• Primary recommendation engine
• Analyzes skill gaps, child interests, age, curriculum approach
• Queries activity database
• Applies AI-enhanced personalization
• Creates SuggestedActivity records
• Returns prioritized activity suggestions

getSuggestedActivitiesForChild(childId, filters)

• Retrieves existing suggested activities
• Filters by status (suggested/bookmarked/dismissed)
• Applies user-specified filters

bookmarkActivity(childId, activityId)

• Marks suggested activity as bookmarked for later
• Updates SuggestedActivity status

dismissSuggestion(childId, activityId, reason)

• Marks activity as not interested
• Optionally captures reason for dismissal (improves future suggestions)

markActivityCompleted(suggestionId, journalEntryId)

• Links completed activity to journal entry
• Updates SuggestedActivity record
• Used for feedback loop analysis

refreshSuggestions(childId)

• Triggers re-analysis and generates new suggestions
• Called after significant journal entry additions or manual request

Live CV / Reporting Controllers

generateLiveCV(childId, dateRange, options)

• Main report generation function
• Queries journal entries, skill progress, achievements
• Compiles data into structured report format
• Applies customization options (audience type, sections)
• Creates LiveCV database record
• Returns report data

exportLiveCVAsPDF(cvId)

• Takes LiveCV record and generates PDF
• Applies formatting and branding
• Returns downloadable PDF

exportLiveCVAsJSON(cvId)

• Exports raw structured data as JSON
• For programmatic access or integration with other tools

shareLiveCV(cvId, recipientEmail)

• Sends generated report via email
• Handles privacy and permissions

getReportHistory(childId)

• Retrieves all previously generated reports for a child
• Allows re-download or viewing

Data Analysis & Insights Controllers

getActivityMetrics(childId, dateRange)

• Calculates entry frequency, photo count, skills tracked
• Returns summary statistics

getSkillCategoryBreakdown(childId)

• Analyzes skill progress by category
• Returns percentage breakdown (life skills vs. academic vs. behavioral, etc.)

getEntryTrends(childId, dateRange)

• Analyzes entry patterns over time
• Identifies active periods, inactive periods
• Used for parent engagement insights

detectMilestones(childId)

• Identifies significant achievements or first-time skill demonstrations
• Returns notable milestones for celebration

Processing Pipelines

Journal Entry Creation Pipeline

End-to-end flow:

1. capturePhoto() or selectPhotoFromLibrary() → Photo acquired
2. uploadPhoto() → Photo stored in cloud
3. createJournalEntry() → Entry record created
4. analyzePhoto() → AI analyzes photo and context
5. suggestTemplate() → Template suggestions generated
6. User selects template (or skips)
7. suggestSkills() + suggestBehaviours() → Skill and behaviour tags pre-selected
8. User confirms/modifies skills and behaviours
9. addSkillsToEntry() + addBehavioursToEntry() → Skills and behaviours linked to entry
10. calculateSkillProgress() → Child's progress updated
11. learnFromUserCorrections() → AI learning feedback

Key orchestration controller: orchestrateEntryCreation(childId, photoData, notes, entryDate, userSkillSelections, userBehaviourSelections)

• Manages full entry creation pipeline
• Coordinates photo upload, AI analysis, template suggestion, skill/behaviour tagging
• Handles errors at each stage
• Returns completed entry

Ideas Mode Recommendation Pipeline

End-to-end flow:

1. User enters Ideas Mode or system runs periodic analysis
2. identifySkillGaps() → Gaps identified
3. generatePersonalizedSuggestions() → Activities matched to gaps
4. Activities displayed with filters
5. User bookmarks activities → bookmarkActivity()
6. User completes activity and creates entry → markActivityCompleted()
7. Loop back: new entry updates skill progress → gap analysis refreshes

Key orchestration controller: orchestrateIdeasMode(childId)

• Manages gap identification and suggestion generation
• Coordinates between progress analysis and activity matching
• Returns comprehensive Ideas Mode data (gaps + suggestions)

Live CV Generation Pipeline

End-to-end flow:

1. User requests report for date range
2. generateLiveCV() → Queries and compiles data
3. exportLiveCVAsPDF() or exportLiveCVAsJSON() → Format conversion
4. shareLiveCV() → Optional distribution
5. Report stored in history → getReportHistory()

Key orchestration controller: orchestrateCVGeneration(childId, dateRange, format, options)

• Manages end-to-end report generation and export
• Handles format conversion and sharing
• Returns downloadable report

Function Inventory

By Functional Domain

Data Import & Seeding: 6 functions Authentication: 4 functions Child Profiles: 6 functions Photo & Media: 4 functions Journal Entries: 5 functions AI Analysis: 5 functions (added behaviour suggestions) Templates: 4 functions Skills & Behaviour Tagging: 12 functions (expanded to include behaviours) Skill Progress: 5 functions Knowledge Areas & Activities (Ideas Mode): 7 functions (expanded to include knowledge areas) Recommendations (Ideas Mode): 6 functions Live CV / Reporting: 5 functions Data Analysis & Insights: 4 functions Pipeline Orchestrators: 3 functions

Total: ~76 controller functions

Notes

• This is a living document that will be updated after each brainstorming prompt
• Focus on NAME and PURPOSE only - no implementation code at this stage
• Think in terms of business logic and orchestration
• Pipeline orchestrators handle multi-step processes to reduce complexity in individual screens
• Separation between Journal Mode (reactive) and Ideas Mode (proactive) maintains clear architectural boundaries