Development Architecture

This document describes the architecture and design of sysc-greet.

Overview

sysc-greet is a graphical greeter for greetd, written in Go using the Bubble Tea TUI framework (v2).

Project Structure

sysc-greet/
├── cmd/
│   ├── installer/       # Interactive installation wizard
│   └── sysc-greet/    # Main greeter binary
│       ├── main.go       # Application entry point, model, update loop
│       ├── theme.go       # Theme application and wallpaper management
│       ├── ascii.go       # ASCII art loading and parsing
│       ├── wallpaper.go   # Wallpaper menu and gSlapper/swww handling
│       ├── menu.go        # Menu system and navigation
│       ├── screensaver.go # Screensaver mode and idle detection
│       ├── ui_components.go # Reusable UI components
│       ├── utils.go       # Helper functions
│       └── views.go       # View rendering for different modes
├── internal/
│   ├── animations/    # Background and text effects
│   │   ├── fire.go       # DOOM PSX fire effect
│   │   ├── rain.go       # ASCII rain effect
│   │   ├── matrix.go     # Matrix rain effect
│   │   ├── fireworks.go  # Firework particle system
│   │   ├── aquarium.go   # Animated aquarium scene
│   │   ├── ticker.go     # Typewriter and scrolling ticker
│   │   ├── print_effect.go # Print animation for ASCII
│   │   ├── beams_text.go # Beams text effect
│   │   └── pour.go       # Pour text effect
│   ├── cache/          # User preferences persistence
│   ├── ipc/            # greetd IPC client
│   ├── sessions/       # XDG session detection
│   ├── themes/         # Theme definitions (colors.go, themes.go)
│   └── wallpaper/      # gSlapper IPC client
├── ascii_configs/        # Session ASCII art configurations
├── config/              # Compositor configuration templates
└── fonts/               # Figlet font files

Core Components

Model-View-Update Pattern

sysc-greet follows Bubble Tea's Elm architecture:

• Model - Holds all application state
• View - Renders the UI based on model state
• Update - Handles messages and transitions state
• Init - Returns initial commands

State Management

The model struct in cmd/sysc-greet/main.go maintains:

• User inputs (username, password)
• Selected session and preferences
• Current mode (login, password, menu, screensaver, etc.)
• Animation state and timers
• IPC client connection

View Modes

sysc-greet operates in different view modes:

Kitty color output

greetd launches the Bubble Tea interface in fullscreen Kitty under the selected compositor. The colorprofile library detects the color depth exposed by Kitty; the supported runtime is the Kitty greeter session.

IPC Communication

greetd Client

sysc-greet communicates with greetd via Unix socket for authentication:

1. Create session with greetd
2. Send create session request with username and session
3. Receive success/failure response
4. On success, start the selected session

gSlapper IPC

Wallpaper management uses gSlapper IPC protocol via Unix socket at /tmp/sysc-greet-wallpaper.sock:

• IsGSlapperRunning() - Check if gSlapper socket exists
• ChangeWallpaper(path) - Change wallpaper with fade transition
• PauseVideo() - Pause video playback
• ResumeVideo() - Resume video playback

Fallback Behavior

If gSlapper is not available, sysc-greet falls back to swww for wallpaper management.

Configuration System

User Preferences

Stored in /var/cache/sysc-greet/:

• Selected theme
• Selected background effect
• Selected wallpaper
• Selected border style
• Last session and username (if --remember-username enabled)
• ASCII variant index

Session Detection

sysc-greet reads XDG session files from standard paths:

• /usr/share/xsessions
• /usr/share/wayland-sessions
• /run/current-system/sw/share/xsessions
• /run/current-system/sw/share/wayland-sessions

Each session is parsed for:

• Name (from Name= field)
• Exec command (from Exec= field)
• Type (X11 or Wayland, based on path)

ASCII Config System

Each session can have a .conf file in /usr/share/sysc-greet/ascii_configs/:

Parsed fields:

• name - Display name
• ascii_1, ascii_2, etc. - Multiple ASCII art variants
• colors - Hex colors for rainbow effect
• roasts - Custom roast messages separated by │

Animation System

Background Effects

All background effects implement a common interface:

• Update(frame) - Advance animation by one frame
• Initialized with width and height
• Use theme colors for rendering

Effects:

• Fire, Matrix, ASCII Rain, Fireworks, Aquarium
• Sonar, Cracktro, Plasma
• AK-47 and Australian SLR models
• Higgs Field particle field
• Rotating statues, landmarks, and aircraft

ASCII Effects

• Typewriter - Character-by-character text display
• Print - Line-by-line ASCII rendering
• Beams - Horizontal color beam scanning
• Pour - Character cascade with gradient

Key Bindings

sysc-greet handles key input centrally:

Security Features

CAPS LOCK Detection

sysc-greet uses Kitty keyboard protocol to detect CAPS LOCK state:

• Requests RequestUniformKeyLayout on init
• Checks tea.ModCapsLock in key messages
• Displays warning when CAPS LOCK is on

Failed Attempt Tracking

Tracks consecutive failed authentication attempts:

• Displays warning message after failed login
• Resets counter on successful authentication
• Returns to username field on failure (not password)

Test Mode

The --test flag bypasses greetd IPC for safe testing:

• Uses mock sessions if none found
• Does not execute user sessions
• Allows Ctrl+C to exit
• Disables wallpaper changes in production

Performance Considerations

Non-blocking Operations

Wallpaper changes and IPC calls run in goroutines to avoid blocking the UI:

go func() {
    if err := wallpaper.ChangeWallpaper(path); err != nil {
        logDebug("gSlapper wallpaper change failed: %v", err)
    }
}()

Lazy Initialization

Effects are initialized on first use when terminal dimensions are known:

• Aquarium effect created when first selected with valid dimensions
• gSlapper launched when first needed, not at startup

Dependencies

• charmbracelet/bubbletea/v2 - TUI framework
• charmbracelet/lipgloss/v2 - Terminal styling
• charmbracelet/colorprofile - Terminal capability detection
• mbndr/figlet4go - ASCII art generation

Build System

• Go 1.25.1 toolchain
• Build tags and commit info injected via ldflags
• Version info available at runtime for debugging