Text Decoder

A conversation analysis app that helps you decode conversations, understand communication patterns, and build better relationships. Built by Digital ABCs.

What It Does

Paste or type a conversation and Text Decoder uses AI (Google Gemini) to:

• Split conversations into individual messages with speaker identification
• Analyse communication patterns and behaviours
• Provide insights from a curated behaviour library
• Track conversation history with profiles

Available on iOS (App Store / TestFlight), Android (Google Play), and Web.

Architecture

Layer	Technology
Frontend	Flutter / Dart (iOS, Android, Web, Desktop)
Backend API	Python / Flask on Google Cloud Run
AI	Google Gemini via google-generativeai SDK
Auth	Firebase Auth (Google Sign-In, Apple Sign-In)
Hosting	Firebase Hosting (web), Cloud Run (API)
Payments	In-App Purchases (Apple/Google), Stripe (web)
CI/CD	Codemagic (mobile), Cloud Build (API + web)

Project Structure

decoder/
├── app.py                  # Flask API backend
├── tests/                  # Python backend tests
├── flutter_app/            # Flutter frontend (iOS/Android/Web/Desktop)
│   ├── lib/               # Dart source code
│   │   ├── screens/       # UI screens (auth, conversation, library, profile)
│   │   ├── services/      # API, auth, storage services
│   │   ├── models/        # Data models
│   │   ├── providers/     # State management (Provider)
│   │   ├── widgets/       # Reusable UI components
│   │   └── utils/         # Utilities
│   └── test/              # Flutter tests
├── data/                   # Behaviour library data
├── scripts/                # Dev workflow scripts
├── firebase.json           # Firebase config + emulators
├── firestore.rules         # Firestore security rules
├── cloudbuild.yaml         # Cloud Build - API deployment
├── cloudbuild-web.yaml     # Cloud Build - Web deployment
├── codemagic.yaml          # Codemagic CI/CD for mobile builds
├── Dockerfile              # API container
└── requirements.txt        # Python dependencies

Getting Started

Backend (Flask API)

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run locally
flask run

Frontend (Flutter)

cd flutter_app

# Get dependencies
flutter pub get

# Run on your platform
flutter run                  # Default device
flutter run -d chrome        # Web
flutter run -d ios            # iOS simulator
flutter run -d android        # Android emulator

Running Tests

# All tests
./scripts/test_all.sh

# Backend only
pytest tests/ -v --cov=app

# Flutter only
cd flutter_app && flutter test

Audit & Compliance Data

Text Decoder maintains an auditable record of user consent and safety events in Firestore, tied to each user's Firebase Auth UID. This data can be used to demonstrate duty of care and regulatory compliance.

What Is Audited

Record Type	Firestore Collection	What It Proves
AI Disclaimer Acknowledgement	user_consents	User confirmed AI analysis is not a replacement for professional psychological, medical, or legal advice
Safety Concern Triggers	safety_events	User's conversation triggered the compassionate safety response and they were shown emergency service details and helpline numbers
Age Verification	user_consents	User confirmed they are 16 years of age or older (age_confirmed: true, minimum_age_requirement: 16)

Firestore Collection Schemas

user_consents — One record per user consent event:

{
  uid: "firebase-auth-uid",
  consent_id: "sha256-hash",
  terms_version: "1.0.0",
  terms_accepted: true,
  ai_disclaimer_acknowledged: true,
  age_confirmed: true,
  minimum_age_requirement: 16,
  consent_timestamp: "2026-03-05T10:30:00Z",
  ip_hash: "truncated-sha256",
  user_agent_hash: "truncated-sha256",
  created_at: <server timestamp>
}

safety_events — One record per safety concern detection:

{
  uid: "firebase-auth-uid",
  severity: "moderate" | "severe",
  categories: ["physical violence", "threats to life", ...],
  safety_resources_shown: true,
  emergency_numbers_shown: true,
  timestamp: <server timestamp>
}

No conversation text is stored in safety events (privacy by design). Only the category of concern and severity are recorded.

Querying Audit Data

Firebase Console:

1. Go to Firestore Database in the Firebase Console
2. Select the user_consents or safety_events collection
3. Filter by uid to find records for a specific user

gcloud CLI — All consents for a specific user:

gcloud firestore documents list \
  --collection-group=user_consents \
  --filter="uid=USER_FIREBASE_UID" \
  --project=YOUR_PROJECT_ID

gcloud CLI — All safety events for a specific user:

gcloud firestore documents list \
  --collection-group=safety_events \
  --filter="uid=USER_FIREBASE_UID" \
  --project=YOUR_PROJECT_ID

Cloud Logging (redundant log-based audit trail):

# Consent records
gcloud logging read 'resource.type="cloud_run_revision" AND textPayload:"Consent persisted to Firestore"' \
  --project=YOUR_PROJECT_ID --limit=100 --format=json

# Safety concern detections
gcloud logging read 'resource.type="cloud_run_revision" AND textPayload:"Safety concerns detected"' \
  --project=YOUR_PROJECT_ID --limit=100 --format=json

Privacy Protections

• IP addresses are stored as truncated SHA-256 hashes (not raw IPs)
• User agents are stored as truncated SHA-256 hashes
• Safety events record concern categories only — no conversation text is stored
• All collections are protected by Firestore security rules: users can only read their own records, writes are restricted to the backend (Firebase Admin SDK)

API Endpoints

Endpoint	Method	Auth	Purpose
/api/v1/legal/consent	POST	Required	Record user consent (persisted to Firestore)
/api/v1/legal/terms	GET	None	Get current terms version and consent requirements
/api/v1/legal/safety-resources	GET	None	Get helpline numbers and emergency service details

Deployment

Platform	Method	Command
API	Cloud Build	gcloud builds submit --config=cloudbuild.yaml
Web	Cloud Build	gcloud builds submit --config=cloudbuild-web.yaml
iOS	Codemagic	Triggered via Codemagic dashboard or push
Android	Codemagic	Triggered via Codemagic dashboard or push
Firebase	Firebase CLI	firebase deploy --only hosting

Environment Variables

The API requires these environment variables (set in Cloud Run or .env):

Variable	Purpose
GEMINI_API_KEY	Google Gemini API access
ENCRYPTION_KEY	Fernet key for sync encryption
APP_SECRET_KEY	Flask session secret

Distribution

• iOS: TestFlight (via Codemagic auto-submit) then App Store
• Android: Firebase App Distribution or Google Play
• Web: Firebase Hosting / Cloud Run

See archived/TESTER_DISTRIBUTION.md for detailed tester onboarding instructions.