# joshua-sx/pjiae-360 architecture

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

- Interactive diagram: https://gitdiagram.com/joshua-sx/pjiae-360
- Repository: https://github.com/joshua-sx/pjiae-360

## Overview

##### Project Type and Purpose
- This is a single-page, full-stack web application—specifically the front-end of a digital employee appraisal platform (“Smartgoals 360”) built with React, TypeScript and Vite.
- It demonstrates an onboarding flow, dashboards, goal and appraisal management, authentication via Clerk, and client-side data fetching/caching with React Query.

##### File Structure
- Top-level files:
- index.html (Vite entry point)
- package.json, bun.lockb, tsconfig*.json, vite.config.ts (build, lint and type configurations)
- public/ (static assets, robots.txt)
- src/ subdirectories:
- components/ – all UI pieces, subdivided into page-level components (LandingPage, DashboardLayout, AppraisalsPage, etc.), domain modules (appraisals/, goals/, onboarding/, preview/), and a shared UI library (ui/ based on shadcn + Tailwind).
- pages/ – route entry components (Index.tsx, NotFound.tsx).
- hooks/ and contexts/ – custom React hooks (useRole, usePreviewSync, etc.) and context providers (PreviewContext).
- lib/ – API wrapper (api.ts) and utilities.
- types/ – shared TypeScript definitions.
- Configuration for ESLint, PostCSS, Tailwind, Vite.

##### Key Insights from the README
- Authentication: Clerk handles sign-in, user sessions.
- Data fetching: React Query for HTTP calls and caching.
- CSS: Tailwind + shadcn UI component library.
- Demo data: some modules use mockData.ts for previews.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Dev Tools
    subgraph "Build & Dev Tools"
        ViteDev["Vite Dev Server"]:::external
        ViteBuild["Vite Bundler"]:::external
        ConfigFiles["Config Files"]:::config
    end

    %% SPA in Browser
    subgraph "SPA (Browser)"
        direction TB
        Entry["SPA Entry: src/main.tsx"]:::ui
        AppRoot["App Root & Routing: src/App.tsx"]:::ui

        subgraph "Pages & Routing"
            direction TB
            Home["Home / Landing: src/pages/Index.tsx"]:::ui
            NotFound["404 Page: src/pages/NotFound.tsx"]:::ui
        end

        subgraph "Authentication"
            direction TB
            Protected["Auth Wrapper: src/components/ProtectedRoute.tsx"]:::ui
            SignIn["Sign-In Page: src/components/AuthPage.tsx"]:::ui
        end

        subgraph "Onboarding Module"
            direction TB
            OnboardFlow["Flow Container: src/components/onboarding/OnboardingFlow.tsx"]:::domain
            OnboardLogic["Logic: src/components/onboarding/OnboardingLogic.tsx"]:::domain
            OnboardRender["Renderer: src/components/onboarding/OnboardingRenderer.tsx"]:::domain
            OnboardTypes["Types: src/components/onboarding/OnboardingTypes.ts"]:::domain
            OnboardComp["Sub-components: src/components/onboarding/components/"]:::domain
        end

        subgraph "Dashboard Layer"
            direction TB
            DashLayout["Dashboard Layout: src/components/DashboardLayout.tsx"]:::domain
            DashContent["Dashboard Content: src/components/Dashboard.tsx"]:::domain
            Sidebar["Sidebar: src/components/AppSidebar.tsx"]:::domain
            Nav["Navigation: src/components/Navigation.tsx"]:::domain
        end

        subgraph "Goals Domain Module"
            direction TB
            GoalsPage["Goals Page: src/components/GoalsPage.tsx"]:::domain
            CreateGoal["Create Goal: src/components/CreateGoalPage.tsx"]:::domain
            ManagerDash["Manager Dashboard: src/components/goals/ManagerGoalsDashboard.tsx"]:::domain
            GoalsTypes["Types: src/components/goals/types.ts"]:::domain
            GoalsMock["Mock Data: src/components/goals/mockData.ts"]:::domain
            GoalsComp["Sub-components: src/components/goals/components/"]:::domain
        end

        subgraph "Appraisals Domain Module"
            direction TB
            AppraisalsPage["Appraisals Page: src/components/AppraisalsPage.tsx"]:::domain
            NewAppFlow["New Appraisal Flow: src/components/appraisals/EmployeeAppraisalFlow.tsx"]:::domain
            NewAppPage["New Appraisal Page: src/components/NewAppraisalPage.tsx"]:::domain
            AppList["Appraisals List: src/components/Appraisals.tsx"]:::domain
            ApprTypes["Types: src/components/appraisals/types.ts"]:::domain
            ApprMock["Mock Data: src/components/appraisals/mockData.ts"]:::domain
            ApprComp["Sub-components: src/components/appraisals/"]:::domain
        end

        subgraph "Preview / Demo Mode"
            direction TB
            PreviewIndex["Preview Index: src/components/preview/index.ts"]:::domain
            PreviewBanner["Preview Banner: src/components/preview/PreviewBanner.tsx"]:::domain
            RoleGuard["Role Guard: src/components/preview/RoleGuard.tsx"]:::domain
            RoleSwitch["Role Switcher: src/components/preview/RoleSwitcher.tsx"]:::domain
            PreviewButton["Preview Button: src/components/preview/PreviewButton.tsx"]:::domain
        end

        subgraph "Shared UI Library"
            direction TB
            SharedUI["UI Components: src/components/ui/"]:::ui
        end

        subgraph "Context & Hooks"
            direction TB
            Context["PreviewContext: src/contexts/PreviewContext.tsx"]:::data
            Hook1["usePreviewSync: src/hooks/usePreviewSync.tsx"]:::data
            Hook2["useRole: src/hooks/useRole.tsx"]:::data
            Hook3["use-toast: src/hooks/use-toast.ts"]:::data
            Hook4["use-mobile: src/hooks/use-mobile.tsx"]:::data
            Hook5["useScrollToTop: src/hooks/useScrollToTop.ts"]:::data
        end

        subgraph "Data Layer"
            direction TB
            APIWrapper["API Wrapper: src/lib/api.ts"]:::data
            Utils["Utils: src/lib/utils.ts"]:::data
            QueryCache["React Query Cache"]:::data
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Clerk["Clerk Auth Service"]:::external
        Backend["Backend API"]:::external
        CDN["Static Assets CDN"]:::external
    end

    %% Data Flow & Relationships
    Entry --> AppRoot
    AppRoot --> Home
    AppRoot --> NotFound
    AppRoot --> Protected
    Protected --> SignIn
    AppRoot --> OnboardFlow
    OnboardFlow --> OnboardLogic --> OnboardRender --> OnboardComp
    AppRoot --> DashLayout
    DashLayout --> DashContent
    DashLayout --> Sidebar --> Nav
    AppRoot --> GoalsPage --> CreateGoal --> ManagerDash --> GoalsComp
    AppRoot --> AppraisalsPage --> NewAppFlow --> NewAppPage --> AppList --> ApprComp
    AppRoot --> PreviewIndex --> PreviewBanner --> RoleGuard --> RoleSwitch --> PreviewButton
    AppRoot --> SharedUI
    OnboardLogic --> Context
    DashContent --> Hook1 & Hook2 & Hook3 & Hook4 & Hook5
    GoalsPage --> Hook2 & Hook3
    AppraisalsPage --> Hook2 & Hook3
    PreviewIndex --> Hook2
    Protected --> APIWrapper
    APIWrapper --> Backend
    APIWrapper --> QueryCache
    Utils --> APIWrapper
    Entry --> ViteDev
    ViteDev --> AppRoot
    ViteBuild --> AppRoot
    ConfigFiles --> ViteDev
    ConfigFiles --> ViteBuild
    CDN --> SharedUI

    %% Click Events
    click Entry "https://github.com/joshua-sx/pjiae-360/blob/main/src/main.tsx"
    click AppRoot "https://github.com/joshua-sx/pjiae-360/blob/main/src/App.tsx"
    click Home "https://github.com/joshua-sx/pjiae-360/blob/main/src/pages/Index.tsx"
    click NotFound "https://github.com/joshua-sx/pjiae-360/blob/main/src/pages/NotFound.tsx"
    click Protected "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/ProtectedRoute.tsx"
    click SignIn "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/AuthPage.tsx"
    click OnboardFlow "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/onboarding/OnboardingFlow.tsx"
    click OnboardLogic "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/onboarding/OnboardingLogic.tsx"
    click OnboardRender "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/onboarding/OnboardingRenderer.tsx"
    click OnboardTypes "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/onboarding/OnboardingTypes.ts"
    click DashLayout "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/DashboardLayout.tsx"
    click DashContent "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/Dashboard.tsx"
    click Sidebar "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/AppSidebar.tsx"
    click Nav "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/Navigation.tsx"
    click GoalsPage "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/GoalsPage.tsx"
    click CreateGoal "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/CreateGoalPage.tsx"
    click ManagerDash "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/goals/ManagerGoalsDashboard.tsx"
    click GoalsTypes "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/goals/types.ts"
    click GoalsMock "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/goals/mockData.ts"
    click AppraisalsPage "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/AppraisalsPage.tsx"
    click NewAppFlow "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/appraisals/EmployeeAppraisalFlow.tsx"
    click NewAppPage "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/NewAppraisalPage.tsx"
    click AppList "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/Appraisals.tsx"
    click ApprTypes "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/appraisals/types.ts"
    click ApprMock "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/appraisals/mockData.ts"
    click PreviewIndex "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/preview/index.ts"
    click PreviewBanner "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/preview/PreviewBanner.tsx"
    click RoleGuard "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/preview/RoleGuard.tsx"
    click RoleSwitch "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/preview/RoleSwitcher.tsx"
    click PreviewButton "https://github.com/joshua-sx/pjiae-360/blob/main/src/components/preview/PreviewButton.tsx"
    click SharedUI "https://github.com/joshua-sx/pjiae-360/tree/main/src/components/ui/"
    click Context "https://github.com/joshua-sx/pjiae-360/blob/main/src/contexts/PreviewContext.tsx"
    click Hook1 "https://github.com/joshua-sx/pjiae-360/blob/main/src/hooks/usePreviewSync.tsx"
    click Hook2 "https://github.com/joshua-sx/pjiae-360/blob/main/src/hooks/useRole.tsx"
    click Hook3 "https://github.com/joshua-sx/pjiae-360/blob/main/src/hooks/use-toast.ts"
    click Hook4 "https://github.com/joshua-sx/pjiae-360/blob/main/src/hooks/use-mobile.tsx"
    click Hook5 "https://github.com/joshua-sx/pjiae-360/blob/main/src/hooks/useScrollToTop.ts"
    click APIWrapper "https://github.com/joshua-sx/pjiae-360/blob/main/src/lib/api.ts"
    click Utils "https://github.com/joshua-sx/pjiae-360/blob/main/src/lib/utils.ts"

    %% Styles
    classDef ui fill:#b3cde0,stroke:#03396c,color:#03396c
    classDef domain fill:#ccebc5,stroke:#006d2c,color:#006d2c
    classDef data fill:#fed9a6,stroke:#f47721,color:#f47721
    classDef external fill:#fbb4ae,stroke:#b10026,color:#b10026
    classDef config fill:#d9d9d9,stroke:#666,color:#333
```
