# chiazhe/tan-stack-table architecture

> Architecture diagram of the GitHub repository chiazhe/tan-stack-table, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chiazhe/tan-stack-table
- Repository: https://github.com/chiazhe/tan-stack-table

## Overview

##### Project Type and Purpose
- This is a full-stack demo application illustrating server-side pagination, column filtering, and sorting using TanStack Table (React Table) and TanStack Query (React Query).
- It comprises three main parts:
- A lightweight Express.js backend serving mock user data from a JSON file.
- A ReactJS (Vite) frontend.
- A Next.js frontend (App Router).

##### File Structure Breakdown
- Root
– README.md (overview & setup)
– backend/ (Express API)
– frontend-nextjs/ (Next.js App Router project)
– frontend/ (ReactJS + Vite project)
- backend/
– server.js: Express server exposes REST endpoint (e.g., GET /users) that implements pagination, filtering, sorting based on query parameters.
– MOCK_DATA.json: array of user objects (simulates database).
– package.json: Node dependencies (express, cors, etc.)
- frontend-nextjs/
– app/: Next.js App Router pages and layout (page.tsx fetches data).
– api/useGetUsers.ts: custom hook wrapping TanStack Query to call the backend.
– components/: TanStack Table components (basic table, filters, pagination, sorting) + shared UI primitives (button, input, table, pagination controls).
– hooks/useDebounce.ts, lib/utils.ts, types/*.ts, Tailwind + PostCSS config.
- frontend/
– src/main.tsx: ReactDOM render.
– src/api/useGetUsers.ts: hook using TanStack Query.
– src/components/: identical TanStack Table components & UI primitives.
– src/hooks/useDebounce.ts, src/lib/utils.ts, src/types/*.ts, Vite config, Tailwind.

##### Key Architectural Patterns
- Client-Server separation: React/Next frontends communicate via REST API.
- Reusable UI and table-concern components: All table logic broken into composable components (sorting, filtering, pagination).
- Single source of truth for data fetching: TanStack Query handles caching, refetching, and query key management.
- Configuration: Tailwind CSS for styling, TypeScript for typesafety.

A. Data Layer
- MOCK_DATA.json (simulated database)
B. Backend/API Layer
- Express Server (server.js)
- GET /users endpoint (accepts page, size, sort, filter queries)
C. Frontend Applications (side by side or as interchangeable clients)
1. ReactJS (Vite) Client
- API Hook (useGetUsers)
- TanStack Query Client
- Table Components (BasicTable, Sorting, Filtering, Pagination)
- UI Primitives (Button, Input, Table, PaginationControls)
2. Next.js Client
- App Router page (fetches data in React server/client component)
- API Hook (useGetUsers)
- Same TanStack Table Components & UI Primitives
D. External / Dev Tools (optional)
- TanStack Table & Query libraries
- Tailwind CSS
- Vite and Next.js build pipelines

##### Relationships and Data Flow
1. On user interaction (change page, sort, filter), the frontend hook constructs a query.
2. TanStack Query issues HTTP GET /users?page=X&limit=Y&sort=…&filter=… to Express server.
3. Express server reads MOCK_DATA.json, applies pagination, sorting, filtering logic, then returns JSON.
4. TanStack Query receives response, caches results, triggers UI rerender in Table components.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Clients Layer
    subgraph "Frontend Clients"
        direction TB
        subgraph "ReactJS (Vite Client)" 
            direction TB
            ReactQueryClient["TanStack Query Client"]:::frontend
            ReactHook["useGetUsers Hook"]:::frontend
            ReactHook -->|"fetch users"| ExpressServer
            ReactQueryClient --> ReactHook
            subgraph "Table Components"
                direction TB
                ReactBasicTable["BasicTable"]:::frontend
                ReactFilterComp["Filtering Component"]:::frontend
                ReactSortingComp["Sorting Component"]:::frontend
                ReactPaginationComp["Pagination Component"]:::frontend
                ReactPaginationNav["Pagination Nav"]:::frontend
                ReactTableLayout["Table Layout"]:::frontend
            end
            subgraph "UI Primitives"
                direction TB
                ReactButton["Button"]:::frontend
                ReactInput["Input"]:::frontend
                ReactLabel["Label"]:::frontend
                ReactSelect["Select"]:::frontend
                ReactTableContainer["Table Container"]:::frontend
                ReactPaginationUI["Pagination Controls"]:::frontend
            end
            subgraph "Utils & Hooks"
                direction TB
                ReactDebounce["useDebounce Hook"]:::frontend
                ReactUtils["Utils"]:::frontend
            end
            %% interactions
            ReactBasicTable -->|"user interacts"| ReactHook
            ReactFilterComp --> ReactHook
            ReactSortingComp --> ReactHook
            ReactPaginationComp --> ReactHook
            ReactPaginationNav --> ReactHook
            ReactTableLayout --> ReactHook
        end

        subgraph "Next.js (App Router Client)"
            direction TB
            NextLayout["layout.tsx"]:::frontend
            NextPage["page.tsx"]:::frontend
            NextQueryClient["TanStack Query Client"]:::frontend
            NextHook["useGetUsers Hook"]:::frontend
            NextQueryClient --> NextHook
            NextHook -->|"fetch users"| ExpressServer
            subgraph "Table Components"
                direction TB
                NextBasicTable["BasicTable"]:::frontend
                NextFilterComp["Filtering Component"]:::frontend
                NextSortingComp["Sorting Component"]:::frontend
                NextPaginationComp["Pagination Component"]:::frontend
                NextPaginationNav["Pagination Nav"]:::frontend
                NextTableLayout["Table Layout"]:::frontend
            end
            subgraph "UI Primitives"
                direction TB
                NextButton["Button"]:::frontend
                NextInput["Input"]:::frontend
                NextLabel["Label"]:::frontend
                NextTableContainer["Table Container"]:::frontend
                NextPaginationUI["Pagination Controls"]:::frontend
            end
            subgraph "Utils & Hooks"
                direction TB
                NextDebounce["useDebounce Hook"]:::frontend
                NextUtils["Utils"]:::frontend
            end
            %% interactions
            NextBasicTable -->|"user interacts"| NextHook
            NextFilterComp --> NextHook
            NextSortingComp --> NextHook
            NextPaginationComp --> NextHook
            NextPaginationNav --> NextHook
            NextTableLayout --> NextHook
        end
    end

    %% Backend/API Layer
    ExpressServer["Express Server (GET /users)"]:::api
    ExpressServer -->|"reads data"| MockData

    %% Data Layer
    MockData["MOCK_DATA.json"]:::data

    %% Data flow response
    ExpressServer -->|"users JSON"| ReactHook
    ExpressServer -->|"users JSON"| NextHook

    %% Click Events - ReactJS
    click ReactHook "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/api/useGetUsers.ts"
    click ReactQueryClient "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/main.tsx"
    click ReactBasicTable "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/TanStackBasicTable.tsx"
    click ReactFilterComp "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/TanStackBasicTableFilterComponent.tsx"
    click ReactSortingComp "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/TanStackBasicTableSortingComponent.tsx"
    click ReactPaginationComp "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/TanStackBasicTablePaginationComponent.tsx"
    click ReactPaginationNav "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/TanStackBasicTablePaginationNavigationComponent.tsx"
    click ReactTableLayout "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/TanStackBasicTableTableComponent.tsx"
    click ReactButton "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/ui/button.tsx"
    click ReactInput "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/ui/input.tsx"
    click ReactLabel "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/ui/label.tsx"
    click ReactSelect "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/ui/select.tsx"
    click ReactTableContainer "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/ui/table.tsx"
    click ReactPaginationUI "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/components/ui/pagination.tsx"
    click ReactDebounce "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/hooks/useDebounce.ts"
    click ReactUtils "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/lib/utils.ts"

    %% Click Events - ReactTS Types
    click TableTypes "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/types/Table.ts"
    click UserTypes "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/types/Users.ts"

    %% Click Events - React App shell
    click MainEntry "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/main.tsx"
    click RootComponent "https://github.com/chiazhe/tan-stack-table/blob/main/frontend/src/App.tsx"

    %% Click Events - Next.js
    click NextLayout "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/app/layout.tsx"
    click NextPage "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/app/page.tsx"
    click NextHook "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/api/useGetUsers.ts"
    click NextBasicTable "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/TanStackTable/TanStackBasicTable.tsx"
    click NextFilterComp "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/TanStackTable/TanStackBasicTableFilterComponent.tsx"
    click NextSortingComp "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/TanStackTable/TanStackBasicTableSortingComponent.tsx"
    click NextPaginationComp "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/TanStackTable/TanStackBasicTablePaginationComponent.tsx"
    click NextPaginationNav "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/TanStackTable/TanStackBasicTablePaginationNavigationComponent.tsx"
    click NextTableLayout "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/TanStackTable/TanStackBasicTableTableComponent.tsx"
    click NextButton "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/ui/button.tsx"
    click NextInput "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/ui/input.tsx"
    click NextLabel "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/ui/label.tsx"
    click NextTableContainer "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/ui/table.tsx"
    click NextPaginationUI "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/components/ui/pagination.tsx"
    click NextDebounce "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/hooks/useDebounce.ts"
    click NextUtils "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/lib/utils.ts"
    click NextTableTypes "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/types/Table.ts"
    click NextUserTypes "https://github.com/chiazhe/tan-stack-table/blob/main/frontend-nextjs/types/Users.ts"

    %% Click Events - Backend & Data
    click ExpressServer "https://github.com/chiazhe/tan-stack-table/blob/main/backend/server.js"
    click MockData "https://github.com/chiazhe/tan-stack-table/blob/main/backend/MOCK_DATA.json"

    %% Styles
    classDef data fill:#cce5ff,stroke:#0056b3,stroke-width:2px
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px,stroke-dasharray: 5 5
    classDef frontend fill:#fff3cd,stroke:#856404,stroke-width:2px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px,stroke-dasharray: 2 2
```
