# nstkrishna/talvia architecture

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

- Interactive diagram: https://gitdiagram.com/nstkrishna/talvia
- Repository: https://github.com/nstkrishna/talvia

## Overview

**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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% User Device / Client
  %% =========================
  subgraph "User Device"
    U["User"]:::external
    B["Browser (Client-rendered UI)"]:::external
    U -->|"interacts"| B
  end

  %% =========================
  %% Talvia (Next.js App)
  %% =========================
  subgraph "Talvia (Next.js App Router Application)"
    subgraph "Routing / Pages (App Router)"
      L["Root Layout (app/layout.tsx)"]:::page
      G["Global Styles (app/globals.css)"]:::styling
      H["Home/Search Page '/' (app/page.tsx)"]:::page
      D["Profile Dashboard '/:username' (app/[username]/page.tsx)"]:::page
      R["Dynamic Route Param ':username'"]:::note

      L -->|"includes"| G
      L -->|"wraps"| H
      L -->|"wraps"| D
      D -->|"reads"| R
    end

    subgraph "UI System (Reusable Components)"
      TP["ThemeProvider (components/theme-provider.tsx)"]:::ui
      UI["UI Component Library (components/ui/*)"]:::ui
      TW["TailwindCSS Styling"]:::styling
      TP -->|"themes"| UI
      G -->|"drives"| TW
      TW -->|"styles"| UI
    end

    subgraph "Hooks / Utilities"
      TST["use-toast (hooks/use-toast.ts)"]:::util
      MOB["use-mobile (hooks/use-mobile.ts)"]:::util
      UT["utils (lib/utils.ts)"]:::util
    end

    subgraph "Data Access (Client-side GraphQL Helpers; NOT server routes)"
      APIDIR["Module: app/api/* (helpers)"]:::api
      API["GitHub API Wrapper (app/api/github.api.ts)"]:::api
      AC["Apollo Client Setup (app/api/client.ts)"]:::api
      Q["GraphQL Query Documents (app/api/github.queries.ts)"]:::api
      TY["TypeScript Types (app/api/types.ts)"]:::api

      APIDIR -->|"contains"| API
      APIDIR -->|"contains"| AC
      APIDIR -->|"contains"| Q
      APIDIR -->|"contains"| TY

      API -->|"uses"| AC
      API -->|"uses"| Q
      API -->|"uses"| TY
      AC -->|"executes"| Q
    end

    subgraph "Config / Tooling"
      ENV[".env.local (NEXT_PUBLIC_GITHUB_TOKEN)"]:::secret
      NC["next.config.ts"]:::config
      TSC["tsconfig.json"]:::config
      PC["postcss.config.mjs"]:::config
      ESL["eslint.config.mjs"]:::config
      PUB["public/ (static assets)"]:::asset
    end
  end

  %% =========================
  %% External Services
  %% =========================
  subgraph "External Services"
    GH["GitHub GraphQL API v4 (External SaaS)"]:::externalSvc
  end

  %% =========================
  %% Interactions / Flows
  %% =========================
  B -->|"navigates '/' "| H
  B -->|"navigates '/:username' "| D

  H -.->|"imports/components"| UI
  H -.->|"uses/hooks"| TST
  H -.->|"uses/utils"| UT

  D -.->|"imports/components"| UI
  D -.->|"uses/hooks"| TST
  D -.->|"uses/hooks"| MOB
  D -.->|"uses/utils"| UT

  D -->|"calls getUserProfile(username)"| API
  R -->|"feeds username"| API

  %% Token / trust boundary
  ENV -->|"provides NEXT_PUBLIC_GITHUB_TOKEN"| AC
  AC -->|"adds Authorization header"| GH
  AC -->|"HTTPS GraphQL request"| GH
  GH -->|"JSON response"| AC
  AC -->|"returns data"| API
  API -->|"returns view-model"| D

  %% Note about architecture
  NOTE1["Note: No custom backend or app/api route handlers; app/api is client-side helpers. Token is NEXT_PUBLIC_* (exposed to client bundle)."]:::note
  D -.->|"architecture note"| NOTE1

  %% =========================
  %% Click Events (from component mapping)
  %% =========================
  click L "https://github.com/nstkrishna/talvia/blob/main/my-app/app/layout.tsx"
  click G "https://github.com/nstkrishna/talvia/blob/main/my-app/app/globals.css"
  click H "https://github.com/nstkrishna/talvia/blob/main/my-app/app/page.tsx"
  click D "https://github.com/nstkrishna/talvia/blob/main/my-app/app/[username]/page.tsx"

  click AC "https://github.com/nstkrishna/talvia/blob/main/my-app/app/api/client.ts"
  click API "https://github.com/nstkrishna/talvia/blob/main/my-app/app/api/github.api.ts"
  click Q "https://github.com/nstkrishna/talvia/blob/main/my-app/app/api/github.queries.ts"
  click TY "https://github.com/nstkrishna/talvia/blob/main/my-app/app/api/types.ts"
  click APIDIR "https://github.com/nstkrishna/talvia/tree/main/my-app/app/api/"

  click TP "https://github.com/nstkrishna/talvia/blob/main/my-app/components/theme-provider.tsx"
  click UI "https://github.com/nstkrishna/talvia/tree/main/my-app/components/ui/"
  click TST "https://github.com/nstkrishna/talvia/blob/main/my-app/hooks/use-toast.ts"
  click MOB "https://github.com/nstkrishna/talvia/blob/main/my-app/hooks/use-mobile.ts"
  click UT "https://github.com/nstkrishna/talvia/blob/main/my-app/lib/utils.ts"

  click NC "https://github.com/nstkrishna/talvia/blob/main/my-app/next.config.ts"
  click TSC "https://github.com/nstkrishna/talvia/blob/main/my-app/tsconfig.json"
  click PC "https://github.com/nstkrishna/talvia/blob/main/my-app/postcss.config.mjs"
  click ESL "https://github.com/nstkrishna/talvia/blob/main/my-app/eslint.config.mjs"
  click PUB "https://github.com/nstkrishna/talvia/tree/main/my-app/public"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#0b1220,stroke:#60a5fa,stroke-width:1.5px,color:#e5e7eb
  classDef externalSvc fill:#0b1220,stroke:#34d399,stroke-width:2px,color:#e5e7eb
  classDef page fill:#111827,stroke:#f59e0b,stroke-width:2px,color:#f9fafb
  classDef ui fill:#111827,stroke:#a78bfa,stroke-width:2px,color:#f9fafb
  classDef util fill:#111827,stroke:#22c55e,stroke-width:1.5px,color:#f9fafb
  classDef api fill:#111827,stroke:#06b6d4,stroke-width:2px,color:#f9fafb
  classDef styling fill:#111827,stroke:#ec4899,stroke-width:1.5px,color:#f9fafb
  classDef config fill:#111827,stroke:#94a3b8,stroke-width:1.5px,color:#f9fafb
  classDef asset fill:#111827,stroke:#cbd5e1,stroke-width:1.5px,color:#f9fafb
  classDef secret fill:#2a0f14,stroke:#ef4444,stroke-width:2px,color:#fee2e2
  classDef note fill:#0f172a,stroke:#eab308,stroke-width:1px,color:#fef9c3,stroke-dasharray:4 3
```
