# vortex-xyz/onyx architecture

> Architecture diagram of the GitHub repository vortex-xyz/onyx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vortex-xyz/onyx
- Repository: https://github.com/vortex-xyz/onyx

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context (C4-ish)
    %% =========================
    U["User (Browser)"]:::external

    subgraph "Onyx Web App (React SPA)"
        direction TB

        subgraph "Bootstrap & Shell"
            direction TB
            HTML["HTML Shell"]:::frontend
            IDX["React Mount / Bootstrap"]:::frontend
            APP["App Composition"]:::frontend
            ROUTES["Routing"]:::frontend
        end

        subgraph "Presentation Layer"
            direction TB
            PAGES["Pages / Screens"]:::frontend
            HOMEUI["Home Feed UI Components"]:::frontend
            SHAREDUI["Shared UI Components"]:::frontend
            UPLOADUI["Upload UI (ImageUpload)"]:::frontend
        end

        subgraph "State & Auth Subsystem"
            direction TB
            AUTHCTX["AuthContext"]:::frontend
            AUTHHOOK["useSupabaseAuth Hook"]:::frontend
            AUTHAPI["Auth API Helpers"]:::frontend
            AUTHCB["AuthCallback Page"]:::frontend
            SUPA_CFG["Supabase Client Config"]:::config
        end

        subgraph "Service Layer"
            direction TB
            APIWRAP["API Facade / Wrapper"]:::service
            POSTSVC["Post Service"]:::service
            FOLLOWSVC["Follow Service"]:::service
            SEARCHSVC["Search Service"]:::service
            POSTQ["Post Queue (Async)"]:::service
            UPLOADSVC["Upload Service"]:::service
            CLOUDINARYSVC["Cloudinary Integration"]:::service
            APPCFG["App/API Config"]:::config
        end

        subgraph "Data Connect Client (Generated)"
            direction TB
            DC_GEN["Generated Data Connect Client SDK"]:::generated
            DC_REACT["Generated Data Connect React SDK"]:::generated
            DC_SCHEMA["GraphQL Schema (Contract)"]:::artifact
            DC_QUERIES["GraphQL Operations (Queries)"]:::artifact
            DC_MUTATIONS["GraphQL Operations (Mutations)"]:::artifact
            DC_CONN["Connector Config"]:::artifact
            DC_PROJ["Data Connect Project Config"]:::artifact
        end
    end

    SUPABASE["Supabase (Auth)"]:::thirdparty
    CLOUDINARY["Cloudinary (Media Storage/Upload API)"]:::thirdparty
    DATACONNECT["Data Connect (GraphQL Service)"]:::thirdparty
    DB[("Backing DB (Managed by Data Connect)")]:::datastore

    %% =========================
    %% System Context Connections
    %% =========================
    U -->|"HTTPS (SPA load)"| HTML
    HTML -->|"loads"| IDX
    IDX -->|"mounts"| APP
    APP -->|"uses"| ROUTES

    ROUTES -->|"renders"| PAGES
    PAGES -->|"composes"| HOMEUI
    PAGES -->|"uses"| SHAREDUI
    PAGES -->|"includes"| UPLOADUI

    %% Auth flow (Login + Callback)
    PAGES -->|"login/start OAuth"| AUTHAPI
    AUTHAPI -->|"OAuth redirect / session token"| SUPABASE
    SUPABASE -->|"redirect callback"| AUTHCB
    AUTHCB -->|"updates session state"| AUTHCTX
    AUTHCTX -->|"listens/refreshes"| AUTHHOOK
    AUTHHOOK -->|"uses client"| SUPA_CFG
    SUPA_CFG -->|"connects"| SUPABASE

    %% Domain services usage
    PAGES -->|"calls"| POSTSVC
    PAGES -->|"calls"| FOLLOWSVC
    PAGES -->|"calls"| SEARCHSVC

    HOMEUI -->|"feed actions"| POSTSVC

    %% API wrapper / config
    POSTSVC -->|"uses"| APIWRAP
    FOLLOWSVC -->|"uses"| APIWRAP
    SEARCHSVC -->|"uses"| APIWRAP
    APIWRAP -->|"reads base URLs/env"| APPCFG

    %% Data Connect access (GraphQL)
    APIWRAP -->|"GraphQL query/mutation"| DC_GEN
    DC_REACT -->|"React hooks around"| DC_GEN
    DC_GEN -->|"GraphQL over HTTPS"| DATACONNECT
    DATACONNECT -->|"reads/writes"| DB

    %% Upload pipeline (Create post with media)
    UPLOADUI -->|"selects media"| UPLOADSVC
    UPLOADSVC -->|"uses"| CLOUDINARYSVC
    CLOUDINARYSVC -->|"HTTP upload (image/video)"| CLOUDINARY
    CLOUDINARY -->|"returns secure_url/public_id"| UPLOADSVC
    UPLOADSVC -->|"returns media URL/metadata"| POSTSVC
    POSTSVC -->|"stores post metadata (caption,tags,Cloudinary URL)"| APIWRAP

    %% Async/queue behavior
    POSTSVC -.->|"enqueue/retry (async)"| POSTQ
    POSTQ -.->|"drains queued mutations"| APIWRAP
    HOMEUI -.->|"shows queue status"| POSTQ

    %% Follow / Search flows
    FOLLOWSVC -->|"GraphQL mutations/queries (follow graph)"| APIWRAP
    SEARCHSVC -->|"GraphQL queries (explore/search)"| APIWRAP

    %% Codegen contract flow (how generated client relates to contracts)
    DC_SCHEMA -->|"drives codegen"| DC_GEN
    DC_QUERIES -->|"drives codegen"| DC_GEN
    DC_MUTATIONS -->|"drives codegen"| DC_GEN
    DC_CONN -->|"configures"| DC_GEN
    DC_PROJ -->|"configures"| DC_GEN

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click HTML "https://github.com/vortex-xyz/onyx/blob/main/onyxf/public/index.html"
    click IDX "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/index.tsx"
    click APP "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/App.tsx"
    click ROUTES "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/routes/index.tsx"

    click PAGES "https://github.com/vortex-xyz/onyx/tree/main/onyxf/src/pages/"
    click HOMEUI "https://github.com/vortex-xyz/onyx/tree/main/onyxf/src/components/home/"
    click SHAREDUI "https://github.com/vortex-xyz/onyx/tree/main/onyxf/src/components/"
    click UPLOADUI "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/components/ImageUpload.tsx"

    click AUTHCTX "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/contexts/AuthContext.tsx"
    click AUTHHOOK "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/hooks/useSupabaseAuth.ts"
    click AUTHAPI "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/api/auth.ts"
    click AUTHCB "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/pages/AuthCallback.tsx"
    click SUPA_CFG "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/config/supabaseClient.ts"

    click APIWRAP "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/services/api.ts"
    click POSTSVC "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/services/postService.ts"
    click FOLLOWSVC "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/services/followService.ts"
    click SEARCHSVC "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/services/searchService.ts"
    click POSTQ "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/services/postQueue.ts"

    click UPLOADSVC "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/services/uploadService.ts"
    click CLOUDINARYSVC "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/services/cloudinary.ts"
    click APPCFG "https://github.com/vortex-xyz/onyx/blob/main/onyxf/src/config/api.ts"

    click DC_SCHEMA "https://github.com/vortex-xyz/onyx/blob/main/onyxf/dataconnect/schema/schema.gql"
    click DC_QUERIES "https://github.com/vortex-xyz/onyx/blob/main/onyxf/dataconnect/connector/queries.gql"
    click DC_MUTATIONS "https://github.com/vortex-xyz/onyx/blob/main/onyxf/dataconnect/connector/mutations.gql"
    click DC_CONN "https://github.com/vortex-xyz/onyx/blob/main/onyxf/dataconnect/connector/connector.yaml"
    click DC_PROJ "https://github.com/vortex-xyz/onyx/blob/main/onyxf/dataconnect/dataconnect.yaml"
    click DC_GEN "https://github.com/vortex-xyz/onyx/tree/main/onyxf/dataconnect-generated/js/default-connector/"
    click DC_REACT "https://github.com/vortex-xyz/onyx/tree/main/onyxf/dataconnect-generated/js/default-connector/react/"

    %% =========================
    %% Styles (Color + Shapes)
    %% =========================
    classDef external fill:#E6EEF9,stroke:#2B4C7E,stroke-width:1.5px,color:#0B1F3A
    classDef frontend fill:#D7EBFF,stroke:#1B66B2,stroke-width:1.5px,color:#0B1F3A
    classDef service fill:#CFE8FF,stroke:#0F5AA6,stroke-width:1.5px,color:#0B1F3A
    classDef config fill:#EAF4FF,stroke:#3A78C2,stroke-width:1.2px,color:#0B1F3A,stroke-dasharray: 4 3
    classDef thirdparty fill:#FFE3C2,stroke:#C46B00,stroke-width:1.6px,color:#3A2200
    classDef datastore fill:#E8D7FF,stroke:#6B3FA0,stroke-width:1.6px,color:#1E0F2E
    classDef generated fill:#DFF7F2,stroke:#14866D,stroke-width:1.5px,color:#05362C
    classDef artifact fill:#F3F4F6,stroke:#6B7280,stroke-width:1.2px,color:#111827,stroke-dasharray: 3 3
```
