How nstkrishna/talvia works
Talvia is a client-rendered Next.js (App Router) web application that renders:
• a Home/Search page (app/page.tsx)
• a Dynamic profile dashboard page for a GitHub user (app/[username]/page.tsx)
It fetches data from the GitHub GraphQL API v4 using Apollo Client and a GitHub Personal Access Token exposed as NEXT_PUBLIC_GITHUB_TOKEN (important for the architecture/security depiction).
There is no custom backend service in this repo (no Next.js route handlers under app/api/*/route.ts). The app/api/* folder is client-side API helpers + queries, not server endpoints.
So: this is a single Next.js app (frontend + Next runtime) calling an external SaaS API (GitHub GraphQL) directly from the browser / Next runtime, depending on how components are authored.
Read the file tree as architecture signals
From the tree:
Runtime / Pages (App Router)
• my-app/app/layout.tsx: root layout; likely wires ThemeProvider and global styling.
• my-app/app/page.tsx: search entry page.
• my-app/app/[username]/page.tsx: user dashboard page (core UI composition).
Data access layer (GraphQL client + queries)
• my-app/app/api/client.ts: Apollo client setup (GraphQL endpoint, auth header, cache policy, etc.).
• my-app/app/api/github.api.ts: higher-level functions (e.g., getUserProfile(username) style).
• my-app/app/api/github.queries.ts: GraphQL documents (queries).
• my-app/app/api/types.ts: TypeScript types for responses/inputs.
UI system
• my-app/components/theme-provider.tsx: app-wide theming.
• my-app/components/ui/*: shadcn/Radix-based primitives (dialog, tabs, charts, etc.). These are *library-like* modules used by pages.
Shared utilities & hooks
• my-app/hooks/use-toast.ts, my-app/hooks/use-mobile.ts
• my-app/lib/utils.ts
Platform/config
• next.config.ts, tsconfig.json, postcss.config.mjs, eslint.config.mjs
• TailwindCSS implied by globals.css and configs.
• public/ for static assets.
Next.js App (Talvia)
• App Router / Pages:
• Home/Search (app/page.tsx)
• Profile Dashboard (app/[username]/page.tsx)
• UI Component Library:
• components/ui/* (shadcn + Radix)
• ThemeProvider (components/theme-provider.tsx)
• Styling:
• TailwindCSS + globals.css
Apollo Client Layer
• app/api/client.ts (client configuration, auth header)
• app/api/github.api.ts (API wrapper functions)
• app/api/github.queries.ts (GraphQL operations)
• app/api/types.ts (types)
External Service: GitHub GraphQL API v4
• Requires Personal Access Token (PAT)
Runtime / Hosting
• “Next.js runtime on Vercel / Node.js server” (even if not explicitly present, it’s implied by Next.js deployment)
Secrets / Config
• .env.local providing NEXT_PUBLIC_GITHUB_TOKEN (note: public exposure risk)
Layered architecture in a single app
• Route/page layer
• Component/presentation layer
• Data-access layer (Apollo + query documents)
• External API integration
“API module” is not a backend
• The folder name app/api might mislead viewers—annotate it as client-side GraphQL helpers (unless you confirm there are server route handlers elsewhere).
Dynamic routing
• app/[username]/page.tsx implies a dynamic segment; show route param flows into the data queries.
Reusable design system
• shadcn/Radix components are effectively an internal UI platform; show as a separate cluster to clarify reuse.
• No internal database
• No internal API server
• External dependency is GitHub GraphQL
• Auth is via PAT in env var (and it’s NEXT_PUBLIC_*, so it’s in the client bundle—show this in a “Public Client Secret Exposure” annotation or at least a trust-boundary note)
• Client-side GraphQL calls (token in browser) — likely current setup
• Server-side calls via Next runtime (token kept server-side) — recommended alternative, but mark it as “future/improvement” if it’s not implemented
External Services
• Routing/Pages
• UI Components (shadcn/Radix)
• Hooks/Utils
• Data Access (Apollo + Queries)
Labels (use file-based labels so it’s auditable)
Examples:
• “Profile Dashboard Page (app/[username]/page.tsx)"
• “Apollo Client (app/api/client.ts)"
• “GraphQL Queries (app/api/github.queries.ts)"
• “GitHub API Wrapper (app/api/github.api.ts)”
Browser
• displays UI
• triggers navigation to / and /:username
Next.js App (Talvia)
• App Router
• layout.tsx (ThemeProvider + globals)
• page.tsx (Search)
• [username]/page.tsx (Dashboard)
• UI Layer
• components/ui/*
• hooks/*, lib/utils.ts
• Data Layer
• Apollo Client (client.ts)
• Queries (github.queries.ts)
• API wrapper (github.api.ts)
• Types (types.ts)
• Config
• .env.local (NEXT_PUBLIC_GITHUB_TOKEN)
GitHub GraphQL API v4
• receives GraphQL queries
• returns profile/repo/language/contribution data
• Browser → Next.js routes
• Dashboard → Data Layer → GitHub GraphQL
• .env.local token → Apollo Client → GitHub