How vortex-xyz/onyx works
Project type & purpose (from tree + README)
This repo is (primarily) a TypeScript React SPA (Create React App-style structure: public/index.html, src/index.tsx, src/react-app-env.d.ts, reportWebVitals, setupTests) with:
• UI/pages/components for a social/content-style app (Home feed, Explore, Gallery, Profile, Settings, Chats, Create Post).
• Authentication via Supabase (src/config/supabaseClient.ts, src/contexts/AuthContext.tsx, src/hooks/useSupabaseAuth.ts, src/api/auth.ts, pages/AuthCallback.tsx).
• Media upload via Cloudinary (src/services/cloudinary.ts, uploadService.ts, components/ImageUpload.tsx).
• A GraphQL “Data Connect” layer (dataconnect/… plus dataconnect-generated/js/default-connector/...) which strongly suggests: *generated client SDK* → *Data Connect service* → *backing datastore*.
• App-level domain services: postService, followService, searchService, postQueue (indicating feed creation, following graph, search, and queued/background-ish post processing on the client or via an API).
How to break down the architecture from the file structure (what to include)
Use the tree to derive *containers* and *components*:
Bootstrap & Shell
• src/index.tsx (app boot)
• src/App.tsx (top-level composition)
• src/routes/index.tsx (routing)
• public/index.html (entry)
Routing / Pages (user-visible screens)
• src/pages/* (Landing, Home, Explore, Gallery, Chats, CreatePost, Profile, Settings, Login, AuthCallback, ProfileSetup, CTA)
UI Component Library (reusable UI)
• src/components/* and src/components/home/*
• Feed composition is especially rich: PostCard, PostHeader, PostContent, PostMedia, PostComments, PostActions, etc.
• Navigation: Navigation, TopNav, Sidebar, MobileBottomNav
• Cross-cutting UI: ToastProvider
State / Auth / Context
• src/contexts/AuthContext.tsx
• src/hooks/useSupabaseAuth.ts
Service Layer (how the UI talks to the outside world)
• src/services/api.ts (often a wrapper/facade)
• src/services/postService.ts, followService.ts, searchService.ts
• src/services/uploadService.ts + cloudinary.ts
• src/services/postQueue.ts (important: implies asynchronous/queued flow)
Configuration
• src/config/supabaseClient.ts (external auth provider client)
• src/config/api.ts (base URLs / env wiring)
Supabase
• Auth (definite)
Cloudinary
• Asset storage + upload endpoint (explicit in cloudinary.ts).
Data Connect GraphQL
• dataconnect/schema/schema.gql
• dataconnect/connector/queries.gql, mutations.gql
• dataconnect-generated/js/default-connector/* (generated client SDK, incl. React flavor)
Flow A: Login / Auth callback
• LoginPage → Supabase Auth (hosted UI/OAuth)
• Redirect → pages/AuthCallback.tsx
• AuthCallback updates AuthContext / session state
• App routes unlock authenticated pages (Home/CreatePost/Profile)
Flow B: Home feed loading
• HomePage / home components (PostCard, QueueStatus, etc.)
• → postService (and maybe searchService/filters)
• → Data Connect GraphQL query (queries.gql via generated client)
• ← returns posts + metadata
• UI renders feed
Flow C: Create post with image upload (most architecturally important)
• CreatePostPage / CreatePostModal / ImageUpload
• → uploadService
• → Cloudinary upload
• ← Cloudinary returns secure_url/public id
• → postService mutation (Data Connect mutations.gql) storing post + media URL
• Optionally:
• postQueue shows local queued status / retry (if used)
Flow D: Follow / social graph
• Profile UI (ProfilePage, ProfileMenu)
• → followService
• → Data Connect mutations/queries
Flow E: Search/Explore
• ExplorePage
• → searchService
• → Data Connect query (or API wrapper)
Notable architectural patterns to call out (based on structure)
• SPA with layered separation:
• UI (pages/components) is distinct from services and config.
• Context + hooks for auth state:
• AuthContext + useSupabaseAuth is your “auth subsystem”.
• Generated API client:
• dataconnect-generated indicates contract-first GraphQL and codegen. Show it explicitly as it changes how people extend the system (update .gql / schema → regenerate client).
• Externalized media pipeline:
• Uploads go to Cloudinary; app stores references (URLs) elsewhere.