Context / Problem

The product required a social application available on iOS, Android, and web from a single codebase, with real-time data synchronisation across all clients, multi-provider authentication (Google, Apple, email), regional content partitioning, and a gamification layer with leaderboards and lifecycle tracking. The architecture needed to support complex social graph queries, transactional email workflows, and edge-optimised OAuth, all while maintaining type safety end-to-end from database to UI.

Constraints

• •Three deployment targets (iOS, Android, web) from a single TypeScript codebase. No platform-specific forks.
• •Real-time data synchronisation. Changes must propagate to all connected clients without manual refresh or polling.
• •Multi-provider OAuth (Google, Apple) with custom domain continuity. Users must see the product domain throughout the auth flow, not the backend provider.
• •Regional data partitioning. Content catalogue varies by geography with global and region-specific entries.
• •Rate-limited external APIs (email provider). System must queue, prioritise, and retry without message loss.

Solution Approach

Designed and built a reactive full-stack architecture centred on Convex as the real-time backend, Expo (React Native) as the cross-platform client framework, and Cloudflare edge functions as the OAuth and static hosting layer. The architecture eliminates REST APIs entirely. All client-server communication uses generated TypeScript SDKs with automatic real-time subscriptions. Authentication is handled by Better Auth with a custom Cloudflare Pages Function proxy that rewrites OAuth redirect headers to maintain custom domain continuity.

Architecture

Automation & Integration

• •Real-time reactive subscriptions. Convex database queries automatically subscribe to changes. Client components re-render when underlying data changes. Zero manual cache invalidation, zero polling.
• •Generated TypeScript SDK. Backend functions (queries, mutations, actions) are exposed to the client through a generated, fully-typed SDK. No REST endpoints, no API versioning, no serialisation layer.
• •Edge-optimised OAuth proxy. Cloudflare Pages Function intercepts OAuth callback redirects and rewrites Location headers from the backend domain to the custom domain. Users see the product domain throughout the sign-in flow.
• •Multi-stage lifecycle tracking. Content entries follow a state machine (active → warning → suspended) with configurable grace periods. Cron jobs enforce time-based transitions. Users receive notifications at each stage.
• •Priority email queue. Transactional emails are queued with priority levels, daily/monthly quota enforcement, and exponential backoff retry. Immediate-priority emails bypass the queue; batch emails are aggregated and rate-limited.
• •Regional data partitioning. Content is region-aware with per-region seed data. Queries are scoped by user region with global fallback. Regional community groups enforce content isolation boundaries.

Governance & Controls

• •Identity & access. Multi-provider authentication (Google OAuth, Apple Sign In, email/password, magic link) via Better Auth with custom Convex adapter. Native apps use platform-secure storage (SecureStore); web uses bearer tokens. Every backend function verifies session ownership before data access.
• •Data boundaries. All queries are scoped to the authenticated user. Cross-user operations verify ownership. Community content is isolated from private content. Global search excludes community-scoped data.
• •Soft deletes & audit trail. User data is soft-deleted with deactivation reasons. Removal events are logged to audit tables. No hard deletes of user-generated content.
• •Rate limiting. Email dispatch is quota-controlled (daily and monthly caps). Queue backpressure defers non-critical messages. External API calls retry with exponential backoff.

Security

All communication uses HTTPS/TLS. Native authentication tokens are stored in platform-secure storage (iOS Keychain / Android Keystore via SecureStore). Web authentication uses signed bearer tokens via Authorization headers. OAuth flows are proxied through Cloudflare edge functions with header rewriting to prevent backend domain exposure. Database access is gated by session-verified functions. No direct client-to-database access. Email sending uses API-key-authenticated SMTP with queue-based rate limiting. Cloudflare provides SSL termination, DDoS protection, and DNS management.

AI-Assisted Engineering

AI tooling was used during the build phase to accelerate schema design, assist with complex Convex query optimisation, and generate seed data for regional content catalogues. Database migration scripts and email template generation were AI-assisted with manual review. All AI-generated code was validated through manual testing and Convex's type-safe compilation pipeline. AI did not make architectural decisions. It accelerated implementation of decisions already made.

Delivery Notes

• •Delivered as a complete cross-platform system: iOS app, Android app, web application, real-time backend, email infrastructure, and edge authentication proxy.
• •24-table database schema with indexing strategy, full-text search, and migration framework.
• •Over-the-air update capability (Expo Updates) for rapid iteration without app store review cycles.
• •Production deployment across Convex (backend), Cloudflare Pages (web + edge functions), and app stores (iOS/Android).

Outcomes

• •Single TypeScript codebase serving three platforms (iOS, Android, web) with approximately 80% code sharing.
• •Zero-latency data synchronisation across all connected clients via reactive subscriptions. No manual refresh required.
• •Custom domain OAuth flow maintaining brand continuity across Google and Apple sign-in providers.
• •Type-safe data pipeline from database schema through backend functions to client components. Compile-time guarantees across the full stack.
• •Regional data architecture supporting multi-geography content catalogues with isolated community boundaries.

Extensibility / Next Steps

Architecture supports horizontal feature addition through new Convex functions and schema extensions. Real-time subscription model scales with additional data types without infrastructure changes. Regional partitioning can expand to new geographies by adding seed data. Email queue pattern is reusable for push notification channels. Authentication layer supports adding new OAuth providers through Better Auth plugin configuration.