How honzaap/githubcity works
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.