Aphasiatherapy SimpTell is the adaptive home-training companion inside the wider aphasiatherapy_umbrella. It enables people with aphasia to practice elliptical constructions. This README documents the functional structure, object model, and collaborative work streams that underpin the SimpTell application.

This export is purely for informational purposes, and is not meant to be runnable stand-alone. This code is meant to be executed within the proprietary AphasiaTherapy environment, and depends on functionality excluded from this export.

• Umbrella topology: SimpTell is an umbrella child application that plugs into the shared authentication (Aphasiatherapy.Guardian), storage (Aphasiatherapy.GcpStorageHelper), and domain contexts defined in the parent apps. This allows us to reuse account management, client onboarding, and logging pipelines without duplicating work.
• Phoenix LiveView delivery: The client-facing experience lives in AphasiatherapySimptell.CyclusLive and companion LiveView components. This stream handles the sequencing of exercises, the adaptive feedback loop, and renders the different interaction stages (introduction, word ordering, word form selection).
• Audio processing services: Speech capture and verification are encapsulated in AphasiatherapySimptell.SpeechToText. The module abstracts the Google Cloud Speech-to-Text workflow, including token brokerage via Goth, encoding, remote API invocation, and transcript matching heuristics.
• Domain orchestration: Generator and Validator modules manage the therapy cycle logic. They cooperate with shared Aphasiatherapy.Simptell contexts so SimpTell keeps stateful awareness of each client’s level, answered sentences, and progression rules.

• Client (Aphasiatherapy.Accounts.Client): Represents the individual learner. Relevant attributes include the active SimpTell level, references to assigned sentences, and permissions for media access.
• Cyclus (Aphasiatherapy.Simptell.ClientCyclus): A cyclus is a therapy session consisting of an ordered set of sentences at a specific difficulty level. The generator ensures that a learner always resumes an unfinished cyclus before a new one is created.
• Sentence (Aphasiatherapy.Simptell.Sentence): A sentence is the main unit of training content. It aggregates grammatical metadata, word entities, and an optional photo_id that links to supportive imagery hosted in cloud storage.
• Word (Aphasiatherapy.Simptell.Word): Words store grammatical constituents (subject, verb, etc.). They are used both for validating word order and for rendering visual cues during exercises.
• Answer (Aphasiatherapy.Simptell.ClientCyclusAnswer): Answers capture the learner’s progress, chosen word order, selected word forms, and scoring. This persisted state powers adaptive level changes and ensures repeat sessions pick up exactly where the client left off.

1. Session bootstrapping
   CyclusLive.mount/3 authenticates the learner, fetches an active cyclus, and prepares the first sentence. The generator either instantiates a new cyclus or restores the latest unfinished session.

2. Guided introduction
   Each sentence begins with an intro step. Support audio for this stage is served from Google Cloud Storage through signed URLs generated by GcpStorageHelper.

3. Word-order exercise
   Learners arrange draggable word cards. The chosen ordering is validated by the Validator module, which enforces grammatical rules (notAfterV, notBeforeS, etc.) on top of the word metadata.

4. Word-form exercise
   Once order is correct, the interface switches to selecting correct word forms. Answers are stored (via ClientCycluses.insert_client_cyclus/1 and ClientCyclusAnswers helpers), enabling detailed progress tracking.

5. Adaptive feedback
   After each sentence the LiveView computes per-step scores, applies adaptivity rules, and surfaces level adjustments (move up, stay, move down). These adjustments respect the global SimpTell level boundaries and keep the learner in a productive challenge zone.

6. Completion & reporting
   When a cyclus is exhausted, the interface updates the learner with summary feedback and provisions the next appropriate level. Persisted records are available to therapists for longitudinal insights.

• UI component library (lib/aphasiatherapy_simptell_web/components) provides a shared set of cards, dialog boxes, audio controls, and layout elements that keep the interface consistent with the wider Aphasiatherapy product line.
• Audio assistive tooling
  AudioPlayer LiveComponents and helper dialogs coordinate playback of guidance audio, reinforcing the multi-modal learning approach.
• Cloud integration
  SpeechToText handles offloading recognition to Google Cloud. It normalizes textual results and feeds them back into the LiveView workflow for instant feedback. Logging hooks are already in place to capture network or API failures for audit purposes.
• Testing foundation
  The test/ directory includes targeted unit tests for the generator, validator, and LiveView flows. These form the basis for regression protection as we extend content, add languages, or refine adaptivity heuristics.