# mojmo/keepeyesonsudan architecture

> Architecture diagram of the GitHub repository mojmo/keepeyesonsudan, 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/mojmo/keepeyesonsudan
- Repository: https://github.com/mojmo/keepeyesonsudan

## Overview

##### Project type and purpose
- Full-stack awareness web application.
- Frontend: React + Vite + TypeScript; Backend: Node.js + Express (proxy to Reddit API).
- Fetches news, social posts, and statistics to inform users about the Sudan crisis.

##### File structure
- Top level
– package.json, vite.config.ts, tsconfig*.json → build tooling/config
– index.html, public/ → static assets and CSV data (refugees.csv)
- src/ → React app
– components/, pages/, styles/, utils/ (newsApi.ts, redditApi.ts)
– Router.tsx, App.tsx, main.tsx
- api/ → Express server
– index.js, .env.template, package.json, vercel.json

##### Extract key insights from the README
- Client calls two external APIs: GNews (NewsAPI) and Reddit (via local Express proxy).
- Visualizes UNHCR data (via public CSV or direct fetch).
- Responsive, mobile-first UI.

A. Client/Browser (User’s web browser)
B. Frontend Application
- React + Vite dev server / built static assets (index.html, JS bundle)
- UI modules: Carousel, Hero, News, SocialMedia, StatisticsChart, etc.
C. Backend Service
- Express.js proxy that securely holds Reddit credentials
- Exposes endpoints for frontend to fetch Reddit posts
D. External Services
- GNewsAPI (NewsAPI)
- Reddit API
- UNHCR (data.unhcr.org) or public/data/refugees.csv
E. Static Hosting / CDN
- Netlify / Vercel (serves built frontend & runs Express as serverless function)

##### Relationships & data flows
1) Browser → Frontend UI (loads HTML/JS/CSS)
2) Frontend → GNewsAPI (direct fetch using VITE_GNEWS_API_KEY)
3) Frontend → Express backend (`/api/reddit`)
4) Express → Reddit API (client credential flow)
5) Frontend → UNHCR or CSV data (static fetch)
6) All responses flow back to Browser to render components

##### Architectural patterns & principles
- Separation of concerns: UI vs. API proxy
- Single-Page Application (SPA) with client-side routing (Router.tsx)
- Environment variable isolation for secrets (NewsAPI key in client, Reddit creds in server)
- Static asset hosting + serverless functions (api/vercel.json)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Browser
    Browser["User's Web Browser"]:::external

    %% Hosting / Deployment
    subgraph "Cloud Hosting / CDN"
        direction TB
        Hosting["Netlify / Vercel"]:::hosting
        indexHTML["index.html"]:::frontend
        refugeesCSV["public/data/refugees.csv"]:::data
    end

    Browser -->|Loads SPA| indexHTML
    Browser -->|Fetch static CSV| refugeesCSV

    %% Frontend Layer
    subgraph "Frontend (React + Vite)" 
        direction TB
        srcDir["src/"]:::frontend
        main["main.tsx"]:::frontend
        appShell["App.tsx"]:::frontend
        router["Router.tsx"]:::frontend

        subgraph "UI Components"
            direction TB
            carousel["Carousel Component"]:::frontend
            hero["Hero Component"]:::frontend
            latestNews["LatestNews Component"]:::frontend
            socialMedia["SocialMedia Component"]:::frontend
            statsOverview["Statistics Component"]:::frontend
            statsChart["StatisticsChart Component"]:::frontend
            summary["Summary Component"]:::frontend
            navbar["Navbar Component"]:::frontend
            footer["Footer Component"]:::frontend
            skeleton["SkeletonCard Component"]:::frontend
        end

        subgraph "Pages"
            direction TB
            homePage["Home Page"]:::frontend
            notFoundPage["NotFound Page"]:::frontend
        end

        subgraph "Styles"
            direction TB
            globalStyles["global.css"]:::frontend
            componentStyles["*.css (component styles)"]:::frontend
        end

        subgraph "API Utilities"
            direction TB
            newsApi["newsApi.ts"]:::frontend
            redditApi["redditApi.ts"]:::frontend
            types["types.ts"]:::frontend
        end
    end

    Browser -->|Serves React App| srcDir
    srcDir --> main
    main --> appShell
    appShell --> router
    appShell --> navbar
    appShell --> footer
    router --> homePage
    router --> notFoundPage
    homePage --> carousel
    homePage --> hero
    homePage --> latestNews
    homePage --> socialMedia
    homePage --> statsOverview
    statsOverview --> statsChart
    homePage --> summary
    latestNews --> skeleton

    %% Frontend -> External APIs
    newsApi -->|HTTPS GET /v2/top-headlines| GNewsAPI
    redditApi -->|GET /api/reddit| ExpressProxy
    homePage --> newsApi
    homePage --> redditApi

    %% Backend Layer
    subgraph "Backend (Express Proxy)" 
        direction TB
        apiDir["api/"]:::backend
        expressServer["index.js"]:::backend
        envTemplate[".env.template"]:::backend
        vercelConfig["vercel.json"]:::backend
        apiPkg["package.json"]:::backend
    end

    ExpressProxy["Express Proxy"]:::backend
    redditAPI["Reddit API"]:::external
    GNewsAPI["GNews API"]:::external
    UNHCR["UNHCR Data API"]:::external

    ExpressProxy -->|OAuth2 Client Flow| redditAPI
    expressServer --> envTemplate
    expressServer --> vercelConfig
    expressServer --> apiPkg

    %% Data Flows
    Browser -->|Static assets| Hosting
    srcDir --> viteConfig
    viteConfig["vite.config.ts"]:::config
    tsconfigAll["tsconfig.json/app/node"]:::config
    envRoot[".env.template"]:::config
    eslint["eslint.config.js"]:::config

    %% External Services
    GNewsAPI -->|News Data| newsApi
    redditAPI -->|Posts| expressServer
    UNHCR -->|Refugee Data| refugeesCSV

    Router -- Deploy --> Hosting
    expressServer -- Serverless Function --> Hosting

    %% Click Events
    click srcDir "https://github.com/mojmo/keepeyesonsudan/tree/main/src/"
    click main "https://github.com/mojmo/keepeyesonsudan/blob/main/src/main.tsx"
    click appShell "https://github.com/mojmo/keepeyesonsudan/blob/main/src/App.tsx"
    click router "https://github.com/mojmo/keepeyesonsudan/blob/main/src/Router.tsx"
    click carousel "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/Carousel.tsx"
    click hero "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/Hero.tsx"
    click latestNews "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/LatestNews.tsx"
    click socialMedia "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/SocialMedia.tsx"
    click statsOverview "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/Statistics.tsx"
    click statsChart "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/StatisticsChart.tsx"
    click summary "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/Summary.tsx"
    click navbar "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/Navbar.tsx"
    click footer "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/Footer.tsx"
    click skeleton "https://github.com/mojmo/keepeyesonsudan/blob/main/src/components/SkeletonCard.tsx"
    click homePage "https://github.com/mojmo/keepeyesonsudan/blob/main/src/pages/Home.tsx"
    click notFoundPage "https://github.com/mojmo/keepeyesonsudan/blob/main/src/pages/NotFound.tsx"
    click globalStyles "https://github.com/mojmo/keepeyesonsudan/blob/main/src/styles/global.css"
    click newsApi "https://github.com/mojmo/keepeyesonsudan/blob/main/src/utils/newsApi.ts"
    click redditApi "https://github.com/mojmo/keepeyesonsudan/blob/main/src/utils/redditApi.ts"
    click types "https://github.com/mojmo/keepeyesonsudan/blob/main/src/utils/types.ts"
    click refugeesCSV "https://github.com/mojmo/keepeyesonsudan/blob/main/public/data/refugees.csv"
    click apiDir "https://github.com/mojmo/keepeyesonsudan/tree/main/api/"
    click expressServer "https://github.com/mojmo/keepeyesonsudan/blob/main/api/index.js"
    click envTemplate "https://github.com/mojmo/keepeyesonsudan/blob/main/api/.env.template"
    click vercelConfig "https://github.com/mojmo/keepeyesonsudan/blob/main/api/vercel.json"
    click apiPkg "https://github.com/mojmo/keepeyesonsudan/blob/main/api/package.json"
    click viteConfig "https://github.com/mojmo/keepeyesonsudan/blob/main/vite.config.ts"
    click tsconfigAll "https://github.com/mojmo/keepeyesonsudan/blob/main/tsconfig.json"
    click envRoot "https://github.com/mojmo/keepeyesonsudan/blob/main/.env.template"
    click eslint "https://github.com/mojmo/keepeyesonsudan/blob/main/eslint.config.js"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef data fill:#ECEFF1,stroke:#607D8B,color:#37474F
    classDef hosting fill:#FFFDE7,stroke:#F9A825,color:#F9A825
    classDef config fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
```
