# zetorai/sprig architecture

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

- Interactive diagram: https://gitdiagram.com/zetorai/sprig
- Repository: https://github.com/zetorai/sprig

## Overview

1. **Repo shape: a mobile-first product with a Supabase backend**
   - This is a monorepo centered on `apps/mobile`, a React Native + Expo app, with `supabase/` providing the backend schema, auth, storage, and server-side functions.
   - `packages/shared` holds cross-cutting types/constants so the mobile app and backend stay aligned.

2. **Client entry and app shell**
   - The mobile app boots through `apps/mobile/index.ts` and `App.tsx`.
   - Global app concerns are assembled in `src/providers` and `src/navigation`: auth state, query/cache setup, theme, and screen routing.

3. **Feature-oriented mobile structure**
   - Most UI is organized by domain under `src/features/`: auth, onboarding, feed, editor, profile, search, and settings.
   - This suggests a vertical-slice architecture where each feature owns its screens and local logic rather than a single large shared app layer.

4. **Shared UI and local interaction logic**
   - Reusable visual pieces live in `src/components` such as buttons, inputs, avatar, meme card/canvas, and error boundary.
   - Feature-specific behavior is split into hooks and helper modules like `useFeed`, `useEngagement`, `useMemeCardActions`, `useOnboarding`, and `reactionLogic`, which keeps screens thin and delegates state/business logic downward.

5. **Client-side data access layer**
   - `src/lib/api/*` is the app’s backend boundary: separate modules for feed, memes, comments, likes, reactions, lineage, profile, search, reports, uploads, templates, GDPR, and social/stoks-related access.
   - `src/lib/supabase.ts` is the core client connector, while `queryClient.ts` indicates cached request orchestration on the app side.
   - This split implies screens call feature hooks, hooks call API wrappers, and those wrappers are the only layer that talks directly to Supabase or functions.

6. **Core product flow: create, remix, and lineage**
   - The editor screens and `MemeCanvas` are the center of the product loop: a user starts from a template or an existing meme, edits locally, then persists a new post.
   - `lineage` support is a first-class concern, not an afterthought: each remix keeps a parent/child relationship so the app can render “remixed from” and tree-like browsing later.
   - The `feed` and `meme detail` surfaces consume that lineage data to show the origin and branching history of a meme.

7. **Media pipeline and storage**
   - Media handling is split between client-side rendering/capture and server storage.
   - The README indicates `react-native-skia` / `react-native-view-shot` for rendering the meme image on device, then `uploads` routes push the generated asset to Supabase Storage.
   - Supabase Storage, plus CDN delivery, is the durable media boundary for the app’s image-heavy content.

8. **Social/feed pipeline**
   - `feed`, `likes`, `comments`, `reactions`, `reports`, and `engagement` form the interaction graph around each meme.
   - `useFeed` and `useEngagement` suggest the feed is a data-driven surface with optimistic updates or cached interactions, while `MemeCard` and `MemeDetailScreen` are the primary presentation points.
   - `search` and `profile` are secondary read paths over the same underlying social objects.

9. **Backend: Supabase as the system of record**
   - `supabase/migrations` contains the actual schema evolution and policy layer, including initialization, feed ranking, storage, v2 social features, signup profile behavior, and direct posting.
   - This means Postgres is the authoritative store for users, memes, relationships, engagement, and moderation state, with RLS likely controlling access at the table boundary.
   - `supabase/seed.sql` supports local development and reproducible test data.

10. **Server-side functions for trust and moderation**
   - `supabase/functions` includes `moderate-meme` and `delete-account`, which are the main backend execution points beyond raw database access.
   - Moderation is explicitly separated from the client, matching the README’s safety model: automated checks and sensitive actions are kept in Edge Functions with secrets stored server-side.
   - Account deletion is also centralized, which is important for GDPR/privacy workflows and for safely cascading deletes across related records and storage.

11. **Cross-cutting concerns**
   - `observability.ts`, `share.ts`, `time.ts`, `media.ts`, and `env.ts` are utility boundaries used across features.
   - The app also has dedicated settings/privacy/help/about screens, which indicates user-facing policy and support flows are part of the product architecture, not just UI polish.

12. **Quality and delivery**
   - Tests exist for utility and feed logic (`src/lib/__tests__`, `src/features/feed/__tests__`), so some business rules are intended to be validated outside the UI.
   - `.github/workflows/ci.yml` plus TypeScript/lint/test scripts show the repo is set up for automated validation before deployment.

13. **How to diagram it**
   - A good architecture diagram would place the mobile app on the left, split into feature modules and shared UI.
   - In the center, show the client data layer talking to Supabase Auth/Postgres/Storage and to Edge Functions for moderation and destructive actions.
   - On the right, show storage/CDN for media and the database as the source of truth, with lineage, feed ranking, reactions, comments, profiles, and reports all modeled as database-backed social data.

Main entry points: [`apps/mobile/src/navigation/index.tsx`](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/navigation/index.tsx) (Navigation), [`apps/mobile/src/lib/api/feed.ts`](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/lib/api/feed.ts) (API layer), [`supabase/migrations/20260622000000_init.sql`](https://github.com/zetorai/sprig/blob/main/supabase/migrations/20260622000000_init.sql) (Schema), [`apps/mobile/App.tsx`](https://github.com/zetorai/sprig/blob/main/apps/mobile/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_entry["App shell<br/>expo entry<br/>[App.tsx]"]
  node_bootstrap["Native entry<br/>expo entry<br/>[index.ts]"]
  node_providers["Providers<br/>app context<br/>[AuthProvider.tsx]"]
  node_nav["Navigation<br/>router<br/>[index.tsx]"]
  node_ui["UI kit<br/>shared components<br/>[MemeCard.tsx]"]
  node_auth["Auth<br/>feature<br/>[SignInScreen.tsx]"]
  node_onboarding["Onboarding<br/>feature"]
  node_editor["Editor<br/>feature<br/>[EditorScreen.tsx]"]
  node_feed["Feed<br/>feature<br/>[FeedScreen.tsx]"]
  node_profile["Profile<br/>feature<br/>[ProfileScreen.tsx]"]
  node_search["Search<br/>feature<br/>[SearchScreen.tsx]"]
  node_settings["Settings<br/>feature<br/>[SettingsScreen.tsx]"]
  node_feedhooks["Feed logic<br/>feature hooks<br/>[useFeed.ts]"]
  node_editorhooks["Editor logic<br/>feature hooks<br/>[CreateScreen.tsx]"]
  node_api["API layer<br/>client boundary<br/>[feed.ts]"]
  node_client["Supabase client<br/>client connector<br/>[supabase.ts]"]
end

subgraph group_shared["Shared package"]
  node_sharedpkg["Shared types<br/>monorepo pkg<br/>[index.ts]"]
end

subgraph group_backend["Supabase backend"]
  node_schema[("Schema<br/>postgres migrations")]
  node_functions{{"Edge functions<br/>serverless<br/>[index.ts]"}}
end

subgraph group_delivery["Delivery"]
  node_deliveryci["CI<br/>workflow<br/>[ci.yml]"]
end

node_bootstrap -->|"starts"| node_entry
node_entry -->|"wraps"| node_providers
node_entry -->|"renders"| node_nav
node_providers -->|"supplies state"| node_nav
node_nav -->|"routes to"| node_auth
node_nav -->|"routes to"| node_onboarding
node_nav -->|"routes to"| node_editor
node_nav -->|"routes to"| node_feed
node_nav -->|"routes to"| node_profile
node_nav -->|"routes to"| node_search
node_nav -->|"routes to"| node_settings
node_feed -->|"uses"| node_feedhooks
node_editor -->|"uses"| node_editorhooks
node_feed -->|"uses"| node_ui
node_editor -->|"uses"| node_ui
node_auth -->|"uses"| node_ui
node_feedhooks -->|"calls"| node_api
node_editorhooks -->|"calls"| node_api
node_profile -->|"reads via"| node_api
node_search -->|"reads via"| node_api
node_api -->|"uses"| node_client
node_api -->|"targets"| node_schema
node_api -->|"invokes"| node_functions
node_schema -->|"governs"| node_functions
node_sharedpkg -->|"aligns"| node_api
node_sharedpkg -->|"aligns"| node_schema
node_functions -->|"updates"| node_schema
node_deliveryci -.->|"validates"| node_entry
node_deliveryci -.->|"validates"| node_schema

click node_entry "https://github.com/zetorai/sprig/blob/main/apps/mobile/App.tsx"
click node_bootstrap "https://github.com/zetorai/sprig/blob/main/apps/mobile/index.ts"
click node_providers "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/providers/AuthProvider.tsx"
click node_nav "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/navigation/index.tsx"
click node_ui "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/components/MemeCard.tsx"
click node_auth "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/auth/SignInScreen.tsx"
click node_onboarding "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/onboarding/OnboardingScreen.tsx"
click node_editor "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/editor/EditorScreen.tsx"
click node_feed "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/feed/FeedScreen.tsx"
click node_profile "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/profile/ProfileScreen.tsx"
click node_search "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/search/SearchScreen.tsx"
click node_settings "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/settings/SettingsScreen.tsx"
click node_feedhooks "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/feed/useFeed.ts"
click node_editorhooks "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/editor/CreateScreen.tsx"
click node_api "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/lib/api/feed.ts"
click node_client "https://github.com/zetorai/sprig/blob/main/apps/mobile/src/lib/supabase.ts"
click node_sharedpkg "https://github.com/zetorai/sprig/blob/main/packages/shared/src/index.ts"
click node_schema "https://github.com/zetorai/sprig/blob/main/supabase/migrations/20260622000000_init.sql"
click node_functions "https://github.com/zetorai/sprig/blob/main/supabase/functions/moderate-meme/index.ts"
click node_deliveryci "https://github.com/zetorai/sprig/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_bootstrap,node_providers,node_nav,node_ui,node_auth,node_onboarding,node_editor,node_feed,node_profile,node_search,node_settings,node_feedhooks,node_editorhooks,node_api,node_client toneBlue
class node_sharedpkg toneAmber
class node_schema,node_functions toneMint
class node_deliveryci toneRose
```

## Components

### Mobile app

React Native + Expo client and feature slices

- [App shell](https://github.com/zetorai/sprig/blob/main/apps/mobile/App.tsx): expo entry · Mobile app bootstrap and root component · `apps/mobile/App.tsx`
- [Native entry](https://github.com/zetorai/sprig/blob/main/apps/mobile/index.ts): expo entry · Native startup entrypoint · `apps/mobile/index.ts`
- [Providers](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/providers/AuthProvider.tsx): app context · Auth, cache, and global app state providers · `apps/mobile/src/providers/AuthProvider.tsx`
- [Navigation](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/navigation/index.tsx): router · Screen routing and navigation types · `apps/mobile/src/navigation/index.tsx`
- [UI kit](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/components/MemeCard.tsx): shared components · Reusable visual components and canvas rendering · `apps/mobile/src/components/MemeCard.tsx`
- [Auth](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/auth/SignInScreen.tsx): feature · Sign-in and authentication surface · `apps/mobile/src/features/auth/SignInScreen.tsx`
- [Onboarding](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/onboarding/OnboardingScreen.tsx): feature · First-run setup and profile completion flow · `apps/mobile/src/features/onboarding/OnboardingScreen.tsx`
- [Editor](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/editor/EditorScreen.tsx): feature · Create and edit meme posts · `apps/mobile/src/features/editor/EditorScreen.tsx`
- [Feed](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/feed/FeedScreen.tsx): feature · Feed, detail, and lineage browsing · `apps/mobile/src/features/feed/FeedScreen.tsx`
- [Profile](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/profile/ProfileScreen.tsx): feature · User profile surface · `apps/mobile/src/features/profile/ProfileScreen.tsx`
- [Search](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/search/SearchScreen.tsx): feature · Discovery and lookup surface · `apps/mobile/src/features/search/SearchScreen.tsx`
- [Settings](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/settings/SettingsScreen.tsx): feature · Account, privacy, help, and app settings · `apps/mobile/src/features/settings/SettingsScreen.tsx`
- [Feed logic](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/feed/useFeed.ts): feature hooks · Feed data and engagement hooks · `apps/mobile/src/features/feed/useFeed.ts`
- [Editor logic](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/features/editor/CreateScreen.tsx): feature hooks · Editor and onboarding behavior hooks · `apps/mobile/src/features/editor/CreateScreen.tsx`
- [API layer](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/lib/api/feed.ts): client boundary · Backend-facing client modules for data access · `apps/mobile/src/lib/api/feed.ts`
- [Supabase client](https://github.com/zetorai/sprig/blob/main/apps/mobile/src/lib/supabase.ts): client connector · Supabase client and cached request orchestration · `apps/mobile/src/lib/supabase.ts`

### Shared package

Cross-cutting types and constants shared by client and backend

- [Shared types](https://github.com/zetorai/sprig/blob/main/packages/shared/src/index.ts): monorepo pkg · Cross-cutting types and constants · `packages/shared/src/index.ts`

### Supabase backend

Database schema, storage, and edge functions

- [Schema](https://github.com/zetorai/sprig/blob/main/supabase/migrations/20260622000000_init.sql): postgres migrations · Database schema, policies, and ranking logic · `supabase/migrations/20260622000000_init.sql`
- [Edge functions](https://github.com/zetorai/sprig/blob/main/supabase/functions/moderate-meme/index.ts): serverless · Moderation and account deletion functions · `supabase/functions/moderate-meme/index.ts`

### Delivery

CI and automated validation

- [CI](https://github.com/zetorai/sprig/blob/main/.github/workflows/ci.yml): workflow · Automated validation and checks · `.github/workflows/ci.yml`

## Connections

- Native entry → App shell: starts · Native bootstrap launches the app shell
- App shell → Providers: wraps · Root component assembles global providers
- App shell → Navigation: renders · App shell mounts navigation
- Providers → Navigation: supplies state · Auth and cache context feed routing and screens
- Navigation → Auth: routes to · Navigation exposes auth screen
- Navigation → Onboarding: routes to · Navigation exposes onboarding flow
- Navigation → Editor: routes to · Navigation exposes editor flow
- Navigation → Feed: routes to · Navigation exposes feed and detail views
- Navigation → Profile: routes to · Navigation exposes profile view
- Navigation → Search: routes to · Navigation exposes search view
- Navigation → Settings: routes to · Navigation exposes settings views
- Feed → Feed logic: uses · Feed screens depend on feed and engagement hooks
- Editor → Editor logic: uses · Editor and onboarding screens use local behavior hooks
- Feed → UI kit: uses · Feed surfaces reuse shared cards and avatar pieces
- Editor → UI kit: uses · Editor uses shared canvas and form components
- Auth → UI kit: uses · Auth screen reuses shared inputs and hero UI
- Feed logic → API layer: calls · Feed logic fetches and mutates through API wrappers
- Editor logic → API layer: calls · Editor and onboarding logic persist through API wrappers
- Profile → API layer: reads via · Profile screen consumes backend data through API modules
- Search → API layer: reads via · Search screen queries backend data through API modules
- API layer → Supabase client: uses · API modules use the shared Supabase client
- API layer → Schema: targets · Client data access reads and writes the Postgres schema
- API layer → Edge functions: invokes · Sensitive actions and moderation go through edge functions
- Schema → Edge functions: governs · Functions operate over the database-backed system of record
- Shared types → API layer: aligns · Shared types keep client payloads consistent
- Shared types → Schema: aligns · Shared constants and types mirror backend entities
- Edge functions → Schema: updates · Moderation and account deletion mutate persisted records
- CI → App shell: validates · CI covers the mobile app build and checks
- CI → Schema: validates · CI also validates backend migrations and functions