Social Mate
Production-grade, AI-powered social platform built with Flutter & Supabase
Overview
Social Mate is a production-grade cross-platform social networking application engineered to deliver the breadth and depth of tier-1 consumer platforms. It brings together 24 self-contained feature modules spanning real-time messaging, multi-party audio/video conferencing, ephemeral stories, short-form video reels, creator sticker packs, and on-device generative AI assistance.
Architected around a Feature-First Clean Architecture paradigm with BLoC/Cubit state management, the application guarantees strict unidirectional data flow and modular boundary isolation. The persistent data layer is backed by Supabase PostgreSQL, leveraging real-time Change Data Capture (CDC) and row-level security (RLS) to synchronize complex social graphs, message streams, and threaded discussions.
Real-time audio and video communications are powered by LiveKit's open WebRTC Selective Forwarding Unit (SFU) architecture, replacing proprietary SDKs with high-efficiency media routing. Complementing this is a pluggable multi-provider AI gateway hot-swapping between Google Gemini, Groq, and OpenRouter, paired with Hive binary offline caching and biometric security.
Social Mate
Production-grade, AI-powered social platform built with Flutter & Supabase
Real-time Messaging & Unified Media Engine
Instant 1-on-1 and group chats with Supabase Realtime, typing indicators, read receipts, professional voice messaging with live waveforms, rich link previews, @mentions, and multi-target message forwarding.
Technical Architecture
A high-level overview of how the system is structured to ensure scalability and maintainability.
Presentation & Reactive State Management
Feature-First Clean Architecture isolating 24 modules with unidirectional BLoC/Cubit state flow and 12-theme dynamic color adaptation.
Realtime Communications & Signaling Layer
Scalable PostgreSQL database utilizing Supabase Realtime Change Data Capture (CDC) over WebSockets with optimistic client reconciliation.
LiveKit WebRTC SFU Audio/Video Engine
Carrier-grade 1-on-1 and group calling utilizing LiveKit SFU, FCM full-screen incoming call intents, flutter_foreground_task, and Picture-in-Picture.
Pluggable Multi-Provider AI Gateway & Hive Offline Tier
Multi-provider AI inference layer with automatic vision detection, accompanied by Hive-backed offline caching with LRU storage eviction.
Engineering Insights
Key technical decisions and challenges encountered during the development process.
Key Decisions
LiveKit WebRTC SFU vs P2P Mesh or Proprietary SDKs
Peer-to-peer WebRTC mesh architectures degrade rapidly in mobile group calling due to N*(N-1) uplink bandwidth saturation, while proprietary SDKs like ZEGOCLOUD introduce vendor lock-in and opaque pricing.
Standardized on LiveKit's open WebRTC Selective Forwarding Unit (SFU) architecture. Clients publish a single upstream track while the SFU intelligently distributes downlinks based on active speaker detection and network conditions. This reduced mobile bandwidth by over 65% in group calls and enabled seamless Picture-in-Picture (PiP) background multitasking.
Pluggable Multi-Provider AI Gateway with Runtime Vision Detection
Relying on a single AI vendor introduces rate limit vulnerabilities, regional latency spikes, and feature constraints when bridging text assistance and multimodal image analysis.
Built an abstraction layer over Gemini, Groq, and OpenRouter. The gateway dynamically inspects the request context: when an image attachment is detected, it automatically routes the payload to Gemini or OpenRouter's vision endpoints; for rapid conversational replies and comment suggestions, it prioritizes Groq for sub-second token delivery.
Supabase Realtime CDC with Optimistic Client-Side Reconciliation
Maintaining instantaneous chat delivery, typing indicators, and deeply nested comment threads across hundreds of concurrent users without excessive polling or race conditions.
Employed Supabase Realtime Change Data Capture (CDC) directly hooked to PostgreSQL table events. The presentation layer applies immediate optimistic UI updates upon user action, then seamlessly reconciles with the authoritative WebSocket broadcast payload, ensuring zero perceivable UI lag.
Feature-First Domain Isolation with Unified Shared Primitives
Organizing a 24-feature social app by technical layers (all models in one folder, all views in another) creates high coupling and makes parallel feature evolution error-prone.
Structured the codebase into self-contained feature slices (`single_chats`, `reels`, `stories`, `stickers`, etc.), each encapsulating its own Cubits, Models, Services, and Views. Reusable infrastructure — such as MediaCacheRepository, AttachmentPicker, and ChatPresenceService — is centralized in `core/` as shared primitives.
Technical Challenges
Reliable Lock-Screen Incoming Call Delivery via FCM Full-Screen Intents
Android's battery-saving Doze modes and background execution limits frequently delay standard notifications and terminate background sockets when an incoming audio/video call arrives.
Configured high-priority FCM data messages coupled with Android Full-Screen Intents and custom notification channels. When an incoming call payload is received, the app immediately raises a full-screen calling activity over the lock screen and initializes `flutter_foreground_task` to prevent the OS from killing the LiveKit signaling socket before the user answers.
Video Controller Lifecycle & Memory Pooling in Reels Feed
Continuous vertical swiping through short-form video reels causes rapid memory accumulation and eventual Out-Of-Memory (OOM) crashes if VideoPlayerControllers are not aggressively managed.
Engineered a pooled video controller manager that maintains active controllers only for the current video and the immediate adjacent videos (index - 1, index + 1) for seamless pre-buffering. Out-of-viewport controllers are aggressively paused and disposed, keeping native video memory within a predictable, bounded ceiling.
Multi-Surface Cache Eviction & Offline Storage Synchronization
Caching rich media (voice notes, thumbnails, high-res photos, sticker packs) for offline browsing quickly exhausts device storage if unbounded.
Implemented an indexed Hive cache with an intelligent Least-Recently-Used (LRU) eviction pipeline. The MediaCacheRepository tracks access frequencies and timestamps, automatically purging non-essential cached media when local storage approaches a configurable limit while keeping textual chat history and user profile metadata intact.
Screens Gallery
A comprehensive look at the user interface and interactions.
Download Social Mate
Install the latest Android build directly to your device. All builds are optimized for performance and security.
Social Mate — ARM64-v8a
Recommended for 95% of modern 64-bit Android devices (Snapdragon, MediaTek, Exynos, Tensor).
minSdk 24 (Android 7.0+) — targetSdk 36. Unknown sources must be enabled.
Other Architectures
Social Mate — ARMv7
For older 32-bit Android devices.
Social Mate — x86_64
For Android Studio emulators, PCs, and x86_64 devices.
Ready to dive deeper?
Explore the source code or see how this architecture translates to other projects in my portfolio.