Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
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.tsinhooks/when shared across features;useCamelCase.tsinside the feature folder when only one feature uses it - shadcn ui files:
kebab-case.tsx(generated convention, do not rename;components.jsonsetstsx: true) .tsxonly for files that contain JSX; seedocs/guidelines/NAMING.md
Adding a New Page
See docs/features/NEW_REACT_PAGE.md.