# ixtk/social-empires architecture

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

- Interactive diagram: https://gitdiagram.com/ixtk/social-empires
- Repository: https://github.com/ixtk/social-empires

## Overview

##### Project type and purpose
- This is a single-page React front-end application (“Social Empires civilization gallery”) whose sole responsibility is to display a catalog of game assets (units, buildings, decorations).
- There is no custom back-end in the repo. It’s a static site that fetches data (images and metadata) from an external Google Sheets document and serves it via a hosted bundle.

##### File structure
- Top-level files: package.json (npm dependencies, React), public/index.html (shell HTML), src/ (React source).
- src/components:
- App.js – top-level React component, orchestrates child components
- Select.js – dropdown or filter UI
- Gallery.js – layout/container for a list of Image components
- Image.js – renders one asset (thumbnail, title, etc.)
- src/index.js – entry point, renders <App /> into the DOM.
- No backend directories, no server code, no deployment scripts beyond the standard React build.

##### README for additional insights
- The gallery sources its images from a Google Sheet. The README references the external Sheets URL.
- Project is purely client-side; static hosting is implied (e.g., GitHub Pages, Netlify, S3 + CloudFront).

a. Main components
- User’s Browser / Client
- Static Site Hosting / CDN (serving index.html, JS bundle, CSS, assets)
- React Application (src/App.js & children)
- External Data Source (Google Sheets / Sheets API or published CSV)
b. Relationships and interactions
1. Browser → CDN: initial GET for index.html, CSS, JS
2. React App boots in browser
3. React App → Google Sheets API (fetch listings / image URLs)
4. Data returned as JSON or CSV → React state
5. App’s Select / Gallery → Image components render UI
c. Architectural patterns / design principles
- Component-based architecture (React)
- Unidirectional data flow: App fetches data once; passes props down to Select & Gallery; user interactions bubble up via callbacks
- Separation of concerns: data fetching in App, presentation in child components
d. Key technologies / frameworks
- React (with hooks or class components)
- JavaScript / JSX
- CSS modules or plain CSS (App.css)
- Google Sheets as a headless data store
- Static site hosting (GitHub Pages, Netlify, AWS S3)

##### Elements
- “User Browser / Client”
- “Static Hosting / CDN”
- “React App” subdivided into App, Select, Gallery, Image
- “Google Sheets Data Source”
- Browser → CDN (GET static assets)
- React App → Google Sheets (fetch data)
- Data flow from parent to child components (App → Gallery → Image)
- Blue rectangles for UI components (Select, Gallery, Image)

##### Detailed but concise advice
- Use a layered layout: top layer = user & hosting, middle = React app runtime, bottom = external data.
- Where props and callbacks flow between components.
- That there is no custom back-end; the only “service” beyond hosting is the Google Sheets API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: User and Hosting
    UB["User Browser / Client"]:::user
    subgraph "Static Hosting / CDN"
        direction TB
        PublicHTML["public/index.html"]:::file
    end
    UB -->|"GET index.html"| PublicHTML
    PublicHTML -->|"Serves HTML"| UB
    PublicHTML -->|"Loads JS/CSS bundle"| Index

    %% React Application Runtime
    subgraph "React Application Runtime"
        direction TB
        Index["src/index.js"]:::file
        AppComp["App.js"]:::file
        CSS["App.css"]:::file
        SelectComp["Select.js"]:::file
        GalleryComp["Gallery.js"]:::file
        ImageComp["Image.js"]:::file
    end

    %% Data Source
    Sheets["Google Sheets Data Source"]:::data

    %% Project Documentation
    subgraph "Project Files"
        direction TB
        Package["package.json"]:::file
        Readme["README.md"]:::file
    end

    %% Component Relationships
    Index -->|"renders <App />"| AppComp
    AppComp -->|"fetchData() via Sheets API"| Sheets
    AppComp -->|"passes props"| SelectComp
    AppComp -->|"passes props"| GalleryComp
    GalleryComp -->|"renders list"| ImageComp
    SelectComp -->|"onFilterChange() callback"| AppComp
    CSS -->|"styles App component"| AppComp

    %% Click Events
    click Index "https://github.com/ixtk/social-empires/blob/main/src/index.js"
    click AppComp "https://github.com/ixtk/social-empires/blob/main/src/components/App.js"
    click CSS "https://github.com/ixtk/social-empires/blob/main/src/App.css"
    click SelectComp "https://github.com/ixtk/social-empires/blob/main/src/components/Select.js"
    click GalleryComp "https://github.com/ixtk/social-empires/blob/main/src/components/Gallery.js"
    click ImageComp "https://github.com/ixtk/social-empires/blob/main/src/components/Image.js"
    click PublicHTML "https://github.com/ixtk/social-empires/blob/main/public/index.html"
    click Package "https://github.com/ixtk/social-empires/blob/main/package.json"
    click Readme "https://github.com/ixtk/social-empires/blob/main/README.md"

    %% Styles
    classDef user fill:#FFD700,stroke:#333,stroke-width:1px;
    classDef hosting fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef frontend fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef data fill:#FFDAB9,stroke:#333,stroke-width:1px;
    classDef file fill:#D3D3D3,stroke:#333,stroke-width:1px;

    class UB user
    class PublicHTML hosting
    class Index,AppComp,SelectComp,GalleryComp,ImageComp,CSS frontend
    class Sheets data
    class Package,Readme file
```
