# klhong124/builtbypixel-code-test architecture

> Architecture diagram of the GitHub repository klhong124/builtbypixel-code-test, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/klhong124/builtbypixel-code-test
- Repository: https://github.com/klhong124/builtbypixel-code-test

## Overview

##### Project Type and Purpose
- A frontend-centric, full-stack-style application built on Next.js 15 (App Router).
- Purpose: A responsive Task Management UI that fetches and mutates data via a remote GraphQL service, with server-side rendering (SSR), client hydration, theme support, and analytics.

##### Main Architectural Components
- Browser / Client: Renders React UI, handles user events, client-side routing.
- Next.js Server (App Router):
– Handles SSR/SSG of pages (app/layout.tsx, app/page.tsx, tasks pages).
– Exposes static assets (public/, styles/) and generates HTML on-the-fly.
- React Components:
– Feature modules under app/tasks (layout, page, dynamic [status] routes, subcomponents).
– Shared UI modules under components/ui.
– Global providers (components/theme-provider.tsx).
- Data Layer:
– Apollo Client (utils/apolloClient.ts) for GraphQL operations.
– Generated GraphQL types (types/graphql.d.ts via codegen.ts).
– GraphQL query documents (app/tasks/graphql/*.gql).
- External Services:
– Remote GraphQL API endpoint (environment variable).
– Vercel Analytics for performance tracking.
– Static asset CDN (Vercel/public).

##### Interactions and Data Flow
- User opens browser → requests a route (e.g., /tasks/new).
- Next.js server performs SSR: imports page component, runs getServerSideProps or React server components, executes Apollo Client query against GraphQL API, renders HTML.
- HTML + serialized Apollo cache → sent to browser; React hydrates.
- Client-side interactions (filter toggles, sorting) trigger Apollo Client queries to GraphQL, update in-memory cache, re-render TaskList.
- Analytics events sent to Vercel during navigation and interactions.

##### Architectural Patterns and Principles
- Feature-based directories (app/tasks) for encapsulation.
- Server components vs. client components separation using Next.js App Router.
- Atomic UI design via shadcn/ui in components/ui.
- Type-safe GraphQL workflow: codegen → TypeScript types.
- Responsive/mobile-first + dark/light theme orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Frontend Layer" 
        direction TB
        Browser["Browser / Client"]:::ext
        subgraph "Next.js Server (App Router)" 
            direction TB
            RootLayout["app/layout.tsx"]:::ui
            HomePage["app/page.tsx"]:::ui
            subgraph "Tasks Feature (app/tasks)" 
                direction TB
                TasksLayout["layout.tsx"]:::ui
                TasksIndex["page.tsx"]:::ui
                TasksStatus["[status]/page.tsx"]:::ui
                subgraph "Task Subcomponents (app/tasks/components)" 
                    direction TB
                    TaskLoading["Loading"]:::ui
                    TaskError["Error"]:::ui
                    TaskEmpty["Empty"]:::ui
                    TaskCard["TaskCard"]:::ui
                    TaskFilter["TaskFilter"]:::ui
                    TaskHeader["TaskHeader"]:::ui
                    TaskListComp["TaskList"]:::ui
                    TaskSidebar["TaskSidebar"]:::ui
                end
                TasksHooks["hooks/useTasks.ts"]:::data
                TasksUtils["utils/tasks.constraint.ts,\nutils/tasks.helpers.ts"]:::data
                subgraph "GraphQL Documents" 
                    direction TB
                    GqlGetTotal["GetTotalTask.gql"]:::data
                    GqlList["TaskList.gql"]:::data
                    TasksQuery["tasks.query.ts"]:::data
                end
            end
        end
        ThemeProvider["components/theme-provider.tsx"]:::ui
        ThemeToggle["components/theme-toggle.tsx"]:::ui
        SharedUI["components/ui"]:::ui
    end

    subgraph "Data Layer" 
        direction TB
        ApolloClient["utils/apolloClient.ts"]:::data
        GraphQLTypes["types/graphql.d.ts"]:::data
        Codegen["codegen.ts"]:::data
    end

    subgraph "External Services & Assets" 
        direction TB
        GraphQLAPI["Remote GraphQL API"]:::ext
        Analytics["Vercel Analytics"]:::ext
        CDN["public/ (Static Assets CDN)"]:::ext
        Styles["styles/globals.css"]:::ui
    end

    subgraph "Config & Build" 
        direction TB
        NextConfig["next.config.ts"]:::data
        PostCSS["postcss.config.mjs"]:::data
        TSConfig["tsconfig.json"]:::data
    end

    %% SSR Flow
    Browser -->|"HTTP Request"| RootLayout
    RootLayout --> HomePage
    HomePage --> TasksLayout
    TasksLayout --> TasksIndex
    TasksIndex -->|"Server Component Query"| ApolloClient
    ApolloClient -->|"GraphQL Fetch"| GraphQLAPI
    GraphQLAPI -->|"Response"| ApolloClient
    ApolloClient --> TasksIndex
    TasksIndex --> Browser
    Browser -->|"Hydrate UI"| TaskListComp

    %% CSR Flow
    Browser -->|"User Interaction"| ApolloClient
    ApolloClient -->|"GraphQL Fetch"| GraphQLAPI
    GraphQLAPI --> ApolloClient
    ApolloClient --> TaskListComp

    %% Analytics & Assets
    Browser -->|"Send Events"| Analytics
    Browser -->|"Load Styles"| Styles
    Browser -->|"Load Assets"| CDN

    %% Codegen Workflow
    Codegen --> GraphQLTypes

    %% Config Dependencies
    NextConfig --> RootLayout
    PostCSS --> Styles
    TSConfig --> RootLayout

    %% Click Events
    click RootLayout "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/layout.tsx"
    click HomePage "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/page.tsx"
    click TasksLayout "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/layout.tsx"
    click TasksIndex "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/page.tsx"
    click TasksStatus "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/[status]/page.tsx"
    click TaskLoading "https://github.com/klhong124/builtbypixel-code-test/tree/main/app/tasks/components"
    click TaskError "https://github.com/klhong124/builtbypixel-code-test/tree/main/app/tasks/components"
    click TaskEmpty "https://github.com/klhong124/builtbypixel-code-test/tree/main/app/tasks/components"
    click TaskCard "https://github.com/klhong124/builtbypixel-code-test/tree/main/app/tasks/components"
    click TaskFilter "https://github.com/klhong124/builtbypixel-code-test/tree/main/app/tasks/components"
    click TaskHeader "https://github.com/klhong124/builtbypixel-code-test/tree/main/app/tasks/components"
    click TaskListComp "https://github.com/klhong124/builtbypixel-code-test/tree/main/app/tasks/components"
    click TaskSidebar "https://github.com/klhong124/builtbypixel-code-test/tree/main/app/tasks/components"
    click GqlGetTotal "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/graphql/GetTotalTask.gql"
    click GqlList "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/graphql/TaskList.gql"
    click TasksQuery "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/graphql/tasks.query.ts"
    click TasksHooks "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/hooks/useTasks.ts"
    click TasksUtils "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/utils/tasks.constraint.ts"
    click TasksUtils "https://github.com/klhong124/builtbypixel-code-test/blob/main/app/tasks/utils/tasks.helpers.ts"
    click ThemeProvider "https://github.com/klhong124/builtbypixel-code-test/blob/main/components/theme-provider.tsx"
    click ThemeToggle "https://github.com/klhong124/builtbypixel-code-test/blob/main/components/theme-toggle.tsx"
    click SharedUI "https://github.com/klhong124/builtbypixel-code-test/tree/main/components/ui"
    click ApolloClient "https://github.com/klhong124/builtbypixel-code-test/blob/main/utils/apolloClient.ts"
    click GraphQLTypes "https://github.com/klhong124/builtbypixel-code-test/blob/main/types/graphql.d.ts"
    click Codegen "https://github.com/klhong124/builtbypixel-code-test/blob/main/codegen.ts"
    click Styles "https://github.com/klhong124/builtbypixel-code-test/blob/main/styles/globals.css"
    click CDN "https://github.com/klhong124/builtbypixel-code-test/tree/main/public/"
    click NextConfig "https://github.com/klhong124/builtbypixel-code-test/blob/main/next.config.ts"
    click PostCSS "https://github.com/klhong124/builtbypixel-code-test/blob/main/postcss.config.mjs"
    click TSConfig "https://github.com/klhong124/builtbypixel-code-test/blob/main/tsconfig.json"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0B5FFF,color:#0B5FFF
    classDef data fill:#E0FFDD,stroke:#1D7F00,color:#1D7F00
    classDef ext fill:#F0F0F0,stroke:#888888,color:#888888
```
