How justtcallmejayy/navigator works
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)