# aibiansari/linkrary architecture

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

- Interactive diagram: https://gitdiagram.com/aibiansari/linkrary
- Repository: https://github.com/aibiansari/linkrary

## Overview

##### What this project is (type + purpose)
**Linkrary** is a **Next.js (React + TypeScript) web application** that serves as a curated directory of links (tools/resources) organized into categories, with **search/filter**, **favorites/bookmarks**, **dark mode**, and **animations**.

From the file tree, it is primarily a **frontend app** (no explicit backend/service layer in-repo). Any “backend-like” capability is delegated to **external services** (notably **EmailJS** for contact/feedback).

##### How to read the architecture from the file structure
Key structural signals:

##### Next.js App Router structure
- `src/app/...`
- `layout.tsx` → global layout (root shell)
- `globals.css` → global styling entry
- `page.tsx` → landing page route `/`
- `about/page.tsx` → `/about`
- `collection/page.tsx` → `/collection` (likely favorites/bookmarks)
- `loading.tsx`, `not-found.tsx` → route-level UX primitives

This strongly indicates **Next.js 13+ App Router** with route segments and shared layout.

##### UI components
- `src/components/ui/*`
- Components like `navbar.tsx`, `Cards.tsx`, `ScrollX.tsx`
- Modals: `categoryModal.tsx`, `filterModal.tsx`
- Controls: `dropdown.tsx`
- Communication: `contact.tsx` (likely EmailJS integration)
These are your **presentation + interaction layer**.

##### State management via React Context
- `src/contexts/*`
- `useCategoryContext.tsx`
- `useCategoryModalContext.tsx`
- `useFavoriteCardsContext.tsx`
- `useFilterButtonContext.tsx`

This implies **client-side state** and cross-component coordination using **React Context providers/hooks** (favorites, selected category, modal open state, filter state).

##### Static data as “domain content”
- `src/data/*`
- `Cards.ts` → curated resources (likely the “database” equivalent)

This is important: the “data store” is currently **static in code**, not a DB.

##### What the README adds (stack + external dependencies)
From README:
- **Next.js + React + TypeScript**
- **TailwindCSS**
- **Framer Motion** (animations)
- **Sonner** (toasts)
- **EmailJS** (send feedback emails)
- **next-themes** (dark mode/theme toggle)

These should appear as **supporting libraries** attached to the components that use them, and **EmailJS** should appear as an **external integration**.

##### Client (Browser)
- React UI components
- Context state (favorites, filters, modals)

##### Next.js Runtime (Server / Edge)
- Route handling for `/`, `/about`, `/collection`

##### External Services
- EmailJS API

- Browser ↔ Next.js runtime: “Request route, receive HTML/JS, hydrate”
- Browser → EmailJS: Often EmailJS runs client-side (depending on usage). If `contact.tsx` calls EmailJS directly from the browser, show **Browser → EmailJS**. If it’s proxied via an API route (none shown), then it would be **Browser → Next.js API → EmailJS**. Based on the tree (no `app/api`), the most accurate default is **Browser → EmailJS**.

**Goal:** Show how the internal modules interact: pages → UI components → contexts → data.

##### Routes (src/app)
- `/ (src/app/page.tsx)`
- `/about (src/app/about/page.tsx)`
- `/collection (src/app/collection/page.tsx)`
- Shared: `layout.tsx`, `loading.tsx`, `not-found.tsx`

##### UI Layer (src/components/ui)
- `navbar.tsx` (navigation + theme toggle likely)
- `Cards.tsx` (renders resource cards)
- `ScrollX.tsx` (horizontal scroller / carousel behavior)
- `categoryModal.tsx`, `filterModal.tsx` (modal UX)
- `dropdown.tsx` (filter/category selection)
- `contact.tsx` (feedback form → EmailJS; toasts via Sonner)

##### State Layer (src/contexts)
- Category selection state
- Category modal open/close state
- Favorites state
- Filter button/filter state

##### Data Layer (src/data)
- `Cards.ts` as the “source of truth” for resources
- `Categories.tsx` for taxonomy

##### Cross-cutting concerns
- **Tailwind**: styling across all components (`globals.css`, `tailwind.config.ts`)
- **Framer Motion**: attach to UI components that animate (modals, cards, transitions)
- **Sonner**: attach to components that raise toasts (likely contact submission + loading states)
- **next-themes**: attach to layout/navbar/theme provider (where theme is toggled)

- Routes → UI Components (pages compose UI)
- UI Components ↔ Context Hooks (read/write global state)
- UI Components → Data modules (render cards/categories from static lists)
- contact.tsx → EmailJS (external call)
- UI Components → Sonner (toast notifications)
- UI Components → Framer Motion (animations)
- layout.tsx/navbar.tsx → next-themes (theme provider/toggle)

##### Required elements
- **Clear labels**: Use file names for internal modules where helpful (e.g., “Cards.ts (dataset)”).
- Rectangles for internal modules
- Clouds for external services (EmailJS)

- `App Shell`
- `src/app/layout.tsx`
- `src/app/globals.css`
- `Routes`
- `HomeRoute (page.tsx)`
- `AboutRoute`
- `CollectionRoute`
- `LoadingUI`, `NotFoundUI`
- `UI Components`
- `Navbar`
- `CardsList/Cards`
- `CategoryModal`
- `FilterModal`
- `Dropdown`
- `ScrollX`
- `ContactForm`
- `State (Contexts)`
- `CategoryContext`
- `CategoryModalContext`
- `FavoriteCardsContext`
- `FilterButtonContext`
- `Data`
- `CardsDataset`
- `CategoriesDataset`
- `IconsMapping`
- `Libraries`
- `Framer Motion`
- `Sonner`
- `next-themes`
- `External`
- `EmailJS API`
- `DevOps`
- `GitHub Actions workflow (nextjs.yml)`
- `Build pipeline (Next.js build + Tailwind/PostCSS)`

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================================================
%% System Context + Container + Component (single vertical diagram)
%% =========================================================

U["User (Browser)"]:::external

subgraph "Linkrary (Next.js Web App)"
direction TB

  subgraph "Runtime: Browser (Client)"
  direction TB
    ClientUI["React UI (Hydrated)"]:::client
    ClientState["React Context State"]:::state
    ClientData["Static Data (Bundled)"]:::data
    ClientLibs["Client Libraries"]:::lib
  end

  subgraph "Runtime: Next.js (Server/Edge)"
  direction TB
    NextRuntime["Next.js App Router\n(Rendering: SSR/SSG depends on route)"]:::server
    AppShellLayout["App Shell Layout\nlayout.tsx"]:::route
    GlobalsCss["Global Styles\nglobals.css"]:::route

    subgraph "Routes (src/app/*)"
    direction TB
      HomeRoute["Home Route '/' (page.tsx)"]:::route
      AboutRoute["About Route '/about' (page.tsx)"]:::route
      CollectionRoute["Collection Route '/collection' (page.tsx)"]:::route
      LoadingUI["Loading UI (loading.tsx)"]:::route
      NotFoundUI["Not Found UI (not-found.tsx)"]:::route
    end
  end

  subgraph "UI Components (src/components/ui/*)"
  direction TB
    Navbar["Navbar (navbar.tsx)"]:::ui
    CardsUI["Cards List (Cards.tsx)"]:::ui
    ScrollX["ScrollX Carousel (ScrollX.tsx)"]:::ui
    CategoryModal["Category Modal (categoryModal.tsx)"]:::ui
    FilterModal["Filter Modal (filterModal.tsx)"]:::ui
    Dropdown["Dropdown (dropdown.tsx)"]:::ui
    ContactForm["Contact/Feedback Form (contact.tsx)"]:::ui
  end

  subgraph "State Layer (src/contexts/*)"
  direction TB
    CategoryCtx["Category Context (useCategoryContext.tsx)"]:::state
    CategoryModalCtx["Category Modal Context (useCategoryModalContext.tsx)"]:::state
    FavoritesCtx["Favorites Context (useFavoriteCardsContext.tsx)"]:::state
    FilterButtonCtx["Filter Context (useFilterButtonContext.tsx)"]:::state
  end

  subgraph "Data Layer (src/data/* + public/*)"
  direction TB
    CardsDataset[("Cards Dataset (Cards.ts)")]:::data
    CategoriesDataset[("Categories Dataset (Categories.tsx)")]:::data
    IconsMapping[("Icons Mapping (Icons.tsx)")]:::data
    PublicIcons[("Public Icons Assets (public/icons)")]:::data
  end

  subgraph "Tooling / Build / CI"
  direction TB
    TailwindCfg["Tailwind Config (tailwind.config.ts)"]:::tool
    PostcssCfg["PostCSS Config (postcss.config.mjs)"]:::tool
    NextCfg["Next.js Config (next.config.mjs)"]:::tool
    TsCfg["TypeScript Config (tsconfig.json)"]:::tool
    EsLintCfg["ESLint Config (.eslintrc.json)"]:::tool
    GHA["GitHub Actions Workflow (nextjs.yml)"]:::ci
  end
end

EmailJS["EmailJS API (External)"]:::external
FramerMotion["Framer Motion"]:::lib
Sonner["Sonner (Toasts)"]:::lib
NextThemes["next-themes"]:::lib

%% =========================================================
%% Flows (keep vertical)
%% =========================================================
U -->|"browse/search/filter/favorites"| NextRuntime
NextRuntime -->|"serves_routes/layout_assets"| ClientUI
ClientUI -->|"hydrates_and_renders"| ClientUI

%% App Router composition
NextRuntime -->|"uses"| AppShellLayout
NextRuntime -->|"uses"| GlobalsCss
AppShellLayout -->|"wraps"| HomeRoute
AppShellLayout -->|"wraps"| AboutRoute
AppShellLayout -->|"wraps"| CollectionRoute
NextRuntime -->|"shows"| LoadingUI
NextRuntime -->|"shows"| NotFoundUI

%% Pages compose UI
HomeRoute -->|"renders"| Navbar
HomeRoute -->|"renders"| CardsUI
HomeRoute -->|"renders"| ScrollX
HomeRoute -->|"opens"| CategoryModal
HomeRoute -->|"opens"| FilterModal
HomeRoute -->|"uses"| Dropdown
HomeRoute -->|"renders"| ContactForm

AboutRoute -->|"renders"| Navbar
AboutRoute -->|"may_render"| ContactForm

CollectionRoute -->|"renders"| Navbar
CollectionRoute -->|"renders"| CardsUI

%% UI <-> Context
Navbar <-->|"reads/updates"| CategoryCtx
Navbar <-->|"reads/updates"| FavoritesCtx
Navbar <-->|"reads/updates"| FilterButtonCtx

CardsUI <-->|"reads/updates"| FavoritesCtx
CardsUI <-->|"reads"| CategoryCtx
CardsUI <-->|"reads"| FilterButtonCtx

CategoryModal <-->|"open/close"| CategoryModalCtx
CategoryModal <-->|"selects"| CategoryCtx

FilterModal <-->|"open/close"| FilterButtonCtx
Dropdown <-->|"updates"| CategoryCtx
Dropdown <-->|"updates"| FilterButtonCtx

%% UI -> Data store (static in-repo)
CardsUI -->|"loads_resources"| CardsDataset
CardsUI -->|"loads_taxonomy"| CategoriesDataset
Navbar -->|"loads_taxonomy"| CategoriesDataset
CategoryModal -->|"loads_taxonomy"| CategoriesDataset

Navbar -->|"loads_icons"| IconsMapping
CardsUI -->|"loads_icons"| IconsMapping
IconsMapping -->|"maps_to_assets"| PublicIcons

%% External integration (most accurate given no app/api)
ContactForm -->|"sends_email"| EmailJS
ContactForm -->|"toast_notifications"| Sonner

%% Libraries (support)
CategoryModal -->|"animations"| FramerMotion
FilterModal -->|"animations"| FramerMotion
CardsUI -->|"animations"| FramerMotion
Navbar -->|"theme_toggle/provider"| NextThemes
AppShellLayout -->|"theme_provider"| NextThemes

%% Tooling/CI relationships (dashed)
GHA -.->|"build/lint/typecheck"| NextCfg
GHA -.->|"build_styles"| TailwindCfg
GHA -.->|"build_styles"| PostcssCfg
GHA -.->|"typecheck"| TsCfg
GHA -.->|"lint"| EsLintCfg

%% =========================================================
%% Click Events (paths only; not shown in node labels)
%% =========================================================
click AppShellLayout "https://github.com/aibiansari/linkrary/blob/main/src/app/layout.tsx"
click GlobalsCss "https://github.com/aibiansari/linkrary/blob/main/src/app/globals.css"

click HomeRoute "https://github.com/aibiansari/linkrary/blob/main/src/app/page.tsx"
click AboutRoute "https://github.com/aibiansari/linkrary/blob/main/src/app/about/page.tsx"
click CollectionRoute "https://github.com/aibiansari/linkrary/blob/main/src/app/collection/page.tsx"
click LoadingUI "https://github.com/aibiansari/linkrary/blob/main/src/app/loading.tsx"
click NotFoundUI "https://github.com/aibiansari/linkrary/blob/main/src/app/not-found.tsx"

click Navbar "https://github.com/aibiansari/linkrary/blob/main/src/components/ui/navbar.tsx"
click CardsUI "https://github.com/aibiansari/linkrary/blob/main/src/components/ui/Cards.tsx"
click ScrollX "https://github.com/aibiansari/linkrary/blob/main/src/components/ui/ScrollX.tsx"
click CategoryModal "https://github.com/aibiansari/linkrary/blob/main/src/components/ui/categoryModal.tsx"
click FilterModal "https://github.com/aibiansari/linkrary/blob/main/src/components/ui/filterModal.tsx"
click Dropdown "https://github.com/aibiansari/linkrary/blob/main/src/components/ui/dropdown.tsx"
click ContactForm "https://github.com/aibiansari/linkrary/blob/main/src/components/ui/contact.tsx"

click CategoryCtx "https://github.com/aibiansari/linkrary/blob/main/src/contexts/useCategoryContext.tsx"
click CategoryModalCtx "https://github.com/aibiansari/linkrary/blob/main/src/contexts/useCategoryModalContext.tsx"
click FavoritesCtx "https://github.com/aibiansari/linkrary/blob/main/src/contexts/useFavoriteCardsContext.tsx"
click FilterButtonCtx "https://github.com/aibiansari/linkrary/blob/main/src/contexts/useFilterButtonContext.tsx"

click CardsDataset "https://github.com/aibiansari/linkrary/blob/main/src/data/Cards.ts"
click CategoriesDataset "https://github.com/aibiansari/linkrary/blob/main/src/data/Categories.tsx"
click IconsMapping "https://github.com/aibiansari/linkrary/blob/main/src/data/Icons.tsx"
click PublicIcons "https://github.com/aibiansari/linkrary/tree/main/public/icons"

click TailwindCfg "https://github.com/aibiansari/linkrary/blob/main/tailwind.config.ts"
click PostcssCfg "https://github.com/aibiansari/linkrary/blob/main/postcss.config.mjs"
click NextCfg "https://github.com/aibiansari/linkrary/blob/main/next.config.mjs"
click TsCfg "https://github.com/aibiansari/linkrary/blob/main/tsconfig.json"
click EsLintCfg "https://github.com/aibiansari/linkrary/blob/main/.eslintrc.json"
click GHA "https://github.com/aibiansari/linkrary/blob/main/.github/workflows/nextjs.yml"

%% =========================================================
%% Styles
%% =========================================================
classDef external fill:#ffe2e2,stroke:#c53030,stroke-width:1.5px,color:#1a202c
classDef server fill:#e6f0ff,stroke:#2b6cb0,stroke-width:1.5px,color:#1a202c
classDef client fill:#ebf8ff,stroke:#2c7a7b,stroke-width:1.5px,color:#1a202c
classDef route fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#111827
classDef ui fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#052e16
classDef state fill:#ffedd5,stroke:#ea580c,stroke-width:1.5px,color:#1a202c
classDef data fill:#f3e8ff,stroke:#7c3aed,stroke-width:1.5px,color:#1a202c
classDef lib fill:#ede9fe,stroke:#6d28d9,stroke-width:1.5px,color:#1f2937
classDef tool fill:#e5e7eb,stroke:#4b5563,stroke-width:1.2px,color:#111827
classDef ci fill:#fef9c3,stroke:#a16207,stroke-width:1.5px,color:#111827
```
