# angrytribble/star-trek-attack-wing-utopia architecture

> Architecture diagram of the GitHub repository angrytribble/star-trek-attack-wing-utopia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/angrytribble/star-trek-attack-wing-utopia
- Repository: https://github.com/angrytribble/star-trek-attack-wing-utopia

## Overview

##### Project type and purpose
- This is a front-end-only, single-page application (SPA) called “Utopia: A Fleet Builder for Star Trek Attack Wing.”
- It uses AngularJS (v1.x), plain HTML/CSS/JS, and a Grunt-based build pipeline. The output is a static site (in `staw-utopia/`) suitable for GitHub Pages or any static host.

##### File structure
- Top-level:
- `src/` holds all source assets—HTML entry points, CSS, JS (app code + third-party libs), templates, data, images, fonts, PDFs.
- `gruntfile.js` + `package.json` drive the build: transforms, concatenates, and outputs into `staw-utopia/`.
- `README.md` describes setup and purpose.
- Within `src/`:
- `css/`: app and theme styles, organized into `common/`, `lib/`, and page-specific sheets.
- `js/`: app code under `common/components/`, `common/services/`, `common/filters/`, plus entry scripts (`utopia-fleet-builder.js`, etc.) and third-party libs (`angular.js`, `jquery.js`).
- `templates/`: Angular partials for cards, fleet builder, search, export, etc.
- `data/`: static data modules (`.js`) and JSON backups under `backup/`. The build process likely compiles/parses them into a single `data.json`.
- `assets/`: PDFs, images, fonts used in UI or downloads.

##### README for additional insights
- Build prerequisites: Node.js and Grunt CLI.
- `npm start` generates the entire static site under `staw-utopia/`, including `data/data.json`.
- Generated files are not edited manually.

##### Main components and their interactions
a. Build Pipeline (Developer PC)
- Inputs: `src/` directory.
- Tools: Node.js, Grunt tasks (concat, minify, copy, JSON build).
- Outputs: `staw-utopia/` (static site).
b. Static Hosting / Deployment
- `staw-utopia/` artifacts deployed to a static web server (GitHub Pages, S3, etc.).
c. Client-side SPA (Browser)
- Entry point: `index.html`.
- AngularJS app loads core scripts (Angular, Utopia app code, libs), CSS, fonts, images.
- Data service fetches `data.json` (static file) and exposes it to UI.
- Components render fleet builder, mission database, set viewer, etc., using HTML templates.
- Filters and services manipulate data for search, export, drag-and-drop, tooltips.

##### Key architectural patterns and design principles
- Single-page, component-based front-end (AngularJS 1.x).
- Clear separation of concerns: services (data loading), filters (data transformation), components (UI widgets), templates (view).
- Static data ingestion—no runtime backend; JSON is built at compile time.
- Build pipeline automates asset bundling and site generation.

##### Relevant technologies, frameworks, libraries
- AngularJS 1.x, Angular-sanitize
- jQuery, Bootstrap (JS + CSS)
- Grunt.js (task runner)
- Node.js/npm (package management)
- JSON data modules and backups

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and Processes
    Developer["Developer PC"]:::client
    subgraph "Build Pipeline" 
        direction TB
        Grunt["Grunt Build (gruntfile.js, package.json)"]:::build
        gruntfile.js["gruntfile.js"]:::build
        package.json["package.json"]:::build
    end
    Developer -->|triggers| Grunt
    Grunt -->|builds| Artifact["Static Site (staw-utopia/)"]:::deployment

    click gruntfile.js "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/gruntfile.js"
    click package.json "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/package.json"
    click Artifact "https://github.com/angrytribble/star-trek-attack-wing-utopia/tree/main/src/staw-utopia/"

    subgraph "Deployment / Hosting"
        direction TB
        WebServer["Web Server / CDN"]:::deployment
    end
    Artifact -->|deploy| WebServer

    %% Client Runtime
    subgraph "Client Browser" 
        direction TB
        Browser["Browser"]:::client

        subgraph "AngularJS App" 
            direction TB
            subgraph "Core Libraries"
                direction TB
                AngularJS["angular.js"]:::client
                AngularSanitize["angular-sanitize.js"]:::client
            end
            subgraph "Third-Party Libs"
                direction TB
                jQuery["jquery.js"]:::client
                BootstrapJS["bootstrap.js"]:::client
            end
            subgraph "App Scripts"
                direction TB
                UtopiaMain["utopia.js"]:::client
                FleetBuilderScript["utopia-fleet-builder.js"]:::client
                UtopiaExport["utopia-fleet-export.js"]:::client
            end
            subgraph "Components"
                direction TB
                CardComp["utopia-card.js"]:::client
                FactionComp["utopia-card-faction.js"]:::client
                ShipComp["utopia-card-ship.js"]:::client
                BuilderComp["utopia-fleet-builder.js"]:::client
            end
            subgraph "Filters"
                direction TB
                FleetFilter["fleet-card-named-filter.js"]:::client
                ShipFilter["ship-card-named-filter.js"]:::client
            end
            subgraph "Services"
                direction TB
                CardLoader["utopia-card-loader.js"]:::client
                ValueOf["utopia-valueof.js"]:::client
            end
            subgraph "Templates"
                direction TB
                FleetBuilderT["fleet-builder.html"]:::client
                FleetExportT["fleet-export.html"]:::client
                SearchT["search.html"]:::client
            end
        end

        DataJSON["data.json"]:::data
        Assets["Assets (images, fonts, PDFs)"]:::asset
    end

    WebServer -->|HTTP GET| Browser
    Browser -->|loads HTML/CSS/JS| WebServer
    Browser -->|fetch data.json| WebServer
    Browser -->|loads assets| WebServer

    Browser --> AngularJS
    AngularJS --> DataJSON
    AngularJS --> Assets

    click AngularJS "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/lib/angular.js"
    click AngularSanitize "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/lib/angular-sanitize.js"
    click jQuery "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/lib/jquery.js"
    click BootstrapJS "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/lib/bootstrap.js"
    click UtopiaMain "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/utopia.js"
    click FleetBuilderScript "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/utopia-fleet-builder.js"
    click CardComp "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/common/components/utopia-card.js"
    click FleetFilter "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/common/filters/fleet-card-named-filter.js"
    click CardLoader "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/js/common/utopia-card-loader.js"
    click FleetBuilderT "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/templates/fleet-builder.html"
    click DataJSON "https://github.com/angrytribble/star-trek-attack-wing-utopia/blob/main/src/data/backup/data.json"

    %% Styles
    classDef build fill:#f96,stroke:#333,color:#000
    classDef deployment fill:#6f6,stroke:#333,color:#000
    classDef client fill:#6cf,stroke:#333,color:#000
    classDef data fill:#ccc,stroke:#333,color:#000
    classDef asset fill:#ddd,stroke:#333,color:#000
```
