# florianrappl/typescript-fullstack-sample architecture

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

- Interactive diagram: https://gitdiagram.com/florianrappl/typescript-fullstack-sample
- Repository: https://github.com/florianrappl/typescript-fullstack-sample

## Overview

##### Project Type and Purpose
- This is a minimal “universal” (isomorphic) full-stack web application sample built with TypeScript, Node.js, and React.
- It demonstrates client-side rendering (CSR), server-side rendering (SSR), hydration, and a shared global state container without external state libraries like Redux.

##### File-Structure Analysis
- Top-level files:
- package.json / package-lock.json: npm scripts and dependencies
- Dockerfile, .gitignore, .editorconfig, prettier.config.js: environment/configuration
- webpack.config.js: orchestrates building both client and server bundles
- tsconfig.json, tsconfig.client.json, tsconfig.server.json: TypeScript configuration for different targets
- src/client: entry point for the browser bundle (createView.tsx, index.ts)
- src/server: Node.js server logic (index.ts), SSR renderer (renderIndex.ts), asset retrieval (retrieveAsset.ts), server-side view creator (createView.tsx)
- src/common: shared React components, pages, actions, types, and global state container

##### README Insights
- Confirms it is a sample showing universal rendering, hydration, and shared state
- Notes excluded topics (live reload, styling, Redux) to keep the example focused and minimal

##### Main Architectural Components
a. Client Application (Browser)
- React entry point (client/index.ts)
- View creator (client/createView.tsx) that hydrates the server-rendered markup
- Bundle produced by webpack for browser consumption
b. Server Application (Node.js)
- HTTP server (server/index.ts) that handles incoming requests
- SSR engine (server/renderIndex.ts) using the shared React App to output HTML
- Static asset handler (server/retrieveAsset.ts) serving JS/CSS bundles from disk
- Bundle produced by webpack for Node.js execution
c. Shared Library (Isomorphic Code)
- src/common/App.tsx: top-level React component used in both environments
- Pages (HomePage, TodoPage, etc.) and UI components (CenterInfo)
- Global state container (actions.ts, state.ts) and TypeScript types
d. Build System
- webpack.config.js defines two targets: “client” (browser) and “server” (Node)
- TypeScript compilers: separate configs for client and server to manage module resolution and JSX emitting

##### Relationships and Data Flow
1. Developer runs “npm run build” → webpack outputs:
– client.bundle.js (for browsers)
– server.bundle.js (for Node.js SSR)
2. Developer runs “npm start” → Node.js loads server.bundle.js and listens on port 3000
3. Browser requests “/” → Node server.renderIndex() uses the shared App to generate HTML + initial state → responds with HTML embedding client.bundle.js and serialized state
4. Browser downloads client.bundle.js → client.createView() hydrates the server-rendered markup, bootstraps the shared global state container, and enables CSR thereafter
5. Further client interactions update the shared state container; if needed, the client can also call new server endpoints (not implemented in this sample, but typical in a full-featured app)

##### Architectural Patterns and Principles
- Universal (isomorphic) rendering for optimal SEO and faster first paint
- Clear separation of concerns:
- Server concerns (HTTP handling, SSR)
- Client concerns (hydration, UI interactions)
- Shared concerns (React components, state management)
- Single global state store without Redux, demonstrating a lightweight custom solution
- Build-time and run-time separation via webpack and tsconfig targets

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build Phase
    subgraph "Build Phase"
        direction TB
        webpack["webpack.config.js"]:::tool
        tsconfigs["tsconfig.json<br/>tsconfig.client.json<br/>tsconfig.server.json"]:::tool
        packageJson["package.json<br/>package-lock.json"]:::tool
        webpack -->|"bundles"| clientBundle
        webpack -->|"bundles"| serverBundle
    end

    clientBundle["client.bundle.js"]:::bundle
    serverBundle["server.bundle.js"]:::bundle

    %% Runtime Phase
    subgraph "Runtime Phase"
        direction TB

        %% Server Side
        subgraph "Server Side" 
            direction TB
            nodeServer("Node.js Server"):::server
            ssr["SSR Renderer<br/>(src/server/renderIndex.ts)"]:::server
            assetRetriever["Asset Retriever<br/>(src/server/retrieveAsset.ts)"]:::server
            createViewServer["Server View Creator<br/>(src/server/createView.tsx)"]:::server
            nodeServer -->|"handles request"| ssr
            nodeServer -->|"serves assets"| assetRetriever
        end

        %% Client Side
        subgraph "Client Side"
            direction TB
            browser("Browser"):::client
            hydrate["Hydration<br/>(src/client/createView.tsx)"]:::client
            clientEntry["Client Entry<br/>(src/client/index.ts)"]:::client
            browser -->|"downloads bundle"| hydrate
            hydrate -->|"bootstraps UI"| reactApp
        end

        %% Shared Code
        subgraph "Shared Code"
            direction TB
            reactApp["React App<br/>(src/common/App.tsx)"]:::shared
            pages["Pages<br/>HomePage, NotFoundPage, TickerPage, TodoPage"]:::shared
            components["UI Components<br/>CenterInfo & index"]:::shared
            stateActions["State & Actions<br/>state.ts & actions.ts"]:::shared
            types["Types<br/>state & todo"]:::shared
            reactApp --> pages
            reactApp --> components
            reactApp --> stateActions
            reactApp --> types
            ssr --> reactApp
            clientEntry --> reactApp
        end

        %% Data Flow
        browser -->|"HTTP GET /"| nodeServer
        ssr -->|"SSR HTML + state + <script>client.bundle.js"| browser
        serverBundle --> nodeServer
        clientBundle --> browser
    end

    %% Click Events
    click clientEntry "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/client/index.ts"
    click hydrate "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/client/createView.tsx"
    click ssr "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/server/renderIndex.ts"
    click assetRetriever "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/server/retrieveAsset.ts"
    click createViewServer "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/server/createView.tsx"
    click reactApp "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/App.tsx"
    click pages "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/pages/HomePage.tsx"
    click pages "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/pages/NotFoundPage.tsx"
    click pages "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/pages/TickerPage.tsx"
    click pages "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/pages/TodoPage.tsx"
    click components "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/components/CenterInfo.tsx"
    click components "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/components/index.ts"
    click stateActions "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/state.ts"
    click stateActions "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/actions.ts"
    click types "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/types/state.ts"
    click types "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/types/todo.ts"
    click types "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/src/common/types/index.ts"
    click webpack "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/webpack.config.js"
    click tsconfigs "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/tsconfig.json"
    click tsconfigs "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/tsconfig.client.json"
    click tsconfigs "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/tsconfig.server.json"
    click packageJson "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/package.json"
    click packageJson "https://github.com/florianrappl/typescript-fullstack-sample/blob/master/package-lock.json"

    %% Styles
    classDef tool fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef bundle fill:#cde5ff,stroke:#0366d6,stroke-width:1px,stroke-dasharray: 5 5
    classDef server fill:#d4f8d4,stroke:#1f8f1f,stroke-width:1px
    classDef client fill:#d4eaff,stroke:#1a6fb3,stroke-width:1px
    classDef shared fill:#fff4cc,stroke:#d39e00,stroke-width:1px
```
