# ifrcgo/go-web-app architecture

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

- Interactive diagram: https://gitdiagram.com/ifrcgo/go-web-app
- Repository: https://github.com/ifrcgo/go-web-app

## Overview

##### Project type and purpose
- This is a frontend‐focused monorepo hosting:
- A React/Vite single‐page application (“app” directory)
- A shared UI component library (“packages/ui”)
- A Storybook instance for that library (“packages/go-ui-storybook”)
- Nginx-based Docker/Helm configurations for serving static assets
- Its purpose is to deliver the IFRC GO web platform UI, which communicates at runtime with a separate backend API.

##### High‐level architecture components
a. End Users’ Web Browsers – load the SPA, interact via UI
b. CDN or Nginx Static File Server – serves built JavaScript/CSS/HTML
c. React SPA (app) – the single‐page front end, built with Vite and TypeScript
d. IFRC GO UI Library – component set used both by the SPA and Storybook
e. Storybook / Chromatic – development site for UI components
f. Backend API (external, not in this repo) – REST endpoints for data
g. CI/CD Pipelines – GitHub Actions for building, testing, publishing, deploying

##### Relationships & data flows
- Developers author components in “packages/ui” → consumed by “app” and “go-ui-storybook”.
- Storybook runs in dev mode (via Chromatic workflow) to preview components in isolation.
- The SPA is built (pnpm → vite build) → static assets.
- Nginx (Docker + Helm charts) pulls those assets into a container → deployed to Kubernetes / cloud.
- Browser requests “index.html” from Nginx → downloads SPA → frontend code executes.
- SPA, via its REST utilities (app/src/utils/restRequest), issues HTTP calls to the external go-api backend → renders data in UI.

##### Architectural patterns & principles
- Monorepo with well-scoped packages (UI library, Storybook, SPA).
- Component-based UI (React) with a shared design system.
- Environment-driven configuration (app/env.ts → .env).
- Infrastructure as code (Dockerfile, Helm templates in nginx-serve).
- CI/CD defined in GitHub workflows:
- ci.yml (build/test)
- publish-nginx-serve.yml (deploy static site)
- chromatic.yml (publish Storybook)

##### Technologies & frameworks
- UI: React, TypeScript, Vite, PostCSS, CSS modules
- Package management: pnpm, pnpm-workspace
- Component library: packages/ui (exports styled, accessible components)
- Storybook: packages/go-ui-storybook, Chromatic integration
- Server: Nginx (Docker), Helm charts for Kubernetes
- CI/CD: GitHub Actions
- Testing: vitest, jest (for scripts), linting (eslint, stylelint), knip
- Internationalization: JSON per-component i18n files, translation migrations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% End Users
    Browser["Browser"]:::web

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Nginx["Nginx Static Server\n(nginx-serve/)"]:::infra
        BackendAPI["Backend API"]:::external
    end

    %% Monorepo
    subgraph "Monorepo"
        direction TB
        subgraph "Development Artifacts"
            direction TB
            ULib["IFRC GO UI Library\n(packages/ui/)"]:::dev
            Story["Storybook\n(packages/go-ui-storybook/)"]:::dev
        end
        SPA["React SPA\n(app/)"]:::web
        Env["Env Config\n(app/env.ts & .env)"]:::dev
        Trans["Translation Migrations\n(translationMigrations/)"]:::dev
        RestUtils["REST Utilities\n(app/src/utils/restRequest/)"]:::web
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines\n(.github/workflows)" 
        direction TB
        CI1["ci.yml"]:::infra
        CI2["chromatic.yml"]:::infra
        CI3["publish-nginx-serve.yml"]:::infra
        CI4["publish-storybook-nginx-serve.yml"]:::infra
    end

    %% Data Flows
    Browser -->|"HTTP GET index.html & assets"| Nginx
    Nginx -->|"serves SPA files"| Browser
    Browser -->|"runs SPA"| SPA
    SPA -->|"uses REST utils"| RestUtils
    RestUtils -->|"HTTP REST calls"| BackendAPI
    ULib -->|"import via pnpm"| SPA
    ULib -->|"import via pnpm"| Story
    Story -->|"preview components"| Browser
    Env -->|"configures"| SPA
    Env -->|"configures"| Story
    Trans -->|"feeds translations"| SPA

    CI1 -->|"build & test"| ULib
    CI1 -->|"build & test"| SPA
    CI1 -->|"build & test"| Story
    CI2 -->|"publish Storybook to Chromatic"| Story
    CI3 -->|"build SPA Docker image & Helm deploy"| Nginx
    CI4 -->|"deploy Storybook via Nginx/Helm"| Story

    %% Click Events
    click ULib "https://github.com/ifrcgo/go-web-app/tree/develop/packages/ui/"
    click Story "https://github.com/ifrcgo/go-web-app/tree/develop/packages/go-ui-storybook/"
    click SPA "https://github.com/ifrcgo/go-web-app/tree/develop/app/"
    click Nginx "https://github.com/ifrcgo/go-web-app/tree/develop/nginx-serve/"
    click CI1 "https://github.com/ifrcgo/go-web-app/blob/develop/.github/workflows/ci.yml"
    click CI2 "https://github.com/ifrcgo/go-web-app/blob/develop/.github/workflows/chromatic.yml"
    click CI3 "https://github.com/ifrcgo/go-web-app/blob/develop/.github/workflows/publish-nginx-serve.yml"
    click CI4 "https://github.com/ifrcgo/go-web-app/blob/develop/.github/workflows/publish-storybook-nginx-serve.yml"
    click RestUtils "https://github.com/ifrcgo/go-web-app/blob/develop/app/src/utils/restRequest/index.ts"

    %% Styles
    classDef web fill:#a0e9a0,stroke:#333,stroke-width:1px
    classDef dev fill:#a0c4e4,stroke:#333,stroke-width:1px
    classDef infra fill:#f5c469,stroke:#333,stroke-width:1px
    classDef external fill:#f28c8c,stroke:#333,stroke-width:1px
```
