AlloFlow Document Remediation README

AlloFlow (v1.2)

Adaptive Levels, Layers, & Outputs ➔ Flexible Learning Options for Whole-Student Education

🚀 What is AlloFlow?

AlloFlow is an open-source, privacy-first AI classroom assistant and instructional differentiation engine built for educators, special education teams, and school psychologists. Use the keyless Google-managed Gemini Canvas path with no installation, or run AlloFlow Desktop for a local-first teacher-laptop workflow.

For reading, start with the selected original text and add optional supports. Create an adapted companion when it serves the learning goal, keeping the original available alongside it. AlloFlow also creates learning activities and other differentiated resources.

No AlloFlow software subscription. Local classroom flows can run without student accounts or required PII. Cloud-provider terms, data handling, and costs depend on the deployment you choose.

Official AlloFlow website: apomera.github.io/AlloFlow

Official source repository: github.com/Apomera/AlloFlow

Official project facts: apomera.github.io/AlloFlow/about.html — maintained identity, version, license, privacy boundaries, and guidance for distinguishing the canonical project from forks.

Search identity: AlloFlow is a free open-source AI classroom assistant for differentiated instruction, UDL, accessibility, AAC communication, STEM/SEL tools, RTI, and local-first school deployments.

Current inventory (verified October 10, 2026): the repository registry check reports 151 STEM tool registrations and 72 SEL tool registrations; the STEM directory contains 151 plugin files. The broader July 3 codebase review remains the dated source for architecture and size estimates. AlloFlow Desktop is the everyday local-first path, while the Docker School Box stack is optional server/appliance infrastructure. See docs/codebase_review_2026-07-03.md, docs/code_size_inventory_2026-07-03.csv, docs/competitive_positioning_review_2026-07-03.md, and desktop/README.md.

🔗 Launch AlloFlow

⚡ Quick Start

1. Click to launch — opens the Gemini Canvas path (eligible Google account required; availability and school administrator settings apply)
2. Paste your lesson text into the Source Material box and identify the learning goal. If you generate a source from a topic, review it before teaching from it.
3. Choose Read original with supports to open the selected text unchanged. Use read-aloud and focus tools, and add optional word explanations. Opening the original does not require an AI call; generating explanations does.
4. Add a support when useful — a glossary, organizer, practice activity, or an adapted companion. An adaptation is supplemental by default; use Original / Adapted / Both to compare it with the captured source.
5. Review and try the student view before sharing. Check contextual meanings, important ideas, and learner fit. Then use a Live Session or export, and test what learners receive on their devices.

Reading walkthrough: Open the original, add word supports, compare versions, and check student delivery.

Need several resources? Full Pack can draft a set from your selected source. Use it when a lesson needs several supports, and review each resource before sharing.

💡 For local-first use on a teacher laptop, see desktop/README.md. For school-owned server/appliance experiments, see School Box below.

🏫 District decision-maker? See the 2-page Admin Brief — cost comparison, privacy/compliance, and pilot-path summary.

Agent-authored AlloPacks

An agent can author the same portable resource-pack structure without opening the AlloFlow UI. The local Agent Core MCP accepts agent-generated resource history, validates renderer-critical shapes and privacy safeguards, creates a teacher-review preview, and exports a .allopack.json payload. It does not silently call a model, read API keys, upload source text, publish content, or write arbitrary paths. See the MCP connector guide, the AlloPack specification, and the reusable AlloFlow resource-pack authoring skill.

Product tour

• Promotion site -- overview, deployment paths, and current evidence
• Official project facts -- canonical repository, current release, license, authorship, and deployment boundaries
• Tool finder -- search by goal, source requirement, AI need, and access path
• Document remediation -- pipeline, evidence boundaries, portable Skill, and connector status
• Ways to use AlloFlow -- compare Gemini Canvas, browser, Desktop, Skill, and connector paths
• Accessibility white paper -- standards context, architecture, privacy boundaries, and evidence
• Feedback -- safe routes for ideas, bugs, accessibility barriers, and de-identified use stories
• Feature catalog -- documented capabilities organized around UDL
• Student experience -- learner-facing tools and accessibility supports
• District brief -- planning, privacy, accessibility, and pilot considerations

Screenshots change quickly as the interface evolves. Use the current promotion pages and launch flow for the latest maintained product tour.

✨ Key Features

🎓 For Teachers

🎮 For Students

🩺 For Special Educators & BCBAs

🧠 For School Psychologists

STEM Lab (151 Plugin Files / 151 Registered Tool IDs)

The STEM Lab is a dynamically-loaded suite of browser-based interactive tools. As verified by node dev-tools/check_tool_registry.cjs on October 10, 2026, the workspace contains 151 stem_tool_*.js files and 151 registered STEM tool IDs.

Each tool supports Generate Drill for instant related practice sets and saves/restores state with the session.

Perception Lab offers seven visual experiments and three Match by eye activities for brightness, circle size, and line length. Learners can swap or remove surroundings, reveal drawing values, compare pinned settings at the same scale, and save observations with deletion undo and JSON export. See the Perception Lab enhancement report for previews and verification.

Each matching activity also supports a three-match study with fixed surroundings, varied starting positions, and separate notes. After recording all three, learners can reveal their median and range, review a saved study, or repeat its settings. See the repeated-study enhancement report for verification and previews.

Saved studies can be compared under the same experiment and reference. Independent reveals, a shared-scale plot, median shifts, and changed-setting explanations help learners compare their observations. See the study-comparison enhancement report.

Complete saved studies also offer a one-setting repeat planner. It keeps the reference and actual starting positions, protects baseline records at the notebook limit, and opens the two studies for independent reveals after three new matches. See the guided-study enhancement report.

Exported Perception notebooks can now be reopened with a previewed import. It preserves existing observations, keeps repeated matches together, checks the 24-record limit, and offers Undo import. See the notebook import enhancement report.

The Perception notebook also has a finder with observation and saved-study views, experiment/status filters, and search across visible notes, impressions, and titles. Repeated matches stay grouped, original notebook numbers remain visible, and open study comparisons are independent of the filters. See the notebook finder enhancement report.

Revealed Perception studies now include previews of their actual recorded drawings. Choose any of the three trials, inspect its impression and note, and compare independently selected A/B trials at the same scale. Preview controls preserve the current drawing and notebook. See the recorded drawing enhancement report.

Perception studies and ready A/B comparisons can now export standalone HTML reports containing every recorded drawing, full notes, settings, and results. Open the exported file in a browser to read or print it; incomplete or hidden studies cannot export. See the portable study report enhancement report.

The Perception notebook now shows saved and available spaces and preserves existing observations when full. Delete a whole saved study through a title/count preview, then restore all its records with one guarded Undo. See the notebook preservation enhancement report.

Recorded Perception drawings can be enlarged into a modal viewer with nearly full-window width, trial selection, measurement guides, and complete notes. Keyboard focus and saved-result visibility remain protected. See the enlarged drawing enhancement report.

Compatible Perception studies can also open together in an enlarged A/B viewer, with independent trial choices, equal drawing scale, and responsive or manual stacking. See the paired drawing enhancement report.

Saved A/B reviews now offer Switch drawings in one position, with buttons and arrow keys for comparing complete recorded trials at a fixed position and scale. Independent trials, guides, and notes stay intact; saved data and complete reports are preserved. See the stationary saved-drawing comparison report.

Saved trial drawings now have shared zoom and pan in enlarged reviews, with Fit, keyboard navigation, and native mouse/touch dragging. A/B views stay aligned while preserving saved data and complete reports. See the saved-drawing inspector report.

Enlarged saved drawings now show Whole drawing or the current cropped magnification beside the artwork, with a local Inspect/Fit action that keeps keyboard focus visible. See the saved-drawing frame report.

Saved study comparisons now use a responsive plot with readable labels and trial dots, a shared linear scale, and explicit range, median, and reference markers. See the study comparison plot report.

Individual study results now use responsive trial cards, with clear column labels, aligned values, and visible trial numbering on narrow screens and at larger text sizes. See the study trial ledger report.

Active three-match studies now show recorded, current, and upcoming steps beneath the results heading, with clear states for results awaiting reveal and revealed results. See the active study progress report.

A/B comparison details now keep result metrics and changed settings readable in compact, labelled rows on narrow screens and at enlarged text sizes. See the comparison details report.

Saved notebook observations now use responsive cards that separate the observation identity, recorded impression, full notes, and available actions. See the notebook observation cards report.

On narrow screens, a collapsible gallery now shows starting drawings for all seven experiments, with selection and keyboard focus preserved when switching experiments or resizing the workspace. See the mobile experiment preview gallery report.

Current and reference drawing captions now identify the surroundings or cube face cue and whether guides are visible, using each drawing's own settings throughout normal, switched, sliding, and focused views. See the drawing conditions report.

The live settings comparison table now stacks reference and current values into readable rows on narrow screens while preserving the existing comparison and hidden-value behavior. See the drawing changes report.

The current drawing now includes its impression prompt and a shortcut that opens the adjustment controls and focuses the selected or first impression choice. See the impression shortcut report.

The impression choices now include Go to drawing, completing the keyboard and touch route between the drawing and its observation controls. Choice columns also adapt to narrow spaces and enlarged text. See the drawing return report.

Magnified drawings now show a Cropped view indicator beside a direct Fit whole drawing shortcut, including when inspection controls are closed. The shortcut restores the full view and keyboard focus without changing saved experiment data. See the live frame report.

The drawing actions now share a clearer toolbar with labeled icons, a visible expanded inspection state, and responsive spacing. Comparison selection and closing controls sit above the action row, with guidance beneath. See the scene toolbar report.

The live drawing inspector now groups zoom and pan controls in a compact responsive panel. Viewing tips open on demand, while a concise crop reminder remains visible when magnified. See the inspector layout report.

Experiment settings now appear in distinct adjustment cards with clearer current values, responsive exact-value and Reset rows, and visible focus and validation states. See the adjustment cards report.

Perception Lab now has illustrated experiment choices, a clearer drawing workspace, compact recorded-drawing controls, and distinct results and note sections across responsive and accessible themes. See the visual presentation enhancement report.

Use Focus experiment to work in a nearly full-window Perception workspace with live controls, notes, matching studies, and pinned comparisons. Closing it preserves the drawing and returns keyboard focus to the workspace. See the focused experiment enhancement report.

Perception Lab can export the current drawing as a 2400 × 1440 PNG with an opaque white background, from either workspace. Exports preserve the captured frame and cancel safely when study or learner context changes. See the PNG export enhancement report.

Perception Lab offers side-by-side, full-width stacked, and stationary switch-view layouts for live comparisons. The shared toolbar works in the focused workspace, preserves drawing colors and scale, and keeps dark-theme comparison tables readable. See the live comparison enhancement report.

Slide drawings compares the current drawing with a reference from the same experiment in one view at the same scale. Drag the divider or use Arrow keys, Home, and End; buttons show either complete drawing or center the divider. It works with pinned, surroundings, and starting-view comparisons in both workspaces, including phones. Divider position is a local view preference; saved data and hidden measurements remain protected. SVG and PNG exports contain the complete current drawing. See the slide comparison enhancement report.

Inspect drawing adds 150%, 200%, and 300% magnification with bounded pan, direction controls, and keyboard navigation. Comparison drawings move together, including Slide drawings. The view works in both workspaces, preserves saved data and full exports, and returns to Fit for repeated studies. See the drawing inspector enhancement report.

The drawing inspector now includes a Current drawing overview with an outlined viewing window. Select or drag in the miniature to navigate magnified details, or use Arrow keys and Enter. Comparison views stay aligned, and saved data and full exports remain unchanged. See the drawing overview enhancement report.

Perception Lab supports direct numeric entry and individual resets for all thirteen experiment settings. Values apply on Enter or blur; invalid entries leave the drawing unchanged, and repeated-study controls remain locked. See the precision controls enhancement report.

The focused Perception workspace now keeps controls beside the drawing when space allows, with quick drawing/control navigation and room for enlarged text. Browse all seven experiments through its selector or Previous/Next controls while retaining each experiment's settings and notes. Browsing pauses moiré motion and stays locked until an active repeated study ends. See the focused browsing enhancement report.

Use Compare surroundings to inspect two live drawings at the same scale, with only their context differing. Both views follow your adjustments, preserve unrevealed matching values, and keep your saved pin available. The cube requires a face cue; tiles and grid views use explicit labels. The comparison works in all available layouts and both workspaces, and stays disabled throughout repeated studies. See the surroundings comparison enhancement report.

Free Match by eye activities now enter at a different starting point rather than equal drawing values. New starting point lets learners make another fresh match; Equalize drawing values explicitly restores equality. Both clear the previous impression and reveal while preserving notes and surroundings. Saved matching values and controlled repeated-study starts are retained. See the matching starting points enhancement report.

Try one change adds a fixed starting-view comparison for café wall, ambiguous cube, moiré, and Ponzo perspective. Learners choose a setting to explore, capture the current drawing, and compare their impressions while a change count distinguishes their chosen setting from other edits. Moiré capture pauses at the visible angle. The temporary starting view uses the existing comparison layouts, keeps the saved pin, and preserves ordinary observations and exports. See the starting-view inquiry enhancement report.

The inquiry guide now shows the chosen setting's starting and current values and provides Adjust chosen setting from both the guide and drawing. Restore chosen setting returns only that setting to the captured value; Restore other settings keeps the chosen change while returning the other changed settings. Notes, impressions, measurement guides, and the fixed starting view are preserved. See the inquiry controls enhancement report.

The inquiry guide can now export a standalone inquiry report for café wall, ambiguous cube, moiré, and Ponzo perspective. It preserves both drawings at the same scale, all settings, impressions, and full notes; measurement-guide differences are identified separately. Reports capture the visible moiré frame and can be read or printed without changing the experiment or notebook. See the inquiry report enhancement report.

Ponzo perspective adds adjustable perspective rails around two equal-length bars. Compare surroundings, reveal aligned endpoint guides, capture a starting view, restore individual inquiry settings, and export a printable inquiry report. The seventh experiment is available in both workspaces and the notebook. See the Ponzo expansion report.

Saved observations now offer Review observation with a drawing-first layout, labeled impression and note panels, saved settings, and a full-width drawing option on wide screens. Reviews preserve saved measurement visibility and can export a standalone printable HTML report without changing the live experiment or notebook. See the saved observation review enhancement report.

💚 SEL Hub (72 Interactive Tools)

The SEL Hub provides 72 social-emotional learning tools aligned with CASEL's core competencies and expanded AlloFlow categories such as self-direction, inner work, care of self, and stewardship:

Highlights include the Growth Mindset Workshop (Brain Science, Reframe Engine, Famous Yet Stories, AI Growth Coach, Letter to Future Me), Restorative Circle (5 circle types with Indigenous roots and talking pieces), Ethical Reasoning Lab (6 contemporary dilemmas, 6 ethical frameworks, stakeholder mapping), and Culture Explorer (80+ world cultures with AI-powered deep dives).

🔐 Privacy & FERPA-Aligned Deployment

AlloFlow is designed so schools can keep student data inside the browser, teacher device, or school-controlled infrastructure. Cloud use is explicit and deployment-dependent.

For districts using Google Workspace for Education: Canvas/Firebase coverage and student-privacy obligations depend on the district's account, contracts, retention settings, and actual use. AlloFlow is built to support FERPA-aligned deployments, but final compliance is a district/legal determination.

🏫 Local-First: Desktop and School Box

Status as of August 1, 2026: AlloFlow Desktop is the recommended local-first path for a teacher laptop or personal workstation. It serves the bundled app locally, manages keys and local AI settings, supports the built-in local engine, and can run same-room Desktop LAN sessions without Docker. The Docker School Box stack remains an optional server/appliance path for school-owned boxes, district/server experiments, and heavier air-gapped infrastructure.

For everyday local use:

npm.cmd run desktop:check
npm.cmd run desktop:smoke
npm.cmd run desktop

For optional School Box server/appliance testing:

# Clone the repository
git clone https://github.com/apomera/AlloFlow.git

# Start the optional Docker server stack
docker-compose up -d

What can run locally:

• AlloFlow Desktop — bundled app hosting, local keys, diagnostics, built-in local engine, local ASR/TTS settings, and Desktop LAN sessions
• Optional Docker School Box stack — server/appliance services such as PocketBase, Ollama, Piper, SearXNG, Flux, and Nginx when a school wants managed local infrastructure
• LM Studio / Ollama / LocalAI — compatibility paths for users who already run those local providers
• PocketBase — local database replacing Firebase

Hardware needs depend on the local model and service profile. See desktop/README.md, docker/README.md, and DEPLOY_YOUR_OWN.md.

♿ Accessibility

AlloFlow is built toward WCAG 2.2 AA with keyboard-first interaction patterns, automated audits, and per-tool accessibility gates. The current evidence set includes an interim v1.2 VPAT and a limited-scope WCAG 2.2 audit; neither is a product-wide certification. Compliance-sensitive deployments should still verify the exact workflow and exported artifacts they use.

• Dyslexia Fonts — OpenDyslexic, Lexend, Atkinson Hyperlegible
• Bionic Reading — bolds initial letters to guide decoding
• Voice options — word-for-word tracking through configured browser, cloud, Desktop, or optional local voice engines
• Color Overlays — Peach, Blue, Yellow tints for Irlen syndrome support
• Reading Ruler — mouse-following line isolation bar
• High Contrast & Dark Mode
• Voice Dictation — speech-to-text on all input fields
• Keyboard-first coverage — core navigation and audited workflows support standard keyboard interaction; use the published audit and report any tool-specific gaps

💵 Is It Really Free?

The software: yes — free and open-source under AGPL v3. The Gemini API usage depends on your deployment path:

🎯 UDL Alignment

Every feature maps to CAST's UDL Guidelines:

📚 Documentation

🔧 For Developers

AlloFlow uses a Hub-and-Spoke architecture — a single orchestrator component (App.jsx / AlloFlowANTI.txt, ~31K lines in the current deploy copy) dynamically loads a large set of modules and plugin families on demand: STEM Lab (151 plugin files / 151 registered IDs), SEL Hub (72 tools), BehaviorLens, Report Writer, Symbol Studio, Word Sounds, Student Analytics, StoryForge, Cinematic Studio (doc→video), AlloStudio, Open Groove Studio, Professional Development, Doc Pipeline, Games, AI Backend, and more. Modules are served from the selected deployment's static asset host; build.js handles URL resolution. See CONTRIBUTING.md for architecture rules and architecture.md for a full technical overview.

# Cloud deployment (Firebase)
cd desktop/web-app
npm install
npm run build
firebase deploy

# Desktop local runtime
npm.cmd run desktop:check
npm.cmd run desktop:smoke
npm.cmd run desktop

# Run clinical logic test suite (no dependencies)
node tests/clinical_tests.js

🧪 Test Suite

AlloFlow includes 117 automated tests covering clinical decision-making logic — the scoring algorithms, classification lookups, and data transformations that affect real student services. Tests are organized in three tiers:

• Tier 1 (Clinical Decisions): Score classification (standard + T-score), percentile calculation, PII scrubbing, RTI tier classification, developmental norms
• Tier 2 (Learning Tracking): Familiarity scoring, word growth levels, codename validation, Pearson correlation, aimline monitoring
• Tier 3 (Data Quality): Math fluency benchmarks, error analysis, doc pipeline issue normalization, assessment preset integrity

Run with node tests/clinical_tests.js — zero dependencies, just Node.js. See tests/README.md for full documentation.

🤝 Contributing

Contributions are welcome — especially new STEM/SEL tools, accessibility improvements, clinical test cases, and additional language support.

1. Read CONTRIBUTING.md for architecture rules (Hub-and-Spoke pattern, Cloudflare CDN module resolution, plugin templates).
2. Read architecture.md for a full technical overview.
3. Open a descriptive PR explaining which UDL checkpoint or clinical workflow your change enhances.

Quick wins for new contributors:

• Add a new STEM tool (stem_lab/stem_tool_yourname.js) — self-contained, no core file changes needed
• Add a new SEL tool (sel_hub/sel_tool_yourname.js) — same plugin pattern
• Add clinical test cases to tests/clinical_tests.js (verify expected values against assessment manuals)
• Improve i18n strings in ui_strings.js for an underrepresented language
• Add keyboard navigation to an existing game
• Fix an issue tagged good first issue on GitHub Issues

📄 License & Credits

AGPL v3 — free and open source under a strong copyleft license, supporting educational technology as a public good.

© 2026 Aaron Pomeranz, PsyD

Built by a school psychologist, for educators.
"Differentiation should be the default, not the exception."