Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

10.7 KB
Raw Blame

Frontend React Architecture

Stack

Concern Library Version
Language TypeScript (strict) 6.0
Framework React 19
Router React Router 7
Build tool Vite 7
UI components shadcn/ui (base-nova style) -
Styling Tailwind CSS 4
Charts Recharts, through Intent UI's chart components (components/ui/chart.tsx and the area, bar and line charts; ADR-048) 3
Chart legend toggles react-aria-components 1
Theming next-themes -
Toasts Sonner -
Icons Lucide React -
Command palette cmdk -
Fonts Sora, Manrope, JetBrains Mono (self-hosted from public/fonts) -

Visual tokens and shared components are described in DESIGN_SYSTEM.md.

This page covers the app (frontend/). The public marketing site and docs are a separate workspace, site/, described in docs/architecture/site/SITE.md.

TypeScript and Vite

Every file in frontend/src is .ts, or .tsx when it contains JSX. Vite (with @vitejs/plugin-react and @tailwindcss/vite, configured in frontend/vite.config.ts) strips the types while it serves and builds; it does not check them. npm run typecheck does:

Config Checks Notes
frontend/tsconfig.json frontend/src Extends the root tsconfig.base.json; DOM lib, jsx: react-jsx, vite/client types; path aliases @/* (to src/*) and @shared/* (to ../shared/*)
frontend/tsconfig.node.json vite.config.ts, frontend/tests, src/vite-env.d.ts Node types

src/vite-env.d.ts types import.meta.env (the VITE_* variables). vite.config.ts defines only the @ alias: @shared imports are always import type, which Vite erases before it resolves anything. The API response types come from shared/types/ (see API_LAYER.md); component props are typed with a <Component>Props interface in the component file (see docs/guidelines/TYPESCRIPT.md).

Entry: frontend/src/main.tsx

frontend/index.html loads /src/main.tsx:

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Application Shell: frontend/src/App.tsx

Defines the router, provider tree, and lazy-loaded page imports.

Lazy loading: All pages except Login are wrapped in React.lazy(). This means pages are code-split into separate chunks and loaded on first navigation. The <Suspense fallback={null}> wrapper renders nothing while the chunk loads. Login lazy-loads only its decorative LoginBackdrop, so the sign-in card never waits for it.

Router: Uses createBrowserRouter (React Router v7 data router). This enables nested layouts via <Outlet /> in MainLayout.

Provider Tree

ThemeProvider (next-themes)          <- OS/user theme preference
  TooltipProvider (shadcn)           <- global tooltip context
    AuthProvider (AuthContext.tsx)   <- Supabase session
      Suspense (fallback=null)
        RouterProvider
          /login -> Login (no protection)
          /docs/* -> DocsRedirect      <- leaves the app for the public docs
          /* ->
            ProtectedRoute           <- redirects to /login if no session
              AppProvider            <- accounts[], loading, showToast
                AppShell (layout/index.tsx)
                  AppSidebar         <- navigation, accounts, categories, user menu
                  TopBar             <- page title or breadcrumb, search, help
                  (lazy page)
                  CommandPalette     <- Ctrl+K / Cmd+K
      Toaster (Sonner, bottom-right) <- toast notifications

Why AppProvider is inside ProtectedRoute: AppProvider calls api.getAccounts() on mount. This request requires a valid JWT. If AppProvider were outside ProtectedRoute, it would fire before auth is confirmed and fail with 401.

Directory Structure

frontend/src/
  main.tsx               Entry point
  App.tsx                Router + provider tree
  index.css              Tailwind + CSS variable tokens
  lib/
    supabase.ts          Supabase anon client (singleton)
    utils.ts             cn() = clsx + tailwind-merge
    accounts.ts          Platform helpers: paths, names, handles, platform summary
    chart.ts             Recharts axis, grid, tooltip and series styling
    library.ts           Filter tiers, paging, duration and engagement helpers
    commandSearch.ts     Command palette ranking
    holdProgress.ts      Hold-to-confirm timing
    docs.ts              DOCS_URL and docsUrl(path), links to the public docs on the site
  services/
    api.ts               All backend HTTP calls
  context/
    AuthContext.tsx       Session, sign-in code, password sign-in and sign-up, Google, reset, signOut
    AppContext.tsx        Accounts list, loading, showToast
  utils/
    formatters.ts         fmtNum, fmtDate, fmtDuration, normalizeAccount, etc.
  hooks/
    use-mobile.ts         useIsMobile()
    use-command-palette-shortcut.ts  Ctrl+K / Cmd+K toggle
    use-smooth-theme.ts   useSmoothTheme(), theme cross-fade
    use-document-title.ts useDocumentTitle(name): a detail page names the browser tab after what it shows
    use-cloudinary-config.ts  useCloudinaryConfig(reloadKey), used by Publish
    use-account-analytics.ts  useAccountAnalytics(account, fetchAnalytics, label), used by Instagram analytics
  layout/
    index.tsx             AppShell: SidebarProvider + AppSidebar + TopBar + Outlet + CommandPalette
    navigation.ts         NAV_GROUPS with icons, routeTitle() and currentNavPath() (single source for sidebar, top bar, palette)
    routes.ts             Pure route matching: DETAIL_ROUTES, longest-match active link, tab titles (tested)
    routeFocus.ts         Moves focus to the new page's heading after a navigation
    shortcuts.ts          Keyboard shortcut labels (Ctrl or Cmd) for the sidebar, palette and tooltips
    shellContext.ts       What the shell passes to pages through the outlet (openPalette)
    RedirectWithQuery.tsx Redirect from a moved path, keeping the query string and hash
    Sidebar.tsx           Collapsible sidebar: logo, search, nav groups, capped account and category lists, user menu
    Header.tsx            TopBar: page title or breadcrumb with a parent link, search, help
  components/
    ProtectedRoute.tsx    Auth guard component
    DocsRedirect.tsx      /docs/* route: sends old docs links to the same page on the public site
    PageHeader.tsx, SurfaceBox.tsx, MetricBox.tsx, ...   Shared components (see DESIGN_SYSTEM.md)
    brand/                Logo and platform icons
    ui/                   shadcn generated components, restyled onto the tokens
  pages/
    Login.tsx             Auth page (not lazy-loaded, always small): one card over the dashboard picture; owns the view
                          (start, code, password, signup, verify, forgot, reset), fields, the password toggle and the resend wait
    LoginBackdrop.tsx     Blurred picture of the dashboard behind the card, built from the shared components with sample
                          figures; aria-hidden and loaded with React.lazy so it never delays the card
    LoginEmailStart.tsx   The first view's email field, with a mail icon and the Continue arrow inside it
    LoginPasswordForm.tsx Email and password form, for signing in and for creating a password account
    NotFound.tsx          The page for any unknown path inside the app: the path, a link to the overview, the search shortcut
    LoginCodeForm.tsx     The 6-digit email code step (code sign-in, sign-up confirmation, and password reset with a new-password field), with Send a new code
    LoginEmailForm.tsx    The email-only Forgot password step
    PasswordInput.tsx     Password field with its show or hide button, used by the sign-in, sign-up and reset forms
    useCountdown.ts       Seconds until another email code may be sent
    loginCopy.ts          LoginView, the title and button text for each view, the sign-up title, privacy link
  features/
    analytics/
      overview/           Overview.tsx - all-accounts dashboard (page; tabs, hooks and helpers beside it)
      channel/            ChannelAnalytics.tsx - per-channel YouTube (page; tabs, hook and helpers beside it)
      instagram/          InstagramAnalytics.tsx - per-account Instagram (page; sections and helpers beside it)
      videos/             VideoExplorer.tsx - all videos table (page; filters, table, grid and helpers beside it)
      shorts/             ShortsExplorer.tsx - shorts-filtered grid (page; filters and grid beside it)
      reels/              ReelsExplorer.tsx - Instagram media grid (page; hook, filters and helpers beside it)
      tracked/            TrackedContent.tsx, TrackedCategory.tsx (pages; components, hooks and helpers beside them)
    publishing/
      UploadContent.tsx   Instagram publishing + schedule queue (page; components, hooks and helpers beside it)
    accounts/
      AccountManager.tsx  Add/remove/refresh accounts (page; dialog, cards, hooks and helpers beside it)
    settings/
      Settings.tsx        API keys status + GitHub config (page; sections, setup guide, hooks and helpers beside it)

Unit tests are outside src/, in frontend/tests/, which mirrors this tree: src/lib/accounts.ts is covered by frontend/tests/lib/accounts.test.ts. They run on the Node test runner with npm test (Node strips the types; see docs/workflows/TESTING.md), and Vite never bundles them.

Packages and Tooling

frontend/ is a workspace of the root npm workspaces monorepo. Install from the repository root with npm install, and add a frontend package with npm install <pkg> --workspace frontend; there is no frontend/package-lock.json. The frontend's own dev dependencies include @types/react and @types/react-dom. Shared dev tooling (TypeScript, typescript-eslint, @types/node, ESLint and its plugins, globals, Prettier, concurrently) is in the root package.json, and the lint rules are in the root eslint.config.mjs. From the root, npm run dev:frontend starts Vite on port 5173, npm run dev starts it with the Worker, npm run build builds frontend/dist/, and npm run typecheck runs the workspace's typecheck script (tsc -p tsconfig.json && tsc -p tsconfig.node.json) along with the other projects.

Naming Conventions

  • Feature files: PascalCase.tsx (matches component name)
  • Utility files: camelCase.ts
  • Context files: PascalCaseContext.tsx
  • Hook files: use-kebab-case.ts in hooks/ when shared across features; useCamelCase.ts inside the feature folder when only one feature uses it
  • shadcn ui files: kebab-case.tsx (generated convention, do not rename; components.json sets tsx: true)
  • .tsx only for files that contain JSX; see docs/guidelines/NAMING.md

Adding a New Page

See docs/features/NEW_REACT_PAGE.md.