# jimmyhealer/shiftplanner architecture

> Architecture diagram of the GitHub repository jimmyhealer/shiftplanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jimmyhealer/shiftplanner
- Repository: https://github.com/jimmyhealer/shiftplanner

## Overview

##### Project type and purpose
- This is a Next.js-based full-stack application focused on rendering a shift-planning Gantt chart UI. It’s bootstrapped with Create-Next-App, uses React/TypeScript on the front end, and currently relies on mock data.

##### File structure
- Top-level config: next.config.ts, tsconfig.json, eslint.config.mjs, postcss.config.mjs, bun.lock
- Public assets: /public
- App entry: /src/app (Next.js App Router: layout.tsx, page.tsx, globals.css, gantt.css)
- Component hierarchy: /src/components (ErrorAlert, GanttChart, and subfolder /gantt for AssignmentBlock, DriverRow, ShiftLegend, TimelineHeader)
- State management: /src/context/ShiftPlannerContext.tsx
- Hooks: /src/hooks/useAssignmentOperations.ts
- Data: /src/data/mockData.ts (placeholder for real API)
- Utilities: /src/utils/ganttUtils.ts, /src/utils/timeline/timeUtils.ts
- Types: /src/types/index.ts

##### README for additional insights
- Confirms a Next.js front-end with automatic font optimization (Geist)
- No backend/API folder present, so it’s currently front-end only with mock data

##### Main components and relationships
a. Components
- Next.js Server / Node Runtime (Edge functions or SSR)
- React App (root at src/app/layout.tsx)
- ShiftPlannerContext Provider
- Page Layer (/src/app/page.tsx)
- Gantt Chart Module (/src/components/GanttChart.tsx + /components/gantt/*)
- Hook Layer (/src/hooks/useAssignmentOperations.ts)
- Data Layer (mockData or future API)
- Utility Layer (ganttUtils, timeUtils)
- Static Assets (public folder, fonts)
- Config & Build Tools (Bun, PostCSS, ESLint)

b. Interactions and data flow
1. Browser → Next.js Server: initial request
2. Next.js SSR/Hydration → React App Root
3. App Root initializes ShiftPlannerContext → provides state & operations hook
4. Page.tsx pulls context and passes assignments to GanttChart
5. GanttChart and subcomponents call ganttUtils/timeUtils for layout math
6. useAssignmentOperations hook reads/writes assignments (mockData or future API calls)
7. UI updates in client; errors surface via ErrorAlert

c. Architectural patterns & principles
- Component-based UI (Break Gantt into reusable blocks: DriverRow, AssignmentBlock, etc.)
- Context API for global state (shift assignments)
- Custom React Hook for encapsulating data operations
- Separation of concerns: layout (CSS), data (mockData/utilities), state, and view

d. Key technologies
- Next.js App Router (app/layout.tsx, page.tsx)
- React + TypeScript
- Context API & Custom Hooks
- PostCSS, CSS modules (globals.css, gantt.css)
- Vercel Edge/SSR (deployment target)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Entity
    Browser["Browser"]:::external

    %% Framework/Runtime Layer
    NextJS["Next.js Server / Node Runtime"]:::framework
    ReactApp["React App Root"]:::framework
    Page["Page Layer"]:::framework

    %% Application Logic Layer
    Context["ShiftPlannerContext Provider"]:::logic
    Hook["useAssignmentOperations Hook"]:::logic

    %% UI Components Layer
    subgraph "Gantt Chart Module"
        GanttModule["GanttChart"]:::ui
        AssignmentBlock["AssignmentBlock"]:::ui
        DriverRow["DriverRow"]:::ui
        ShiftLegend["ShiftLegend"]:::ui
        TimelineHeader["TimelineHeader"]:::ui
        ErrorAlert["ErrorAlert"]:::ui
    end

    %% Utilities and Data Layer
    ganttUtils["ganttUtils"]:::utils
    timeUtils["timeUtils"]:::utils
    Data["Mock Data Store"]:::data

    %% Static Assets and Config
    Static["Static Assets"]:::static
    Config["Config & Build Tools"]:::config

    %% Connections
    Browser -->|"SSR request"| NextJS
    NextJS -->|"Serves React App"| ReactApp
    ReactApp -->|"init context"| Context
    Context -->|"provides state"| Page
    Page -->|"renders"| GanttModule
    Page -->|"error handling"| ErrorAlert
    GanttModule -->|"uses layout math"| ganttUtils
    GanttModule -->|"uses time calculations"| timeUtils
    GanttModule -->|"renders timeline header"| TimelineHeader
    GanttModule -->|"renders driver rows"| DriverRow
    DriverRow -->|"renders assignment blocks"| AssignmentBlock
    Context -->|"provides operations"| Hook
    Hook -->|"reads/writes assignments"| Data
    NextJS --> Static
    NextJS --> Config

    %% Click Events
    click NextJS "https://github.com/jimmyhealer/shiftplanner/blob/main/next.config.ts"
    click ReactApp "https://github.com/jimmyhealer/shiftplanner/blob/main/src/app/layout.tsx"
    click Page "https://github.com/jimmyhealer/shiftplanner/blob/main/src/app/page.tsx"
    click Context "https://github.com/jimmyhealer/shiftplanner/blob/main/src/context/ShiftPlannerContext.tsx"
    click GanttModule "https://github.com/jimmyhealer/shiftplanner/blob/main/src/components/GanttChart.tsx"
    click AssignmentBlock "https://github.com/jimmyhealer/shiftplanner/blob/main/src/components/gantt/AssignmentBlock.tsx"
    click DriverRow "https://github.com/jimmyhealer/shiftplanner/blob/main/src/components/gantt/DriverRow.tsx"
    click ShiftLegend "https://github.com/jimmyhealer/shiftplanner/blob/main/src/components/gantt/ShiftLegend.tsx"
    click TimelineHeader "https://github.com/jimmyhealer/shiftplanner/blob/main/src/components/gantt/TimelineHeader.tsx"
    click Hook "https://github.com/jimmyhealer/shiftplanner/blob/main/src/hooks/useAssignmentOperations.ts"
    click Data "https://github.com/jimmyhealer/shiftplanner/blob/main/src/data/mockData.ts"
    click ganttUtils "https://github.com/jimmyhealer/shiftplanner/blob/main/src/utils/ganttUtils.ts"
    click timeUtils "https://github.com/jimmyhealer/shiftplanner/blob/main/src/utils/timeline/timeUtils.ts"
    click Static "https://github.com/jimmyhealer/shiftplanner/tree/main/public/"
    click Config "https://github.com/jimmyhealer/shiftplanner/blob/main/bun.lock"
    click Config "https://github.com/jimmyhealer/shiftplanner/blob/main/postcss.config.mjs"
    click Config "https://github.com/jimmyhealer/shiftplanner/blob/main/eslint.config.mjs"
    click Config "https://github.com/jimmyhealer/shiftplanner/blob/main/tsconfig.json"

    %% Styles
    classDef framework fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ui fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef utils fill:#FFDAB9,stroke:#333,stroke-width:1px
    classDef data fill:#FFDAB9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef static fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef config fill:#F5F5F5,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
