🌍 UN GIM Multi-Country Survey Platform

Multi-tenant WhatsApp survey system for conflict analysis and peacebuilding consultations

Status: ✅ Production Ready (Syria LIVE) Last Updated: October 20, 2025

---

📊 Overview

This platform runs 3 independent WhatsApp surveys simultaneously for UN GIM consultations in:

Survey	Status	Phone Number	Language	Heroku App
Syria	✅ LIVE (v46)	+358454903164	Arabic	un-gim-survey-bot
Armenia	🔜 Ready to deploy	+358454901787	English	un-gim-survey-bot-armenia
Guinea-Bissau	🔜 Ready to deploy	(Purchase number)	Portuguese	un-gim-survey-bot-guinea

View Syria Data: https://un-gim-survey-bot-fe9d751698ce.herokuapp.com/list-survey-data?event_id=syria_survey_2025

---

📂 Project Structure

AI Consultation Tool/
│
├── README.md                    ← YOU ARE HERE
│
├── documentation/               ← General setup guides & architecture
│   ├── QUICK_START.md          ← Start here for orientation
│   ├── NEW_SURVEY_SETUP_GUIDE.md ← How to add new surveys
│   ├── FINAL_CONFIGURATION_OCT19_2025.md
│   ├── DEPLOYMENT_READY_SUMMARY.md
│   ├── MULTI_TENANT_IMPLEMENTATION_PLAN.md
│   └── archive/                ← Historical docs
│
├── syria-survey/               ← Syria WhatsApp bot (LIVE)
│   ├── app/main.py            ← Main webhook handler
│   ├── core/config.py         ← Configuration
│   ├── services/              ← Survey + export logic
│   └── [Syria-specific docs]
│
├── armenia-survey/             ← Armenia WhatsApp bot (Ready to deploy)
│   └── [To be created - duplicated from Syria]
│
├── guinea-bissau-survey/       ← Guinea-Bissau WhatsApp bot (Ready to deploy)
│   └── [To be created - duplicated from Syria]
│
├── sensemaking-tool/           ← AI analysis tool (post-survey)
│   └── [Data analysis codebase]
│
└── delete_test_user.py         ← Shared testing utility

---

🚀 Quick Start

For New AI Assistants:

1. Read: documentation/QUICK_START.md
2. Understand: documentation/FINAL_CONFIGURATION_OCT19_2025.md
3. Set up new survey: documentation/NEW_SURVEY_SETUP_GUIDE.md

For Developers:

Test Syria Survey:

python3 delete_test_user.py
# Send "Hello" to +358454903164 on WhatsApp
# View: https://un-gim-survey-bot-fe9d751698ce.herokuapp.com/list-survey-data?event_id=syria_survey_2025

Monitor Logs:

cd syria-survey
heroku logs --tail

Deploy Changes:

cd syria-survey
git add -A && git commit -m "message" && git push heroku main

---

🎯 Survey Architecture

Independent Deployments:

• Each survey = Separate Heroku app
• Each survey = Own codebase (duplicated, then customized)
• Complete isolation (changes to one don't affect others)

Shared Infrastructure:

• Firebase Project: yemeni-youth-engagement
• Twilio Account: Same account, different phone numbers
• AI Services: OpenAI (Whisper) + Anthropic (Claude)

Data Isolation:

Firebase Collections:
├── syria_users → syria-survey app only
├── syria_responses → syria-survey app only
├── armenia_users → armenia-survey app only
├── armenia_responses → armenia-survey app only
├── guinea_bissau_users → guinea-bissau-survey app only
└── guinea_bissau_responses → guinea-bissau-survey app only

---

🔧 Technical Stack

Platform: Heroku (3 separate apps) Framework: FastAPI + Python 3.12 Database: Firebase Firestore Storage: Firebase Storage (voice messages) Messaging: Twilio WhatsApp API AI Models:

• OpenAI Whisper-1 (audio transcription + translation)
• Anthropic Claude Sonnet 4.5 (text translation)

---

📱 Current Deployments

Syria Survey (LIVE):

• App: https://un-gim-survey-bot-fe9d751698ce.herokuapp.com
• Phone: +358454903164
• Version: v46
• Status: ✅ Production ready
• Data: https://un-gim-survey-bot-fe9d751698ce.herokuapp.com/list-survey-data?event_id=syria_survey_2025

Armenia Survey (Pending):

• App: To be created
• Phone: +358454901787 (already purchased)
• Status: 🔜 Ready to configure (~2-3 hours)

Guinea-Bissau Survey (Pending):

• App: To be created
• Phone: To be purchased
• Status: 🔜 Ready to configure (~3-4 hours)

---

🎓 Key Learnings

Why 3 Separate Apps?

1. Different survey structures:

   • Syria: 3 demographics + 6 questions
   • Armenia: 0 demographics + 5 questions
   • Guinea-Bissau: 10 demographics + 8 questions

2. Zero risk:

   • Changes to Armenia won't break Syria
   • Each survey isolated and independent

3. Simpler maintenance:

   • Clear which code controls which survey
   • Easier for future developers/AI agents

4. Faster deployment:

   • No complex conditional logic
   • Straightforward customization

What's Shared:

• Firebase project (different collections)
• Twilio account (different numbers)
• API keys (OpenAI, Anthropic)
• Architecture patterns
• Documentation

---

📖 Documentation Guide

General Documentation (in documentation/):

• System architecture
• Setup guides
• Troubleshooting
• Multi-tenant design patterns

Survey-Specific Documentation (in each survey folder):

• Deployment details
• Template IDs
• Event configuration
• Version history

---

🔗 Essential Links

• Firebase Console: https://console.firebase.google.com/project/yemeni-youth-engagement/firestore
• Twilio Console: https://console.twilio.com
• Heroku Dashboard: https://dashboard.heroku.com/apps/un-gim-survey-bot
• Syria Live Survey: Text +358454903164 on WhatsApp

---

🆘 Support

For Setup Questions:

1. Read documentation/QUICK_START.md
2. Follow documentation/NEW_SURVEY_SETUP_GUIDE.md
3. Check survey-specific README in each folder

For Issues:

1. Check heroku logs --tail in relevant survey folder
2. Review documentation/TROUBLESHOOTING.md
3. Verify Firestore configuration

---

Created: October 20, 2025 Syria Survey: Fully operational ✅ Next Steps: Deploy Armenia & Guinea-Bissau surveys