Repository navigation
Technical Architecture and Deployment
This document describes the software architecture, WebAssembly pipelines, offline persistence layers, and build procedures for BridgeAAC (bridgeaac/core).
Note
Sub-50ms Latency Benchmark: Assistive communication requires instantaneous tactile and auditory feedback. Every data structure, signal subscription, and audio path in BridgeAAC is optimized for immediate local execution.
BridgeAAC is built to meet strict criteria critical for assistive communication:
- No Cloud Dependence: Core communication (boards, speech, editing, import/export) must work offline. No telemetry and no external database. Features that use the network, such as online speech and ARASAAC symbol search, are optional and opt-in.
- Instant Response Latency: When a button is tapped, speech and visual feedback must occur in under 50 milliseconds.
- Low Memory Footprint: Must run smoothly on 2GB RAM budget tablets and older iPads without crashing.
┌────────────────────────────────────────────────────────┐
│ Preact UI Layer │
│ Board, TopBar, MessageBar, Modals, Tools, Hub │
└───────────────┬────────────────────────┬───────────────┘
│ │
▼ ▼
┌───────────────────────────┐ ┌─────────────────────────┐
│ Speech Subsystem │ │ File & I/O Engine │
│ - meSpeak Web Audio │ │ - sql.js (SQLite WASM) │
│ - Piper ONNX (WASM SIMD) │ │ - fflate (ZIP / Deflate)│
│ - OS SpeechSynthesis │ │ - .ce / .obz / .bridge │
└───────────────┬───────────┘ └─────────────┬───────────┘
│ │
▼ ▼
┌────────────────────────────────────────────────────────┐
│ Local Persistence Layer │
│ IndexedDB (Boards/Audio/Images) + OPFS (ONNX Models) │
└────────────────────────────────────────────────────────┘
| Layer | Component | Purpose |
|---|---|---|
| UI Framework | Preact 10 (@preact/signals) |
Minimalist virtual-DOM UI with signals for instant, low-overhead rendering. |
| Build Tooling | Vite 8 + TypeScript 5.8 | Sub-second HMR and optimized ES2022 bundling. |
| Database Engine |
sql.js (SQLite WASM) |
In-memory SQLite execution to read and write AAC Backup *.c4v databases client-side. |
| Archive Unpacking | fflate |
High-speed, zero-dependency ZIP compression/decompression for .ce and .obz archives. |
| Neural Synthesis |
ONNX Runtime Web + Piper
|
Client-side neural speech inference via WebAssembly SIMD. |
| Offline PWA |
vite-plugin-pwa + Workbox
|
Service Worker pre-caching for 100% offline application delivery. |
| Desktop Wrapper | Electron 34 + electron-builder
|
Standalone desktop distribution for Windows, macOS, and Linux. |
| Mobile Runtime | Capacitor 7 & Swift (xtool) |
Native iOS/iPadOS and Android wrappers. |
BridgeAAC operates three independent client-side storage tiers:
-
bridgeaac_db: Stores user vocabularies, page grids, button configurations, and application preferences. -
bridgeaac_assets: Stores binary image blobs (ARASAAC symbols you choose, user photos) and custom audio recordings. -
bridgeaac_piper_files: Stores pre-cached vocabulary WAV clips (tts_cache).
- Used by the neural speech engine to store Piper ONNX model binaries (
.onnx) and voice configurations (.json). - If OPFS is unavailable on older iOS Safari versions, BridgeAAC automatically falls back to an IndexedDB binary store.
- Workbox precaches all JavaScript, CSS, HTML, WebAssembly modules, and core symbol assets. When the device loses Wi-Fi or cellular service, the application continues to boot and operate identically.
- The original symbols are SVG drawings written in TypeScript under
src/data/symbol-sets/, built from shared drawing helpers indraw.ts(people, hands, faces, buildings, food and so on). -
src/data/symbols.tsmerges the sets and maps everyday words to symbols with an alias table, sotelevisionandtvresolve to the same picture. - Buttons refer to symbols as
svg:bs-<id>. Because the symbols are bundled code, they need no network and are embedded into exported.cefiles. - To redraw the images in the README, store listings and this wiki after changing symbols, run
npm run store:assets,npm run brand:assetsandnode scripts/generate-symbol-sheet.mjs.
- Node.js: v18.0.0 or later (v20+ recommended)
- npm: v9.0.0 or later
# Clone the repository
git clone https://github.com/bridgeaac/core.git
cd core
# Install dependencies
npm install
# Start local development server with hot-reload
npm run devOpen http://localhost:5173 in your browser.
# Typecheck TypeScript definitions
npm run typecheck
# Run Vitest test suite
npm test
# Build production bundle for web
npm run buildBridgeAAC uses Electron and electron-builder:
# Run in Electron desktop mode locally
npm run electron:dev
# Build distributable desktop packages
npm run electron:distOutputs in release/:
-
Windows:
BridgeAAC Setup 1.0.0.exe(NSIS installer) and portable.exe. -
macOS:
BridgeAAC-1.0.0.dmgand universal.zip. -
Linux:
BridgeAAC-1.0.0.AppImageandbridgeaac_1.0.0_amd64.deb.
# Initialize Android project
npm run android:init
# Build Web bundle and sync Capacitor assets
npm run android:build
# Open in Android Studio
npm run android:openIn Android Studio: Select Build → Build Bundle(s) / APK(s) → Build APK(s).
BridgeAAC includes a native Swift package (Package.swift and Sources/BridgeAAC/ContentView.swift) configured for native compilation:
# Synchronize web bundle to Swift bundle directory
npm run ios:sync
# Compile using Swift Package Manager / xtool
swift build- Cloudflare Pages: The live site bridgeaac.org is deployed directly via Cloudflare Pages with automatic edge SSL and global CDN distribution.
-
GitHub Actions: Automated workflows in
.github/workflows/run linting, unit tests, and production builds on every pull request.
BridgeAAC • 100% Free & Open Source AAC • Immediate Family Support: support@bridgeaac.org • Legal & Medical Disclaimer • bridgeaac.org • GitHub (bridgeaac/core)
- File Interoperability & Migration
- Offline Speech & Neural Voices
- Motor Access & Switch Scanning
- Grid Editor & Customization
- Settings & Configuration
-
Life & Learning Hub
- Daily Visual Planner
- Mood Tracker & Analytics
- Skill Games (Sentence & Emotion)
- "About Me" Passport
- Passcode Caregiver Notes
- Caregiver & Classroom Guide
- Privacy, HIPAA & Security
- Languages & RTL Localization
- Architecture & Build Guide
- Legal & Medical Disclaimer
Immediate Family Support
External Links