# uopsdod/claude_code_toy_marketplace architecture

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

- Interactive diagram: https://gitdiagram.com/uopsdod/claude_code_toy_marketplace
- Repository: https://github.com/uopsdod/claude_code_toy_marketplace

## Overview

1. **Repository shape**
   - This is a **client-side React application** built with **Vite + TypeScript**.
   - The only backend/runtime dependency shown in the repo is **Supabase**, which acts as the app’s auth, database, and likely realtime layer.

2. **Top-level architecture**
   - The code splits cleanly into:
     - **`src/pages`**: route-level screens
     - **`src/components`**: reusable UI and domain components
     - **`src/hooks`**: data-fetching and state hooks
     - **`src/contexts`**: app-wide providers
     - **`src/integrations/supabase`**: backend client and generated types
     - **`supabase/`**: database migrations, seed data, and config
   - This suggests a **frontend-first marketplace** with Supabase providing the application backend.

3. **Route/page layer**
   - The main user flows live in pages like:
     - marketplace browsing: `Index`, `Categories`, `ProductDetail`
     - selling/listing creation: `CreateListing`, `CreateListingForm`
     - account/auth: `Auth`, `Profile`
     - saved items: `SavedItems`
     - messaging: `ConversationList`, `ConversationDetail`
     - static/info: `About`
     - fallback: `NotFound`
   - These pages are the main integration points for data hooks and shared UI.

4. **Domain areas**
   - The app appears to be a **toy marketplace** with at least four core domains:
     - **Listings/products**: browse, view detail, create listings
     - **Authentication/user profile**
     - **Saved/favorited products**
     - **Messaging/conversations**
   - The presence of conversations and unread count hooks implies the marketplace is not just catalog browsing; it supports direct buyer/seller communication.

5. **Data access layer**
   - Data is not fetched directly from pages in an ad hoc way; instead, the app uses custom hooks:
     - `useAuth`
     - `usePublicProducts`
     - `useUserProducts`
     - `useSavedProducts`
     - `useUserSavedProducts`
     - `useUnreadMessagesCount`
   - This creates a clear boundary: **pages consume hooks; hooks encapsulate Supabase queries and reactive state**.

6. **Supabase integration boundary**
   - `src/integrations/supabase/client.ts` is the application’s backend client entry point.
   - `src/integrations/supabase/types.ts` indicates **generated database types**, so the frontend is typed against the Supabase schema.
   - The `supabase/migrations` directory shows schema evolution is managed as code, including RPC functions for saved products and location-aware saved product retrieval.

7. **Backend-owned business logic**
   - The migration files show some behavior lives in the database rather than the UI:
     - `add_saved_products_rpc_functions.sql`
     - `update_get_user_saved_products_include_location.sql`
   - That suggests saved-item retrieval and possibly related joins/filters are handled through **Supabase SQL/RPC**, not just plain table reads.

8. **Auth and session flow**
   - `Auth.tsx` is backed by dedicated forms:
     - `SignInForm`
     - `SignUpForm`
     - `ResetPasswordForm`
   - `useAuth` likely centralizes session state and user identity, which then gates authenticated pages such as listing creation, profile, saved items, and conversations.

9. **Messaging and realtime-like state**
   - The presence of `PresenceProvider` in `src/contexts` and `useUnreadMessagesCount` suggests the app has some **live or semi-live communication state**.
   - Conversations are modeled as their own feature area, separate from product browsing, which is important for architecture diagrams: messaging is a distinct subsystem that depends on auth and user identity.

10. **Shared UI layer**
   - `src/components/ui` contains a large set of reusable primitives typical of a **shadcn/ui + Radix-based design system**.
   - These components are not business logic; they form the presentation foundation used across pages and feature components.

11. **Feature-specific components**
   - Higher-level components like `ProductCard`, `PublicProductCard`, `NavigationBar`, `HamburgerMenu`, and `FilterSheet` bridge the UI primitives and the marketplace domain.
   - `PublicProductCard` versus `ProductCard` suggests separate rendering for anonymous/public browsing vs authenticated/user-specific views.

12. **Image and utility layer**
   - `src/lib/imageUtils.ts` likely handles image formatting, selection, or URL manipulation for listings.
   - `src/lib/utils.ts` and `src/hooks/use-mobile.tsx` support cross-cutting UI behavior, not domain logic.

13. **Static assets and app shell**
   - `index.html`, `public/`, `src/main.tsx`, `src/App.tsx`, and the global CSS files define the Vite app shell.
   - The repository is a SPA: routing and state management happen in the client, while Supabase handles persistence and backend concerns.

14. **Operational/deployment boundary**
   - `supabase/config.toml`, migrations, and seed SQL indicate the backend schema is meant to be provisioned and versioned alongside the frontend.
   - The repo therefore has two deployable concerns:
     - the **static frontend**
     - the **Supabase project/database schema**

15. **What an architecture diagram should emphasize**
   - Show the **React/Vite client** as the central node.
   - Draw separate boxes for:
     - **Pages/screens**
     - **Reusable UI components**
     - **Custom hooks/state**
     - **Supabase client/types**
     - **Supabase auth + database + RPC + realtime/presence**
   - The key data paths are:
     - user interaction in pages → hooks → Supabase
     - auth state → app-wide context/hooks → gated views
     - product/listing data → cards/detail pages/saved items
     - conversation data → conversation screens + unread/presence state

Main entry points: [`src/integrations/supabase/client.ts`](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/integrations/supabase/client.ts) (Supabase client), [`src/App.tsx`](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/App.tsx) (App routes), [`src/pages/Index.tsx`](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/Index.tsx) (Marketplace pages), [`src/pages/Auth.tsx`](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/Auth.tsx) (Account pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_app_shell["App shell<br/>spa entry<br/>[main.tsx]"]
  node_app_routes["App routes<br/>route host<br/>[App.tsx]"]
  node_pages_market["Marketplace pages<br/>screens<br/>[Index.tsx]"]
  node_pages_account["Account pages<br/>auth and profile<br/>[Auth.tsx]"]
  node_pages_messaging["Messaging pages<br/>conversations"]
  node_page_notfound["Not found<br/>fallback screen<br/>[NotFound.tsx]"]
  node_nav_ui["Nav chrome<br/>layout components<br/>[NavigationBar.tsx]"]
  node_product_cards["Product cards<br/>listing UI<br/>[ProductCard.tsx]"]
  node_auth_forms["Auth forms<br/>form components<br/>[SignInForm.tsx]"]
end

subgraph group_ui["UI system"]
  node_ui_primitives["UI primitives<br/>design system<br/>[button.tsx]"]
end

subgraph group_data["Data and state"]
  node_presence_ctx["Presence<br/>context provider"]
  node_auth_hook["Auth hook<br/>session state<br/>[useAuth.tsx]"]
  node_product_hooks["Product hooks<br/>data hooks"]
  node_saved_hooks["Saved hooks<br/>data hooks"]
  node_message_hook["Unread hook<br/>message state"]
end

subgraph group_backend["Supabase backend"]
  node_supabase_client["Supabase client<br/>backend client<br/>[client.ts]"]
  node_supabase_types["DB types<br/>generated schema types<br/>[types.ts]"]
  node_supabase_schema[("Schema migrations<br/>sql migrations")]
  node_supabase_seed["Seed data<br/>sql seed<br/>[seed.sql]"]
end

node_app_shell -->|"boots"| node_app_routes
node_app_routes -->|"routes to"| node_pages_market
node_app_routes -->|"routes to"| node_pages_account
node_app_routes -->|"routes to"| node_pages_messaging
node_app_routes -->|"fallback"| node_page_notfound
node_pages_market -->|"uses"| node_nav_ui
node_pages_market -->|"renders"| node_product_cards
node_pages_account -->|"uses"| node_auth_forms
node_pages_account -->|"reads session"| node_auth_hook
node_pages_messaging -->|"reads counts"| node_message_hook
node_pages_messaging -->|"subscribes"| node_presence_ctx
node_pages_market -->|"loads data"| node_product_hooks
node_pages_market -->|"loads saved"| node_saved_hooks
node_product_hooks -->|"queries"| node_supabase_client
node_saved_hooks -->|"queries"| node_supabase_client
node_auth_hook -->|"sessions"| node_supabase_client
node_message_hook -->|"reads"| node_supabase_client
node_presence_ctx -->|"connects"| node_supabase_client
node_supabase_client -->|"typed by"| node_supabase_types
node_supabase_types -->|"generated from"| node_supabase_schema
node_supabase_schema -.->|"seeded by"| node_supabase_seed

click node_app_shell "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/main.tsx"
click node_app_routes "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/App.tsx"
click node_pages_market "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/Index.tsx"
click node_pages_account "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/Auth.tsx"
click node_pages_messaging "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/ConversationList.tsx"
click node_page_notfound "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/NotFound.tsx"
click node_nav_ui "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/components/NavigationBar.tsx"
click node_product_cards "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/components/ProductCard.tsx"
click node_auth_forms "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/components/auth/SignInForm.tsx"
click node_ui_primitives "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/components/ui/button.tsx"
click node_presence_ctx "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/contexts/PresenceProvider.tsx"
click node_auth_hook "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/hooks/useAuth.tsx"
click node_product_hooks "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/hooks/usePublicProducts.tsx"
click node_saved_hooks "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/hooks/useSavedProducts.tsx"
click node_message_hook "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/hooks/useUnreadMessagesCount.tsx"
click node_supabase_client "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/integrations/supabase/client.ts"
click node_supabase_types "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/integrations/supabase/types.ts"
click node_supabase_schema "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/supabase/migrations/00000000_consolidated_migration.sql"
click node_supabase_seed "https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/supabase/seed.sql"

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_app_shell,node_app_routes,node_pages_market,node_pages_account,node_pages_messaging,node_page_notfound,node_nav_ui,node_product_cards,node_auth_forms toneBlue
class node_ui_primitives toneAmber
class node_presence_ctx,node_auth_hook,node_product_hooks,node_saved_hooks,node_message_hook toneMint
class node_supabase_client,node_supabase_types,node_supabase_schema,node_supabase_seed toneRose
```

## Components

### Frontend app

Vite + React SPA, route screens, shell, and shared marketplace components.

- [App shell](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/main.tsx): spa entry · Client bootstrap, routing shell, and global styling. · `src/main.tsx`
- [App routes](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/App.tsx): route host · Top-level route composition for the marketplace app. · `src/App.tsx`
- [Marketplace pages](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/Index.tsx): screens · Browse, category, detail, listing creation, saved items, and static pages. · `src/pages/Index.tsx`
- [Account pages](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/Auth.tsx): auth and profile · Authentication, profile, and user-facing account views. · `src/pages/Auth.tsx`
- [Messaging pages](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/ConversationList.tsx): conversations · Conversation list and detail screens for buyer-seller communication. · `src/pages/ConversationList.tsx`
- [Not found](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/pages/NotFound.tsx): fallback screen · Route fallback for unknown paths. · `src/pages/NotFound.tsx`
- [Nav chrome](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/components/NavigationBar.tsx): layout components · Navigation bar, menu, and filter surfaces shared across the marketplace UI. · `src/components/NavigationBar.tsx`
- [Product cards](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/components/ProductCard.tsx): listing UI · Public and authenticated product card variants plus listing presentation. · `src/components/ProductCard.tsx`
- [Auth forms](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/components/auth/SignInForm.tsx): form components · Sign in, sign up, and password reset forms used by the auth page. · `src/components/auth/SignInForm.tsx`

### UI system

Reusable design-system primitives and small cross-cutting helpers.

- [UI primitives](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/components/ui/button.tsx): design system · Reusable Radix/shadcn-style interface components used across pages and feature components. · `src/components/ui/button.tsx`

### Data and state

Custom hooks and app-wide context that coordinate auth, products, saved items, and messaging state.

- [Presence](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/contexts/PresenceProvider.tsx): context provider · App-wide presence and live-state provider for communication features. · `src/contexts/PresenceProvider.tsx`
- [Auth hook](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/hooks/useAuth.tsx): session state · Centralized user/session state for gated views and identity. · `src/hooks/useAuth.tsx`
- [Product hooks](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/hooks/usePublicProducts.tsx): data hooks · Public and user-specific product queries for browse and seller flows. · `src/hooks/usePublicProducts.tsx`
- [Saved hooks](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/hooks/useSavedProducts.tsx): data hooks · Saved-item query hooks, including user-specific retrieval. · `src/hooks/useSavedProducts.tsx`
- [Unread hook](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/hooks/useUnreadMessagesCount.tsx): message state · Unread message count for messaging notifications and navigation state. · `src/hooks/useUnreadMessagesCount.tsx`

### Supabase backend

Supabase client boundary plus database schema, RPCs, seeds, and config.

- [Supabase client](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/integrations/supabase/client.ts): backend client · Typed client entry point for auth, database, and realtime access. · `src/integrations/supabase/client.ts`
- [DB types](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/src/integrations/supabase/types.ts): generated schema types · Generated TypeScript types for the Supabase schema. · `src/integrations/supabase/types.ts`
- [Schema migrations](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/supabase/migrations/00000000_consolidated_migration.sql): sql migrations · Database schema evolution, RPC functions, and saved-product logic. · `supabase/migrations/00000000_consolidated_migration.sql`
- [Seed data](https://github.com/uopsdod/claude_code_toy_marketplace/blob/main/supabase/seed.sql): sql seed · Initial database content for local or staged setup. · `supabase/seed.sql`

## Connections

- App shell → App routes: boots · The entrypoint mounts the routed application shell.
- App routes → Marketplace pages: routes to · Marketplace browsing and content pages are reached through app routing.
- App routes → Account pages: routes to · Auth and profile screens are exposed through the router.
- App routes → Messaging pages: routes to · Conversation screens are exposed through the router.
- App routes → Not found: fallback · Unknown routes resolve to the not-found screen.
- Marketplace pages → Nav chrome: uses · Marketplace pages share navigation and filtering UI.
- Marketplace pages → Product cards: renders · Listing browse and detail flows are driven by product presentation components.
- Account pages → Auth forms: uses · Authentication screens embed dedicated sign-in, sign-up, and reset forms.
- Account pages → Auth hook: reads session · Account pages depend on centralized auth/session state.
- Messaging pages → Unread hook: reads counts · Conversation views consume unread-message state.
- Messaging pages → Presence: subscribes · Messaging screens participate in app-wide presence/live state.
- Marketplace pages → Product hooks: loads data · Browse and listing pages query public and user-owned products through hooks.
- Marketplace pages → Saved hooks: loads saved · Saved-items screens query saved-product state through hooks.
- Product hooks → Supabase client: queries · Product hooks encapsulate Supabase reads and reactive state.
- Saved hooks → Supabase client: queries · Saved-item hooks encapsulate Supabase reads and RPC-backed retrieval.
- Auth hook → Supabase client: sessions · Auth state is backed by the Supabase client and session APIs.
- Unread hook → Supabase client: reads · Unread message state is derived from backend data through Supabase.
- Presence → Supabase client: connects · Presence and live state connect through the Supabase backend boundary.
- Supabase client → DB types: typed by · The client is constrained by generated schema types.
- DB types → Schema migrations: generated from · Types reflect the database schema and migrations.
- Schema migrations → Seed data: seeded by · Schema setup is paired with initial seed data.
