# landry5/glance architecture

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

- Interactive diagram: https://gitdiagram.com/landry5/glance
- Repository: https://github.com/landry5/glance

## Overview

##### Project Type & Purpose
- Glance is a full-stack application built as a single Go binary. It focuses on rendering a customizable dashboard that aggregates data from multiple external sources into widgets.
- The dashboard configuration is defined via YAML files, and the app renders HTML pages using templates combined with static assets (CSS, JavaScript).
- Its main use case is to provide an “at-a-glance” view of various real-time information feeds and external data sources.

##### Analyzing the File Structure
- CLI and entry point (main.go inside internal/glance).
- Configuration handling (config.go, config-fields.go) which parses the YAML config.
- Core logic for loading and rendering pages and widgets (glance.go, diagnose.go, embed.go).
- A series of widget-specific implementations (files like widget-calendar.go, widget-weather.go, etc.) that encapsulate fetching and rendering for each widget type.
- Static assets and templates are inside internal/glance/static (for CSS, JavaScript, images) and internal/glance/templates (for HTML pages and widget templates).
- Additional directories like “pkg/sysinfo” support functions that provide system information, possibly for use in the server stats widget.
- The presence of multiple Docker-related configuration files (Dockerfile, .dockerignore, GitHub workflows, docker-compose examples in README) indicates that deployment is well-supported via containers.

a. Main Components:
- Configuration Module: Reads and parses YAML files (e.g., config/go files, docs/glance.yml) that define pages, layout, and widget settings.
- Widget Modules: Separate Go files for each widget (e.g., widget-rss.go, widget-weather.go, etc.) that define the business logic for fetching data from external APIs or sources.
- HTTP Server: The main Go application (entry in main.go) that starts an HTTP server, listens for incoming requests, applies configuration and routing, and serves rendered pages.
- External Services/Dependencies: These include external data providers such as RSS feeds, weather APIs, Twitch channels, etc. They are invoked by the widget modules.
- Deployment Components: Docker configuration and the pre-built binary demonstrate how the app is packaged and deployed.

b. Representing Relationships & Interactions:
- The Configuration Module defines multiple Pages, each containing a list of Widgets.
- The HTTP Server uses Template Engine (rendering HTML by combining widget data with templates located under internal/glance/templates) and serves static assets (JS, CSS) from the static folder.

c. Highlighting Architectural Patterns & Design Principles:
- Modular Design: Each widget is implemented as an independent module, which makes it easier to add or update functionality.
- Separation of Concerns: Clean division between configuration parsing, widget logic, template rendering, and static asset serving.
- Lightweight & Minimal Dependencies: Emphasize the design goal of low memory usage and fast load times.
- Extensibility: Custom widget types (such as custom-api or extension widgets) easily integrate into the main flow through the widget module architecture.

d. Including Relevant Technologies:
- Programming Language: Go (core logic, backend server).
- Template Engine: Go’s standard templating (and the use of .gotmpl files for theme styling).
- Frontend: HTML, minimal vanilla JavaScript, and CSS to power interactivity on the client side.
- Build and Deployment: Docker (via Dockerfile, docker-compose examples), and Go build tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    A["External Configuration Files"]:::external
    K["External API: Feeds/Services"]:::external

    %% Deployment Components
    J["Deployment Components"]:::deployment

    %% Backend Components
    B["Configuration Module"]:::backend
    C["HTTP Server / Router"]:::backend
    D["Template Renderer"]:::backend
    H["CLI & Diagnostic Tools"]:::backend
    I["System Information Support"]:::backend

    %% Frontend Components
    E["Templates"]:::frontend
    F["Static Assets"]:::frontend

    %% Widget Modules Subgraph
    subgraph "Widget Modules"
        direction TB
        G1["General Widget Logic"]:::widget
        G2["Widget: Calendar"]:::widget
        G3["Widget: Weather"]:::widget
        G4["Widget: RSS"]:::widget
        G5["Widget: Twitch Channels"]:::widget
    end

    %% Relationships
    A -->|"reads"| B
    B -->|"configures"| C
    C -->|"renders using"| D
    D --> E
    D --> F
    C -->|"initiates"| G1
    G1 -->|"spawns"| G2
    G1 -->|"spawns"| G3
    G1 -->|"spawns"| G4
    G1 -->|"spawns"| G5
    G2 -->|"fetches"| K
    G3 -->|"fetches"| K
    G4 -->|"fetches"| K
    G5 -->|"fetches"| K
    C -->|"debug/support"| H
    C -->|"monitors"| I
    J -->|"containers"| C

    %% Click Events
    click A "https://github.com/landry5/glance/blob/main/docs/glance.yml"
    click A "https://github.com/landry5/glance/blob/main/docs/configuration.md"
    click B "https://github.com/landry5/glance/blob/main/internal/glance/config.go"
    click B "https://github.com/landry5/glance/blob/main/internal/glance/config-fields.go"
    click C "https://github.com/landry5/glance/blob/main/internal/glance/main.go"
    click C "https://github.com/landry5/glance/blob/main/main.go"
    click D "https://github.com/landry5/glance/tree/main/internal/glance/templates"
    click E "https://github.com/landry5/glance/tree/main/internal/glance/templates"
    click F "https://github.com/landry5/glance/tree/main/internal/glance/static"
    click G1 "https://github.com/landry5/glance/blob/main/internal/glance/widget.go"
    click G2 "https://github.com/landry5/glance/blob/main/internal/glance/widget-calendar.go"
    click G3 "https://github.com/landry5/glance/blob/main/internal/glance/widget-weather.go"
    click G4 "https://github.com/landry5/glance/blob/main/internal/glance/widget-rss.go"
    click G5 "https://github.com/landry5/glance/blob/main/internal/glance/widget-twitch-channels.go"
    click H "https://github.com/landry5/glance/blob/main/internal/glance/cli.go"
    click H "https://github.com/landry5/glance/blob/main/internal/glance/diagnose.go"
    click I "https://github.com/landry5/glance/blob/main/pkg/sysinfo/sysinfo.go"
    click J "https://github.com/landry5/glance/tree/main/Dockerfile"
    click J "https://github.com/landry5/glance/blob/main/Dockerfile.goreleaser"
    click J "https://github.com/landry5/glance/blob/main/.dockerignore"
    click J "https://github.com/landry5/glance/tree/main/.github/workflows"

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef deployment fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef widget fill:#FFA07A,stroke:#000,stroke-width:2px;
```
