Seenly

🏛️ Seenly Social — Architecture Specification


This document details the high-level architecture, module decomposition, and data pipelines powering Seenly Social.
---

1. High-Level System Architecture


Seenly employs a decoupled, privacy-first client-server model: - Client Layer: Single Page Application (SPA) built on React 18, Vite 6, and Tailwind CSS. Packaged as a Progressive Web App (PWA) and native Android application via Capacitor 8. - Relay & Backend Layer: Express.js and Go WebSocket relay servers providing zero-knowledge transit for encrypted communication. - Database & Storage Layer: Cloudflare R2 object storage for media CDN, Appwrite for identity & session synchronization, and MongoDB for public indexing.
``` ┌────────────────────────────────────────────────────────────────────────┐ │ SEENLY CLIENT (REACT 18) │ ├─────────────────┬──────────────────┬─────────────────┬─────────────────┤ │ Home & Trending│ Clips Viewer │ E2EE Chat │ Creator Profile│ ├─────────────────┴──────────────────┴─────────────────┴─────────────────┤ │ WebCrypto Security Engine (ECDH) │ ├────────────────────────────────────────────────────────────────────────┤ │ Appwrite & Socket.IO Client │ └──────────────────────────────────┬─────────────────────────────────────┘ │ HTTPS / WSS ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ SEENLY ZERO-KNOWLEDGE RELAY SERVER │ ├──────────────────────────────────┬─────────────────────────────────────┤ │ Zero-Plaintext Message Relay │ Trending Velocity Calculator │ └─────────────────┬────────────────┴──────────────────┬──────────────────┘ │ │ ▼ ▼ ┌───────────────────┐ ┌───────────────────┐ │ Cloudflare R2 │ │ Database Layer │ │ (Fast Media CDN) │ │(Appwrite / Mongo) │ └───────────────────┘ └───────────────────┘ ```
---

2. Core Subsystems


2.1 Trending Clips Engine (24-Hour Velocity)

Trending Clips are calculated dynamically on the server and client using real-time engagement velocity:
$\text{Trending Score} = \frac{(\text{views} \times 1.0) + (\text{likes} \times 2.5) + (\text{comments} \times 3.5) + (\text{shares} \times 5.0)}{(\text{hoursSinceUpload} + 2)^{1.5}}$
- Dynamic Lifespan: Each clip is assigned a `trending_started_at` and `trending_expires_at` (24-hour duration). - No Stories: Ephemeral status updates are deprecated. Ephemeral discovery is powered strictly by trending public Clips.

2.2 End-to-End Encryption (E2EE) Messaging Subsystem

- Key Negotiation: ECDH over curve P-256 via browser `window.crypto.subtle`. - Cipher Suite: AES-GCM with 256-bit key length and unique 12-byte initialization vectors (IV) per message. - Clip Sharing Reference: Clips shared within chats are passed as referenced metadata payloads (`[SHARED_POST:{"id":"..."}]`), eliminating video duplication.

2.3 Media Delivery & Preloading

- Video assets are stored on Cloudflare R2 and distributed over a global edge CDN. - Multi-tier preloading: - Active Clip: 100% full stream buffering with hardware decode. - Next 2 Clips: Metadata and first 3 seconds buffer preload.
---

3. Directory Layout


``` seenly-social/ ├── android/ # Native Android Capacitor workspace ├── public/ # Public assets, sitemap.xml, robots.txt ├── server/ # Express & Node.js backend relay ├── src/ │ ├── assets/ # Brand SVG & HD PNG assets │ ├── components/ # UI components & Views │ │ ├── PixelPerfectSocialApp.jsx # Main App layout & tab router │ │ ├── ReelsViewer.jsx # Vertical video clips viewer │ │ ├── ChatMessenger.jsx # E2EE chat & clip sharing │ │ ├── ProfileDashboard.jsx # Creator profile & grid │ │ ├── SeenlyCreateStudio.jsx # Clip recording & creation │ │ ├── FirebaseLogin.jsx # Authentication module │ │ └── cryptoHelper.js # WebCrypto E2EE library │ ├── hooks/ # Custom React hooks (native, network) │ ├── store/ # Zustand state management │ └── utils/ # Appwrite client, analytics, media resolvers ```