Mobile App Integration
Integration guide for adding Phenom Chat to the React Native mobile app, covering both Matrix/Synapse and Hasura Lite implementations.
Chat System
Phenom real-time chat system with dual-implementation A/B testing, shared Cognito auth, and MCP tools for AI agents.
Categories:
The Phenom Chat System is currently in testing at chat-testing.thephenom.app. It runs a dual-implementation architecture for A/B evaluation before selecting the production backend.
Overview
The Phenom Chat System provides real-time messaging within the PhenomApp mobile application. The system is designed with a dual-implementation architecture that allows A/B testing between two backend approaches:
- Implementation A (Matrix/Synapse) – a standards-based Matrix homeserver providing federated messaging capabilities with full E2EE support.
- Implementation B (Hasura Lite) – a lightweight GraphQL-native backend built on top of the existing Hasura GraphQL Engine and PostgreSQL database.
Both implementations share:
- AWS Cognito authentication – users authenticate once and their identity works across both backends.
- MCP Tool Server – AI agents interact with chat through 9 standardized MCP tools, regardless of which backend is active.
- Three chat rooms – Internal (team), Partners (collaborators), and Community (mobile app users).
- Link preview resolution – Phenom content links are automatically enriched with preview cards.
Architecture
graph TB
subgraph "Mobile App"
RN["React Native Client
(expo-web-browser for SSO)"] end subgraph "Cloudflare" CF["DNS: chat-testing.thephenom.app
CNAME → ALB"] end subgraph "AWS — Public Tier" ALB["Application Load Balancer
HTTPS termination
Path-based routing"] end subgraph "AWS — Private Tier (ECS Fargate)" SYN["Synapse Homeserver
Implementation A
Port 8008 · 512 CPU · 1024 MiB"] ADMIN["Synapse Admin UI
Port 80 · 256 CPU · 512 MiB"] MCP["Chat MCP Server
9 tools · Port 3001
256 CPU · 512 MiB"] end subgraph "AWS — Data Tier" RDS["RDS PostgreSQL 17.4
Synapse DB + Chat tables"] SM["Secrets Manager
Homeserver config · DB creds
Client secrets"] end subgraph "AWS — Serverless" LP["Link Preview Lambda
Node.js 18.x · 256 MiB"] UP["User Provisioner Lambda
Cognito post-auth trigger"] COG["Cognito User Pool
OIDC for Synapse
Agent client for MCP"] end RN -->|HTTPS| CF CF --> ALB ALB -->|"/_matrix/* /_synapse/*"| SYN ALB -->|"/chat-admin/*"| ADMIN ALB -->|"/mcp/*"| MCP MCP -->|"BACKEND_TYPE=hasura"| RDS MCP -->|"BACKEND_TYPE=synapse"| SYN SYN --> RDS LP --> RDS COG -->|"Post-auth trigger"| UP UP -->|"Provision user"| RDS SYN -.->|"OIDC auth"| COG RN -.->|"SSO login"| COG MCP -.->|"Read secrets"| SM style ALB fill:#d73429,color:#fff,rx:30 style RDS fill:#1a1a1a,color:#fff,rx:30 style COG fill:#151515,color:#e0e0e0,rx:30 style MCP fill:#121010,color:#a5e3e8,rx:30
(expo-web-browser for SSO)"] end subgraph "Cloudflare" CF["DNS: chat-testing.thephenom.app
CNAME → ALB"] end subgraph "AWS — Public Tier" ALB["Application Load Balancer
HTTPS termination
Path-based routing"] end subgraph "AWS — Private Tier (ECS Fargate)" SYN["Synapse Homeserver
Implementation A
Port 8008 · 512 CPU · 1024 MiB"] ADMIN["Synapse Admin UI
Port 80 · 256 CPU · 512 MiB"] MCP["Chat MCP Server
9 tools · Port 3001
256 CPU · 512 MiB"] end subgraph "AWS — Data Tier" RDS["RDS PostgreSQL 17.4
Synapse DB + Chat tables"] SM["Secrets Manager
Homeserver config · DB creds
Client secrets"] end subgraph "AWS — Serverless" LP["Link Preview Lambda
Node.js 18.x · 256 MiB"] UP["User Provisioner Lambda
Cognito post-auth trigger"] COG["Cognito User Pool
OIDC for Synapse
Agent client for MCP"] end RN -->|HTTPS| CF CF --> ALB ALB -->|"/_matrix/* /_synapse/*"| SYN ALB -->|"/chat-admin/*"| ADMIN ALB -->|"/mcp/*"| MCP MCP -->|"BACKEND_TYPE=hasura"| RDS MCP -->|"BACKEND_TYPE=synapse"| SYN SYN --> RDS LP --> RDS COG -->|"Post-auth trigger"| UP UP -->|"Provision user"| RDS SYN -.->|"OIDC auth"| COG RN -.->|"SSO login"| COG MCP -.->|"Read secrets"| SM style ALB fill:#d73429,color:#fff,rx:30 style RDS fill:#1a1a1a,color:#fff,rx:30 style COG fill:#151515,color:#e0e0e0,rx:30 style MCP fill:#121010,color:#a5e3e8,rx:30
Documentation
| Page | Description |
|---|---|
| Mobile Integration | Integration guide for the React Native mobile app (for Jon) |
| Architecture | Deep-dive into system design, database schema, and sequence diagrams |
| API Reference | Complete API docs for Hasura GraphQL, MCP tools, and Matrix endpoints |
| Admin & Operations | Moderation, monitoring, troubleshooting, and emergency procedures |
| Deployment | Terraform modules, Docker builds, DNS, and post-deploy configuration |
Current Status
| Aspect | Status |
|---|---|
| Testing endpoint | https://chat-testing.thephenom.app |
| Implementation A (Synapse) | Deployed and running |
| Implementation B (Hasura Lite) | Schema deployed, Hasura metadata configured |
| MCP Server | Active, serving 9 tools |
| Mobile integration | In progress |
| Production deployment | Pending A/B test results |
Repository
GitHub Repository: Phenom-earth/phenom-infra (chat modules under modules/chat-*)
Chat Architecture
Deep dive into the Phenom Chat system architecture, including component design, database schema, sequence diagrams, and security model.
Chat API Reference
Complete API documentation for the Phenom Chat system, covering Hasura Lite GraphQL, MCP tools, and Matrix/Synapse endpoints.
Admin & Operations
Day-to-day administration, moderation, monitoring, troubleshooting, and emergency procedures for the Phenom Chat system.
Deployment Guide
Terraform deployment procedures, Docker image builds, DNS configuration, and post-deployment setup for the Phenom Chat system.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.