# guiseek/solar-war architecture

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

- Interactive diagram: https://gitdiagram.com/guiseek/solar-war
- Repository: https://github.com/guiseek/solar-war

## Overview

##### Project Type & Purpose
- The project is a web-based simulation or visualization of a solar system. It is likely focused on rendering 3D models (planets, ships, astros) and managing related interactions (audio, animation, control of ships/missiles) in a browser.
- The README (“Solar System”) and asset directories (blend files for model definitions, public models) indicate a graphical and interactive application that leverages textures and 3D resources.

##### Analyzing the File Structure
- Top-Level Structure:
- Configuration/CI: .github directory (with GitHub workflows) for automated processes; package.json, tsconfig.json, vite.config.ts for managing dependencies and build configurations.
- Assets: “blend” (source 3D models created with Blender) and “public” (hosting final assets like glTF models, textures, and other static resources).
- Application Code: “src” folder divided into subdirectories such as “astros” (handles celestial objects like the Earth, stars, sun, starfields), “planet” (planet-specific logic and shaders), “ship” (controls and mechanics for ship movement and missiles), and “audio” (handling audio resources and playback for different events).

##### Main Components
a. Frontend/UI Layer:
- index.html which serves as the entry point for the web application.
- Style definitions (src/style.scss) to manage the presentation layer.
b. Application Core (Client-Side Logic):
- src/ directory components are organized functionally:
- Astros Module: Manages celestial bodies and related visual logic.
- Planet Module: Includes planet rendering logic and custom shaders (fragment and vertex shaders).
- Ship Module: Handles controls and interactions for ship movements and missile launching.
- Audio Module: Deals with playing sound effects (alarm, ship, pass-by sounds) linked with visual events.
- main.ts acts as the starting point for launching the application.
c. Asset Management:
- Blend Directory: Contains Blender source files (e.g., missile, ship) that may be used to generate or update 3D models.
- Public Directory: Provides ready-to-use models in GLB format that are loaded at runtime.
d. Infrastructure & DevOps:
- .github workflows (CI/CD) that help with automated testing, building, or deployment.

##### Relationships & Data Flow
- How index.html loads the bundled JavaScript (from Vite) and assets.
- The flow from the main.ts initialization to the loading of different modules (astros, planet, ship, audio).
- Interaction between the UI layer and the visualization engine: e.g., user control inputs triggering ship/missile functions.
- Data paths from asset folders (blend and public) to the rendering modules (planet shaders, ship models).
- Dependencies between configuration, build tools (Vite) and the source code.

##### Architectural Patterns & Design Principles
- Modular design: Different features are isolated by their purpose (celestial objects, audio, ship control).
- Separation of concerns: UI (HTML/SCSS), asset management, and core logic are clearly separated.
- Likely an event-driven approach for handling interactive parts (user commands, audio playback).

- A section for asset management showing the relationship between 3D models (blend source vs. public GLB files) and their use by respective visualization modules.
- Relationships like how user interactions translate into events managed by the ship module or how shaders process planet visuals.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend/UI Layer"
        UI["index.html"]:::frontend
        Style["style.scss"]:::frontend
    end

    subgraph "Application Core"
        Main["main.ts"]:::module
        Astros["Astros Module"]:::module
        Planet["Planet Module"]:::module
        Ship["Ship Module"]:::module
        Audio["Audio Module"]:::module
    end

    subgraph "Asset Management"
        Blend["Blend Assets"]:::asset
        Public["Public Assets"]:::asset
    end

    subgraph "Infrastructure & DevOps"
        Github["CI/CD: .github"]:::infra
        Readme["Documentation: README.md"]:::infra
        subgraph "Build Configs"
            Pkg["package.json"]:::infra
            Tsconfig["tsconfig.json"]:::infra
            Vite["vite.config.ts"]:::infra
            Pnpm["pnpm-lock.yaml"]:::infra
        end
    end

    %% Connections from UI to Application Core
    UI --> Main
    Main --> Astros
    Main --> Planet
    Main --> Ship
    Main --> Audio

    %% Asset Management interactions
    Blend --> Ship
    Public --> Astros
    Public --> Planet
    Public --> Ship

    %% Infrastructure & DevOps interactions
    Github --> Pkg
    Readme --> Pkg
    Pkg --> Tsconfig
    Tsconfig --> Vite
    Vite --> Pnpm
    Pnpm --> Main

%% Click Events
click UI "https://github.com/guiseek/solar-war/blob/main/index.html"
click Style "https://github.com/guiseek/solar-war/blob/main/src/style.scss"
click Main "https://github.com/guiseek/solar-war/blob/main/src/main.ts"
click Astros "https://github.com/guiseek/solar-war/tree/main/src/astros/"
click Planet "https://github.com/guiseek/solar-war/tree/main/src/planet/"
click Ship "https://github.com/guiseek/solar-war/tree/main/src/ship/"
click Audio "https://github.com/guiseek/solar-war/tree/main/src/audio/"
click Blend "https://github.com/guiseek/solar-war/tree/main/blend/"
click Public "https://github.com/guiseek/solar-war/tree/main/public/"
click Github "https://github.com/guiseek/solar-war/tree/main/.github/"
click Pkg "https://github.com/guiseek/solar-war/blob/main/package.json"
click Tsconfig "https://github.com/guiseek/solar-war/blob/main/tsconfig.json"
click Vite "https://github.com/guiseek/solar-war/blob/main/vite.config.ts"
click Pnpm "https://github.com/guiseek/solar-war/blob/main/pnpm-lock.yaml"
click Readme "https://github.com/guiseek/solar-war/blob/main/README.md"

%% Styles
classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
classDef module fill:#90EE90,stroke:#000,stroke-width:1px;
classDef asset fill:#FFFACD,stroke:#000,stroke-width:1px;
classDef infra fill:#F08080,stroke:#000,stroke-width:1px;
```
