# akassh9/my-canvas architecture

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

- Interactive diagram: https://gitdiagram.com/akassh9/my-canvas
- Repository: https://github.com/akassh9/my-canvas

## Overview

##### Project type and purpose
- This is a Next.js 15–based, client-only React “interactive foresight terminal” that simulates a macOS-style archive computer circa 2040.
- The server’s only role is to ship static assets (JS/CSS/images) and handle two routes: the home UI and a CSR‐only `/history` page embedding Issuu.

##### File structure
- Top level:
- components/ – reusable React widgets (DraggableWindow, MacMenuBar, PreviewWindow, TextEditWindow, MobileWarning)
- data/ – static TypeScript modules (`healthContent.ts`, `educationContent.ts`, `entertainmentContent.ts`) defining the ForesightContent domain model
- public/images – 300+ headline tiles and one “archive computer” video
- src/app/ – Next.js App Router structure:
– page.tsx (HomeClient orchestrator)
– history/page.tsx + HistoryClient.tsx
– api/simulate/route.ts (simulated API endpoint)
– globals.css + route‐scoped CSS
- hooks/, types/, styles/, config files (eslint.config.mjs, next.config.ts, postcss.config.mjs, tsconfig.json)
- Key patterns:
- Single‐page drag-and-drop window manager driven by top-level React state (no Redux)
- Pure static data look-up tables for headlines and scenario draggables
- CSR-only `/history` page with dynamic import + Suspense
- Animation via Framer Motion and manual text‐typing loops

##### Extract README insights
- Mission: build an interactive terminal with draggable macOS windows; all UI logic lives client-side.
- Domain model: one ForesightContent interface implemented in three data files; no business logic outside of TextEditWindow.
- Global state atoms: selectedCategory, selectedOption, happenedMode, hoveredHappened, happenedScenario, zCounter.
- Window registry: ~350 entries mapping keys to positions, sizes, types.
- Tech stack: Next.js 15, React 18, TypeScript, Tailwind v4, Framer Motion, react-draggable, Vercel analytics.

- Infrastructure Layer
– Vercel (hosting + analytics)
– Next.js Server (static file dispatcher)
- Frontend Shell (Next.js App)
– App Router → Layout.tsx → Nav/Menu bar → HomeClient or HistoryClient
- UI Component Layer
– MacMenuBar (menu gating, callbacks)
– DraggableWindow manager + global zIndex counter
– TextEditWindow (terminal state‐machine, typing, option/happened modes)
– PreviewWindow (image viewer stub)
– MobileWarning (fallback UI)
- Data Layer
– Static content modules (`data/*.ts`, `src/data/windows.ts`)
– Window/Headline registries and filtering matrices
- Assets & Styles
– public/images/**, video, fonts
– Tailwind CSS, mac-window.css
- External Integrations
– Issuu iframe (History page)
– @vercel/analytics, @vercel/speed-insights

- Vercel → Next.js Server → client browser
- Browser loads App Shell → Layout → renders MacMenuBar + HomeClient or HistoryClient
- HomeClient maintains global React state, reads static Data Layer → passes props into DraggableWindow/TextEditWindow
- User events (menu clicks, drags, keyboard nav) flow into component callbacks → update React state → re-render windows + content
- Animations triggered inside components via Framer Motion
- HistoryClient dynamically loads Issuu embed (Suspense)

c. Architectural patterns/design principles:
- Component‐centric UI with clearly separated “orchestrator” (page.tsx) vs. “leaf” components
- Single source of truth: top‐level React state atoms instead of global store
- Pure data modules: ForesightContent and window registries are immutable look-up tables
- CSR vs. SSG: Home is SSG/SSR, History is forced CSR (dynamic + Suspense)

d. Key technologies and libraries to annotate:
- Next.js App Router (app/layout.tsx, dynamic routing)
- React 18 + TypeScript types for ForesightContent & WindowConfig
- Tailwind CSS & custom mac-window.css
- Framer Motion `<AnimatePresence>` + motion.div
- react-draggable for window dragging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        Vercel["Vercel Hosting & Analytics"]:::infrastructure
        NextServer["Next.js Server\n(static assets & routing)"]:::infrastructure
    end

    %% App Shell & Router
    subgraph "App Shell & Router"
        direction TB
        Layout["App Router & Layout"]:::appshell
        HomePage["Home Page Orchestrator\npage.tsx & HomeClient.tsx"]:::appshell
        HistoryPage["History Page Orchestrator\nhistory/page.tsx & HistoryClient.tsx"]:::appshell
        APISim["API Simulation Endpoint"]:::appshell
    end

    %% UI Components
    subgraph "UI Component Layer"
        direction TB
        MenuBar["MacMenuBar"]:::ui
        Draggable["DraggableWindow Manager"]:::ui
        TextEdit["TextEditWindow\n(typing state-machine)"]:::ui
        Preview["PreviewWindow"]:::ui
        MobileWarn["MobileWarning"]:::ui
        SimulationWnd["SimulationWindow Stub"]:::ui
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ForesightModel["ForesightContent Model"]:::data
        Education["educationContent.ts"]:::data
        Entertainment["entertainmentContent.ts"]:::data
        Health["healthContent.ts"]:::data
        WindowRegistry["Window Registry Definitions"]:::data
    end

    %% Assets & Styles
    subgraph "Assets & Styles"
        direction TB
        GlobalsCSS["globals.css"]:::assets
        MacCSS["mac-window.css"]:::assets
        PublicAssets["public/images & video"]:::assets
    end

    %% External Services
    subgraph "External Integrations"
        direction TB
        Issuu["Issuu Iframe"]:::external
        VercelAnalytics["@vercel/analytics & speed-insights"]:::external
    end

    %% Connections
    Vercel --> NextServer
    NextServer --> Browser["Client Browser"]
    Browser --> Layout
    Layout --> HomePage
    Layout --> HistoryPage
    Layout --> APISim
    HomePage --> MenuBar
    HomePage --> Draggable
    HomePage --> TextEdit
    HomePage --> Preview
    HomePage --> SimulationWnd
    HomePage --> MobileWarn
    HomePage --> ForesightModel
    HomePage --> Education
    HomePage --> Entertainment
    HomePage --> Health
    HomePage --> WindowRegistry
    HistoryPage --> Issuu
    APISim --> SimulationWnd
    VercelAnalytics --> NextServer
    Draggable --> WindowRegistry
    TextEdit --> ForesightModel
    Preview --> PublicAssets
    MenuBar --> Draggable
    MenuBar --> TextEdit

    Browser -->|"user events"| MenuBar
    MenuBar -->|"onClick → spawn window"| Draggable
    Draggable -->|"bringToFront → bump zCounter"| TextEdit
    TextEdit -->|"reads content"| ForesightModel
    Preview -->|"loads media"| PublicAssets

    HistoryPage -->|"dynamic import + Suspense"| Issuu

    %% Click Events
    click NextServer "https://github.com/akassh9/my-canvas/blob/main/next.config.ts"
    click Layout "https://github.com/akassh9/my-canvas/blob/main/src/app/layout.tsx"
    click HomePage "https://github.com/akassh9/my-canvas/blob/main/src/app/page.tsx"
    click HomePage "https://github.com/akassh9/my-canvas/blob/main/src/app/HomeClient.tsx"
    click HistoryPage "https://github.com/akassh9/my-canvas/blob/main/src/app/history/page.tsx"
    click HistoryPage "https://github.com/akassh9/my-canvas/blob/main/src/app/history/HistoryClient.tsx"
    click APISim "https://github.com/akassh9/my-canvas/blob/main/src/app/api/simulate/route.ts"
    click MenuBar "https://github.com/akassh9/my-canvas/blob/main/components/MacMenuBar.tsx"
    click Draggable "https://github.com/akassh9/my-canvas/blob/main/components/DraggableWindow.tsx"
    click TextEdit "https://github.com/akassh9/my-canvas/blob/main/components/TextEditWindow.tsx"
    click Preview "https://github.com/akassh9/my-canvas/blob/main/components/PreviewWindow.tsx"
    click MobileWarn "https://github.com/akassh9/my-canvas/blob/main/components/MobileWarning.tsx"
    click SimulationWnd "https://github.com/akassh9/my-canvas/blob/main/components/SimulationWindow.tsx"
    click ForesightModel "https://github.com/akassh9/my-canvas/blob/main/data/foresightContent.ts"
    click Education "https://github.com/akassh9/my-canvas/blob/main/data/educationContent.ts"
    click Entertainment "https://github.com/akassh9/my-canvas/blob/main/data/entertainmentContent.ts"
    click Health "https://github.com/akassh9/my-canvas/blob/main/data/healthContent.ts"
    click WindowRegistry "https://github.com/akassh9/my-canvas/blob/main/src/data/windows.ts"
    click GlobalsCSS "https://github.com/akassh9/my-canvas/blob/main/src/app/globals.css"
    click MacCSS "https://github.com/akassh9/my-canvas/blob/main/styles/mac-window.css"
    click PublicAssets "https://github.com/akassh9/my-canvas/tree/main/public/images/"
    click Browser "https://github.com/akassh9/my-canvas/blob/main/src/hooks/useDeviceDetect.ts"
    click Browser "https://github.com/akassh9/my-canvas/blob/main/src/types/window.ts"

    %% Styles
    classDef infrastructure fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef appshell fill:#add8e6,stroke:#333,stroke-width:1px
    classDef ui fill:#90ee90,stroke:#333,stroke-width:1px
    classDef data fill:#ffa500,stroke:#333,stroke-width:1px
    classDef assets fill:#ffb6c1,stroke:#333,stroke-width:1px
    classDef external fill:#dda0dd,stroke:#333,stroke-width:1px
```
