# honzaap/githubcity architecture

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

- Interactive diagram: https://gitdiagram.com/honzaap/githubcity
- Repository: https://github.com/honzaap/githubcity

## Overview

##### Project Type and Purpose
- GitHub City is a web-based interactive 3D visualization tool that uses ThreeJS to generate a virtual city based on your GitHub contribution graph.
- Its purpose is to take GitHub activity data and transform it into a dynamic 3D environment composed of various building and environmental 3D assets.
- The README clearly states the use of ThreeJS and hints at leveraging hardware acceleration, indicating that performance and real-time rendering are key.

##### Analyzing the File Structure
- Top-Level Files & Folders:
– Configuration and build tools: .eslintrc.js, .prettierrc.js, .stylelintrc.js, package.json, package-lock.json, and GitHub workflows.
– Assets: A massive assets folder containing numerous .glb files for buildings, roads, trees, and environments. These represent the 3D models used in rendering the city.
– Core JavaScript files: main.js, scene.js, algo.js, api.js, and constants.js.
– User Interface entry point: index.html. Also, style.scss provides styling.
- Architectural Patterns Evident:
– Separation of concerns: There is a clear split between configuration, assets, and the core functionality (logic in algo.js, api.js, and rendering setup in scene.js/main.js).
– The structure indicates a single-page application with a heavy client-side rendering component handled by ThreeJS.
– The presence of algorithm and API scripts suggests a design that fetches and processes external data (GitHub contributions) and feeds it into the rendering pipeline.

a. Main Components:
- Browser/Client (Frontend Entry):
– index.html: The entry point that loads the application.
– style.scss: The styling file ensuring a polished UI.
- Application Logic:
– main.js: Likely bootstraps the app and initializes the rendering loop.
– scene.js: Sets up and manages the ThreeJS scene, handling camera, lights, and 3D rendering.
– algo.js: Contains core algorithms for converting GitHub contributions into structures/buildings in the city.
– api.js: Handles fetching data from GitHub (or processing contribution graph data).
- Assets:
– assets folder: Contains all .glb files representing 3D models (buildings, environments, roads, trees) used by the scene.
- Configuration & Tooling:
– Constants.js: Likely holds application constants and configurations.
– Build and linters configurations: .eslintrc.js, .prettierrc.js, .stylelintrc.js, package.json, etc.
- External Services:
– GitHub’s API: Although not explicitly shown in the file tree, the project’s concept implies interaction with GitHub for contribution data.

b. Relationships and Interactions:
- The index.html loads the main JavaScript which then initializes the ThreeJS scene (via scene.js).
- main.js orchestrates the app by calling functions in algo.js to interpret GitHub data (possibly retrieved via api.js) and then applying this data to the scene.
- The assets folder feeds 3D models into the scene rendering logic.
- Configuration files ensure code quality and consistent builds, feeding into the development lifecycle (e.g., pre-commit hooks with Husky).

c. Architectural Patterns and Design Principles:
- Single-Page Application design with client-side rendering.
- Separation of concerns: UI, processing logic, and assets are clearly separated.
- Modular design: Different JavaScript files handle distinct responsibilities (scene setup, algorithms, API calls).
- Use of asset-driven design: The city is dynamically constructed from a rich set of 3D models.

d. Relevant Technologies and Frameworks:
- ThreeJS: Core library for 3D rendering.
- Node.js and npm: For package management and development tooling.
- GitHub Actions and Husky: For CI/CD and pre-commit linting.
- Standard tools: ESlint, Prettier, and Stylelint for code quality.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend/UI
    subgraph "Frontend/UI"
        FE1["index.html"]:::frontend
        FE2["style.scss"]:::frontend
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        RE1["main.js"]:::render
        RE2["scene.js"]:::render
    end

    %% Business Logic
    subgraph "Business Logic"
        BL1["algo.js"]:::logic
        BL2["api.js"]:::logic
    end

    %% Assets (3D Models)
    subgraph "Assets (3D Models)"
        SA1["assets (3D Models)"]:::assets
    end

    %% Configuration & Tooling
    subgraph "Configuration & Tooling"
        CT1["constants.js"]:::config
        CT2[".eslintrc.js"]:::config
        CT3[".prettierrc.js"]:::config
        CT4[".stylelintrc.js"]:::config
        CT5["package.json"]:::config
        CT6["package-lock.json"]:::config
        CT7["GitHub Workflows & Husky"]:::config
    end

    %% External Service
    EG["GitHub API"]:::external

    %% Relationships
    FE1 -->|"loads"| RE1
    RE1 -->|"initializes"| RE2
    RE1 -->|"orchestrates"| BL1
    BL1 -->|"generatesCity"| RE2
    BL2 -->|"fetchesData"| EG
    RE2 -->|"loadsModels"| SA1

    %% Configuration support (dotted arrows)
    CT5 -.->|"supports"| FE1
    CT5 -.->|"supports"| RE1
    CT5 -.->|"supports"| BL1
    CT5 -.->|"supports"| BL2

    %% Legend (see comments below)
    %% Legend:
    %% - Frontend/UI (yellow): index.html, style.scss
    %% - Rendering Engine (light blue): main.js, scene.js
    %% - Business Logic (light green): algo.js, api.js
    %% - Assets (khaki): assets folder containing 3D models
    %% - Configuration & Tooling (grey): constants.js, build and linter configs, package files, GitHub workflows & Husky
    %% - External Service (salmon): GitHub API

    %% Click Events
    click FE1 "https://github.com/honzaap/githubcity/blob/main/index.html"
    click FE2 "https://github.com/honzaap/githubcity/blob/main/style.scss"
    click RE1 "https://github.com/honzaap/githubcity/blob/main/main.js"
    click RE2 "https://github.com/honzaap/githubcity/blob/main/scene.js"
    click BL1 "https://github.com/honzaap/githubcity/blob/main/algo.js"
    click BL2 "https://github.com/honzaap/githubcity/blob/main/api.js"
    click SA1 "https://github.com/honzaap/githubcity/tree/main/assets"
    click CT1 "https://github.com/honzaap/githubcity/blob/main/constants.js"
    click CT2 "https://github.com/honzaap/githubcity/blob/main/.eslintrc.js"
    click CT3 "https://github.com/honzaap/githubcity/blob/main/.prettierrc.js"
    click CT4 "https://github.com/honzaap/githubcity/blob/main/.stylelintrc.js"
    click CT5 "https://github.com/honzaap/githubcity/blob/main/package.json"
    click CT6 "https://github.com/honzaap/githubcity/blob/main/package-lock.json"
    click CT7 "https://github.com/honzaap/githubcity/tree/main/GitHub Workflows & Husky"

    %% Styles
    classDef frontend fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef render fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef logic fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef assets fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef config fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9999,stroke:#333,stroke-width:2px;
```
