# justtcallmejayy/navigator architecture

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

- Interactive diagram: https://gitdiagram.com/justtcallmejayy/navigator
- Repository: https://github.com/justtcallmejayy/navigator

## Overview

**Film Theory Navigator** is a **client-side React + TypeScript SPA** built with **Vite**. It’s primarily a **read-heavy “theory library” UI** that:
- routes between pages (React Router)
- fetches data from **Supabase** (Postgres + REST-ish via Supabase client)
- caches/coordinates server state with **TanStack Query**
- renders a searchable/filterable grid and detail views

- **Browser SPA** composition (routes/layout/components)
- **Client-side data layer** (Query Client + query modules)
- **External managed backend** (Supabase: DB + RLS policies + possibly Auth)
- **Build/runtime split** (Vite build → static assets served via CDN/hosting)

##### Entry / bootstrap
- `index.html` (Vite entry HTML)
- `src/main.tsx` → mounts the React app, wires providers (likely Router + QueryClientProvider)
- `src/index.css`, `src/styles/theme.css`, `tailwind.config.ts`, `postcss.config.js` → styling system

##### App composition / routing
- `src/app/router.tsx` → route definitions for `/`, `/theory`, `/theory/:slug`, `/vocabulary`, `/admin/login`, `/admin`
- `src/app/layout/AppLayout.tsx`, `NavBar.tsx` → shared layout for pages
- `src/pages/*` → route-level screens (Home, TheoryLibrary, TheoryDetail, AdminLogin, AdminDashboard, VocabularyHub)

##### UI and domain components
- `src/components/theory/*` (TheoryGrid, TheoryCard, TheoryFilters) → domain-specific UI for the library
- `src/components/common/*` (Loading, ErrorState, EmptyState) → data-fetching UI states
- `src/components/ui/*` (Button, Card, Input) → base design system components

- **Pages (route screens)**
- **Domain components (theory feature)**
- **Shared UI kit + common states**

##### Data access layer (important for system design)
- `src/app/queryClient.ts` → TanStack Query configuration (retry, cache times, etc.)
- `src/lib/queries/theories.ts` → query functions (list published theories, get by slug, etc.)
- `src/lib/supabase/client.ts` → Supabase client configured via `VITE_SUPABASE_URL` + `VITE_SUPABASE_ANON_KEY`
- `src/lib/supabase/policies.md` → RLS/policy documentation (security boundary)
- `src/hooks/useDebounce.ts` → search UX support
- `src/utils/slug.ts`, `src/utils/format.ts` → transformations used across UI/data

**Pages/Components → TanStack Query → Query modules → Supabase client → Supabase service (DB/RLS)**.

##### README insights to encode explicitly
- **Search by title w/ debounced input** (so show “User typing → debounce → query refetch”)
- **Filter by category** (UI state affects query params)
- **Detail page by slug** (`/theory/:slug` triggers fetch-by-slug)
- **Published-only** (`status = 'published'`) enforced by query and/or RLS policy
- **Admin + Vocabulary placeholders** (present but not fully implemented; mark as “future/placeholder”)

##### React SPA (Film Theory Navigator)
- Router (React Router)
- Layout (AppLayout, NavBar)
- Pages (Home, TheoryLibrary, TheoryDetail, VocabularyHub, AdminLogin, AdminDashboard)
- Components (theory/common/ui)
##### Client Data Layer
- TanStack Query (QueryClient)
- Query modules (`lib/queries/theories.ts`)
- Supabase JS client (`lib/supabase/client.ts`)
##### Supabase (Managed Backend)
- Postgres DB (`theories` table)
- RLS / Policies (from `policies.md`)

- **Browser → Static Hosting/CDN:** GET `/`, JS bundle, CSS
- **React Router → Pages:** route resolution (`/theory`, `/theory/:slug`, etc.)
- **TheoryLibrary Page → useDebounce → TanStack Query:** debounced search term triggers refetch
- **TheoryFilters → Query key/params:** category affects query
- **TanStack Query → Query functions:** `fetchPublishedTheories(search, category)` / `fetchTheoryBySlug(slug)`
- **Query functions → Supabase Client:** `supabase.from('theories').select(...).eq('status','published')...`
- **Supabase Client → Supabase API → Postgres:** network call boundary (external service)
- **Supabase RLS/Policies → Query Results:** security filter (rows/columns allowed)

##### Architectural patterns worth calling out
- **SPA + client-side routing**
- **Feature/module separation**: `pages/` (route-level), `components/` (presentation), `lib/` (data integrations), `types/` (domain types)
- **Server-state management** via **TanStack Query** (caching, loading/error states)
- **BaaS backend**: Supabase is the persistence + access control boundary (RLS)

- React 19, Vite 7
- React Router 7
- TanStack Query 5
- Supabase JS client 2 → Supabase (Postgres + RLS)
- Tailwind CSS 3

##### Must-include nodes (based on files)
- `src/main.tsx` (bootstrap)
- `src/app/router.tsx` (routes)
- `src/app/layout/AppLayout.tsx`, `NavBar.tsx` (shared frame)
- Pages: `Home`, `TheoryLibrary`, `TheoryDetail`, `VocabularyHub`, `AdminLogin`, `AdminDashboard`
- Theory components: `TheoryGrid`, `TheoryCard`, `TheoryFilters`
- Common states: `Loading`, `ErrorState`, `EmptyState`
- `useDebounce`
- `queryClient.ts`
- `lib/queries/theories.ts`
- `lib/supabase/client.ts`
- Supabase: `theories` table + RLS policies

##### Optional but valuable nodes
- `types/theory.ts` (domain contract)
- `utils/slug.ts` (slug creation/usage)
- Tailwind/theme styling layer (not a runtime “service” but helps explain UI system)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 1: Context / Runtime
  %% =========================
  U["User (Browser)"]:::external

  subgraph "Static Delivery (Build → Runtime)"
    CDN["Static Hosting / CDN\n(serves Vite build assets)"]:::infra
    HTML["index.html"]:::infra
    ASSETS["JS/CSS Bundles\n(Vite output)"]:::infra
    CSS1["Global CSS (Tailwind entry)\nindex.css"]:::infra
    CSS2["Theme CSS\ntheme.css"]:::infra
    TW["tailwind.config.ts\n(build-time)"]:::infra
    PC["postcss.config.js\n(build-time)"]:::infra
  end

  U -->|"GET /"| CDN
  CDN -->|"serves"| HTML
  CDN -->|"serves"| ASSETS
  ASSETS -->|"loads"| CSS1
  ASSETS -->|"loads"| CSS2
  TW -.->|"build config"| ASSETS
  PC -.->|"build pipeline"| ASSETS

  %% =========================
  %% Level 2: SPA Internal Architecture
  %% =========================
  subgraph "Film Theory Navigator (React + TypeScript SPA)"
    MAIN["App Bootstrap\n(main.tsx)\nProviders: Router + QueryClient"]:::core

    subgraph "App Shell"
      ROUTER["Routes / Router\n(router.tsx)\n(React Router)"]:::core
      LAYOUT["AppLayout"]:::ui
      NAV["NavBar"]:::ui
    end

    subgraph "Pages (Route Screens)"
      HOME["Home"]:::page
      LIB["TheoryLibrary\n(Search + Filter + Grid)"]:::page
      DETAIL["TheoryDetail\n(/theory/:slug)"]:::page
      VOC["VocabularyHub\n(placeholder)"]:::pagePlaceholder
      ALOGIN["AdminLogin\n(placeholder)"]:::pagePlaceholder
      ADASH["AdminDashboard\n(placeholder)"]:::pagePlaceholder
    end

    subgraph "Presentation Layer"
      subgraph "Theory Feature Components"
        FILTERS["TheoryFilters\n(category filter)"]:::ui
        GRID["TheoryGrid"]:::ui
        CARD["TheoryCard"]:::ui
      end

      subgraph "Common Data States"
        LOADING["Loading"]:::state
        ERROR["ErrorState"]:::state
        EMPTY["EmptyState"]:::state
      end

      subgraph "Base UI Kit"
        BTN["Button"]:::uikit
        UICARD["Card"]:::uikit
        INPUT["Input\n(search input)"]:::uikit
      end
    end

    subgraph "Client Data Layer (Server State)"
      QC["TanStack Query\nQueryClient (queryClient.ts)"]:::data
      QMOD["Theories Query Module\n(theories.ts)\n(published-only queries)"]:::data
      DEB["useDebounce\n(debounced search term)"]:::util
      TYPES["Theory Type Contract\n(theory.ts)"]:::util
      SLUG["slug utils\n(slug.ts)"]:::util
      FMT["format utils\n(format.ts)"]:::util
      SBCLIENT["Supabase JS Client\n(client.ts)\n(VITE_SUPABASE_URL + ANON_KEY)"]:::data
    end
  end

  %% External Backend (BaaS)
  subgraph "Supabase (Managed Backend)"
    SBA["Supabase API\n(HTTPS)"]:::externalSvc
    DB[("Postgres DB\nTable: theories")]:::db
    RLS["RLS / Policies\n(policies.md)\n(Security boundary)"]:::security
    AUTH["Auth\n(planned/unused)"]:::externalSvcPlanned
  end

  %% =========================
  %% SPA boot / routing
  %% =========================
  HTML -->|"loads SPA"| MAIN
  MAIN -->|"mounts app"| ROUTER
  MAIN -->|"provides"| QC

  ROUTER -->|"route match '/'"| HOME
  ROUTER -->|"route match '/theory'"| LIB
  ROUTER -->|"route match '/theory/:slug'"| DETAIL
  ROUTER -.->|"route match '/vocabulary' (placeholder)"| VOC
  ROUTER -.->|"route match '/admin/login' (placeholder)"| ALOGIN
  ROUTER -.->|"route match '/admin' (placeholder)"| ADASH

  ROUTER -->|"wraps pages with"| LAYOUT
  LAYOUT -->|"includes"| NAV

  %% =========================
  %% Page composition
  %% =========================
  LIB -->|"uses"| FILTERS
  LIB -->|"renders"| GRID
  GRID -->|"renders list"| CARD

  LIB -->|"shows state"| LOADING
  LIB -->|"shows state"| ERROR
  LIB -->|"shows state"| EMPTY

  DETAIL -->|"shows state"| LOADING
  DETAIL -->|"shows state"| ERROR
  DETAIL -->|"shows state"| EMPTY

  FILTERS -->|"uses"| INPUT
  CARD -->|"uses"| UICARD
  FILTERS -->|"uses"| BTN

  %% =========================
  %% Search / filter → debounced query flow
  %% =========================
  U -->|"type search text"| INPUT
  INPUT -->|"set search term"| DEB
  FILTERS -->|"set category"| LIB
  DEB -->|"debounced term"| LIB

  LIB -->|"Query key ['theories',search,category]"| QC
  QC -->|"calls list query"| QMOD
  QMOD -->|"returns Theory[]"| TYPES

  %% Detail by slug flow
  U -->|"open detail"| ROUTER
  DETAIL -->|"extract slug param"| SLUG
  DETAIL -->|"Query key ['theory',slug]"| QC
  QC -->|"calls get-by-slug"| QMOD

  %% Formatting utilities used in UI rendering
  CARD -->|"format display"| FMT
  DETAIL -->|"format display"| FMT

  %% =========================
  %% Data layer → Supabase
  %% =========================
  QMOD -->|"supabase.from('theories')\nselect/eq(status='published')\ntext search + category filter"| SBCLIENT

  SBCLIENT -->|"Internet / HTTPS\n(anon key is public; RLS enforced)"| SBA
  SBA -->|"SQL / REST-ish gateway"| DB
  RLS -->|"filters rows/columns"| DB
  DB -->|"JSON rows"| SBA
  SBA -->|"JSON response"| SBCLIENT
  SBCLIENT -->|"data"| QMOD
  QMOD -->|"cache + notify"| QC
  QC -->|"render states"| LIB
  QC -->|"render states"| DETAIL

  %% Auth is planned/unused
  SBCLIENT -.->|"optional (planned)"| AUTH

  %% =========================
  %% Click events (from mapping)
  %% =========================
  click HTML "https://github.com/justtcallmejayy/navigator/blob/main/index.html"
  click MAIN "https://github.com/justtcallmejayy/navigator/blob/main/src/main.tsx"
  click CSS1 "https://github.com/justtcallmejayy/navigator/blob/main/src/index.css"
  click CSS2 "https://github.com/justtcallmejayy/navigator/blob/main/src/styles/theme.css"
  click TW "https://github.com/justtcallmejayy/navigator/blob/main/tailwind.config.ts"
  click PC "https://github.com/justtcallmejayy/navigator/blob/main/postcss.config.js"

  click ROUTER "https://github.com/justtcallmejayy/navigator/blob/main/src/app/router.tsx"
  click LAYOUT "https://github.com/justtcallmejayy/navigator/blob/main/src/app/layout/AppLayout.tsx"
  click NAV "https://github.com/justtcallmejayy/navigator/blob/main/src/app/layout/NavBar.tsx"

  click QC "https://github.com/justtcallmejayy/navigator/blob/main/src/app/queryClient.ts"
  click QMOD "https://github.com/justtcallmejayy/navigator/blob/main/src/lib/queries/theories.ts"
  click SBCLIENT "https://github.com/justtcallmejayy/navigator/blob/main/src/lib/supabase/client.ts"
  click RLS "https://github.com/justtcallmejayy/navigator/blob/main/src/lib/supabase/policies.md"

  click HOME "https://github.com/justtcallmejayy/navigator/blob/main/src/pages/Home.tsx"
  click LIB "https://github.com/justtcallmejayy/navigator/blob/main/src/pages/TheoryLibrary.tsx"
  click DETAIL "https://github.com/justtcallmejayy/navigator/blob/main/src/pages/TheoryDetail.tsx"
  click VOC "https://github.com/justtcallmejayy/navigator/blob/main/src/pages/VocabularyHub.tsx"
  click ALOGIN "https://github.com/justtcallmejayy/navigator/blob/main/src/pages/AdminLogin.tsx"
  click ADASH "https://github.com/justtcallmejayy/navigator/blob/main/src/pages/AdminDashboard.tsx"

  click GRID "https://github.com/justtcallmejayy/navigator/blob/main/src/components/theory/TheoryGrid.tsx"
  click CARD "https://github.com/justtcallmejayy/navigator/blob/main/src/components/theory/TheoryCard.tsx"
  click FILTERS "https://github.com/justtcallmejayy/navigator/blob/main/src/components/theory/TheoryFilters.tsx"

  click LOADING "https://github.com/justtcallmejayy/navigator/blob/main/src/components/common/Loading.tsx"
  click ERROR "https://github.com/justtcallmejayy/navigator/blob/main/src/components/common/ErrorState.tsx"
  click EMPTY "https://github.com/justtcallmejayy/navigator/blob/main/src/components/common/EmptyState.tsx"

  click BTN "https://github.com/justtcallmejayy/navigator/blob/main/src/components/ui/Button.tsx"
  click UICARD "https://github.com/justtcallmejayy/navigator/blob/main/src/components/ui/Card.tsx"
  click INPUT "https://github.com/justtcallmejayy/navigator/blob/main/src/components/ui/Input.tsx"

  click DEB "https://github.com/justtcallmejayy/navigator/blob/main/src/hooks/useDebounce.ts"
  click TYPES "https://github.com/justtcallmejayy/navigator/blob/main/src/types/theory.ts"
  click SLUG "https://github.com/justtcallmejayy/navigator/blob/main/src/utils/slug.ts"
  click FMT "https://github.com/justtcallmejayy/navigator/blob/main/src/utils/format.ts"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ffffff,stroke:#111827,stroke-width:2px,color:#111827
  classDef infra fill:#eef2f7,stroke:#64748b,stroke-width:2px,color:#0f172a
  classDef core fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#0b1b4a
  classDef page fill:#bfdbfe,stroke:#1d4ed8,stroke-width:2px,color:#0b1b4a
  classDef ui fill:#93c5fd,stroke:#1d4ed8,stroke-width:2px,color:#0b1b4a
  classDef uikit fill:#7dd3fc,stroke:#0369a1,stroke-width:2px,color:#082f49
  classDef state fill:#bae6fd,stroke:#0284c7,stroke-width:2px,color:#082f49

  classDef data fill:#e9d5ff,stroke:#7c3aed,stroke-width:2px,color:#2e1065
  classDef util fill:#ede9fe,stroke:#6d28d9,stroke-width:2px,color:#2e1065

  classDef externalSvc fill:#fed7aa,stroke:#ea580c,stroke-width:2px,color:#431407
  classDef security fill:#ffedd5,stroke:#c2410c,stroke-width:2px,color:#431407
  classDef db fill:#fdba74,stroke:#c2410c,stroke-width:2px,color:#431407
  classDef externalSvcPlanned fill:#ffedd5,stroke:#ea580c,stroke-width:2px,stroke-dasharray: 6 4,color:#431407

  classDef pagePlaceholder fill:#bfdbfe,stroke:#1d4ed8,stroke-width:2px,stroke-dasharray: 6 4,color:#0b1b4a
```
