# aylur/ags architecture

> Architecture diagram of the GitHub repository aylur/ags, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aylur/ags
- Repository: https://github.com/aylur/ags

## Overview

AGS is a scaffolding CLI for Astal/Gnim desktop-shell projects, alongside a GJS runtime library for GTK3/GTK4 applications. The documented starter flow is to use the CLI to scaffold a project and then run an application; command-level links are limited because the supplied excerpts do not show those implementations. The runtime excerpts show app startup, D-Bus control, compatibility patches, and process-backed polling. Other library exports are represented as capabilities without inferred call paths.

Main entry points: [`lib/overrides.ts`](https://github.com/aylur/ags/blob/main/lib/overrides.ts) (Astal Compatibility), [`lib/app/dbus.ts`](https://github.com/aylur/ags/blob/main/lib/app/dbus.ts) (App D-Bus Service), [`lib/gtk3/app.ts`](https://github.com/aylur/ags/blob/main/lib/gtk3/app.ts) (GTK3 App Runtime), [`lib/gtk4/app.ts`](https://github.com/aylur/ags/blob/main/lib/gtk4/app.ts) (GTK4 App Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Scaffolding CLI"]
  node_cli_main["CLI Entrypoint<br/>[main.go]"]
  node_cli_commands["Command Framework<br/>[root.go]"]
  node_project_init["Project Init<br/>[init.go]"]
  node_project_bundle["Project Bundling<br/>[bundle.go]"]
  node_project_run["Run Projects<br/>[run.go]"]
  node_instance_commands["Instance Controls<br/>[list.go]"]
  node_instance_request["Instance Requests<br/>[request.go]"]
  node_instance_inspect["Inspect Instance<br/>[inspect.go]"]
end

subgraph group_templates["Starter Projects"]
  node_gtk3_starter["GTK3 Starter<br/>[app.ts]"]
  node_gtk3_bar["GTK3 Bar<br/>[Bar.tsx]"]
  node_gtk4_starter["GTK4 Starter<br/>[app.ts]"]
  node_gtk4_bar["GTK4 Bar<br/>[Bar.tsx]"]
end

subgraph group_apps["GTK Applications"]
  node_gtk3_app["GTK3 App Runtime<br/>[app.ts]"]
  node_gtk4_app["GTK4 App Runtime<br/>[app.ts]"]
  node_app_control["App D-Bus Service<br/>[dbus.ts]"]
  node_app_management["App Management API<br/>[index.ts]"]
  node_jsx_gtk3["GTK3 JSX Runtime<br/>[jsx-runtime.ts]"]
  node_jsx_gtk4["GTK4 JSX Runtime<br/>[jsx-runtime.ts]"]
end

subgraph group_runtime["Runtime Utilities"]
  node_compat_patches["Astal Compatibility<br/>[overrides.ts]"]
  node_process_api["Process API<br/>[process.ts]"]
  node_time_api["Timers And Polling<br/>[time.ts]"]
  node_file_api["File Utilities<br/>[file.ts]"]
  node_other_apis["Other Runtime Exports<br/>[fetch.ts]"]
end

node_user(("Project Developer"))
node_astal_extensions["Astal GI Extensions"]

node_user -->|"uses"| node_cli_main
node_cli_main -->|"initializes and executes"| node_cli_commands
node_gtk3_app -->|"constructs service"| node_app_control
node_gtk4_app -->|"constructs service"| node_app_control
node_app_management -->|"proxies calls"| node_app_control
node_gtk3_app -->|"imports patches"| node_compat_patches
node_gtk4_app -->|"imports patches"| node_compat_patches
node_time_api -->|"executes commands"| node_process_api
node_compat_patches -.->|"patches when available"| node_astal_extensions

click node_cli_main "https://github.com/aylur/ags/blob/main/cli/main.go"
click node_cli_commands "https://github.com/aylur/ags/blob/main/cli/cmd/root.go"
click node_project_init "https://github.com/aylur/ags/blob/main/cli/cmd/init.go"
click node_project_bundle "https://github.com/aylur/ags/blob/main/cli/cmd/bundle.go"
click node_project_run "https://github.com/aylur/ags/blob/main/cli/cmd/run.go"
click node_instance_commands "https://github.com/aylur/ags/blob/main/cli/cmd/list.go"
click node_instance_request "https://github.com/aylur/ags/blob/main/cli/cmd/request.go"
click node_instance_inspect "https://github.com/aylur/ags/blob/main/cli/cmd/inspect.go"
click node_gtk3_starter "https://github.com/aylur/ags/blob/main/cli/data/gtk3/app.ts"
click node_gtk3_bar "https://github.com/aylur/ags/blob/main/cli/data/gtk3/Bar.tsx"
click node_gtk4_starter "https://github.com/aylur/ags/blob/main/cli/data/gtk4/app.ts"
click node_gtk4_bar "https://github.com/aylur/ags/blob/main/cli/data/gtk4/Bar.tsx"
click node_gtk3_app "https://github.com/aylur/ags/blob/main/lib/gtk3/app.ts"
click node_gtk4_app "https://github.com/aylur/ags/blob/main/lib/gtk4/app.ts"
click node_app_control "https://github.com/aylur/ags/blob/main/lib/app/dbus.ts"
click node_app_management "https://github.com/aylur/ags/blob/main/lib/app/index.ts"
click node_jsx_gtk3 "https://github.com/aylur/ags/blob/main/lib/gtk3/jsx-runtime.ts"
click node_jsx_gtk4 "https://github.com/aylur/ags/blob/main/lib/gtk4/jsx-runtime.ts"
click node_compat_patches "https://github.com/aylur/ags/blob/main/lib/overrides.ts"
click node_process_api "https://github.com/aylur/ags/blob/main/lib/process.ts"
click node_time_api "https://github.com/aylur/ags/blob/main/lib/time.ts"
click node_file_api "https://github.com/aylur/ags/blob/main/lib/file.ts"
click node_other_apis "https://github.com/aylur/ags/blob/main/lib/fetch.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_main,node_cli_commands,node_project_init,node_project_bundle,node_project_run,node_instance_commands,node_instance_request,node_instance_inspect toneBlue
class node_gtk3_starter,node_gtk3_bar,node_gtk4_starter,node_gtk4_bar toneAmber
class node_gtk3_app,node_gtk4_app,node_app_control,node_app_management,node_jsx_gtk3,node_jsx_gtk4 toneMint
class node_compat_patches,node_process_api,node_time_api,node_file_api,node_other_apis toneRose
class node_user,node_astal_extensions toneIndigo
```

## Components

### Scaffolding CLI

- [CLI Entrypoint](https://github.com/aylur/ags/blob/main/cli/main.go): `cli/main.go`
- [Command Framework](https://github.com/aylur/ags/blob/main/cli/cmd/root.go): `cli/cmd/root.go`
- [Project Init](https://github.com/aylur/ags/blob/main/cli/cmd/init.go): `cli/cmd/init.go`
- [Project Bundling](https://github.com/aylur/ags/blob/main/cli/cmd/bundle.go): `cli/cmd/bundle.go`
- [Run Projects](https://github.com/aylur/ags/blob/main/cli/cmd/run.go): `cli/cmd/run.go`
- [Instance Controls](https://github.com/aylur/ags/blob/main/cli/cmd/list.go): `cli/cmd/list.go`
- [Instance Requests](https://github.com/aylur/ags/blob/main/cli/cmd/request.go): `cli/cmd/request.go`
- [Inspect Instance](https://github.com/aylur/ags/blob/main/cli/cmd/inspect.go): `cli/cmd/inspect.go`

### Starter Projects

- [GTK3 Starter](https://github.com/aylur/ags/blob/main/cli/data/gtk3/app.ts): `cli/data/gtk3/app.ts`
- [GTK3 Bar](https://github.com/aylur/ags/blob/main/cli/data/gtk3/Bar.tsx): `cli/data/gtk3/Bar.tsx`
- [GTK4 Starter](https://github.com/aylur/ags/blob/main/cli/data/gtk4/app.ts): `cli/data/gtk4/app.ts`
- [GTK4 Bar](https://github.com/aylur/ags/blob/main/cli/data/gtk4/Bar.tsx): `cli/data/gtk4/Bar.tsx`

### GTK Applications

- [GTK3 App Runtime](https://github.com/aylur/ags/blob/main/lib/gtk3/app.ts): `lib/gtk3/app.ts`
- [GTK4 App Runtime](https://github.com/aylur/ags/blob/main/lib/gtk4/app.ts): `lib/gtk4/app.ts`
- [App D-Bus Service](https://github.com/aylur/ags/blob/main/lib/app/dbus.ts): `lib/app/dbus.ts`
- [App Management API](https://github.com/aylur/ags/blob/main/lib/app/index.ts): `lib/app/index.ts`
- [GTK3 JSX Runtime](https://github.com/aylur/ags/blob/main/lib/gtk3/jsx-runtime.ts): `lib/gtk3/jsx-runtime.ts`
- [GTK4 JSX Runtime](https://github.com/aylur/ags/blob/main/lib/gtk4/jsx-runtime.ts): `lib/gtk4/jsx-runtime.ts`

### Runtime Utilities

- [Astal Compatibility](https://github.com/aylur/ags/blob/main/lib/overrides.ts): `lib/overrides.ts`
- [Process API](https://github.com/aylur/ags/blob/main/lib/process.ts): `lib/process.ts`
- [Timers And Polling](https://github.com/aylur/ags/blob/main/lib/time.ts): `lib/time.ts`
- [File Utilities](https://github.com/aylur/ags/blob/main/lib/file.ts): `lib/file.ts`
- [Other Runtime Exports](https://github.com/aylur/ags/blob/main/lib/fetch.ts): `lib/fetch.ts`

### Other components

- **Project Developer**
- **Astal GI Extensions**

## Connections

- Project Developer → CLI Entrypoint: uses (evidence: `README.md`)
- CLI Entrypoint → Command Framework: initializes and executes (evidence: `cli/main.go`)
- GTK3 App Runtime → App D-Bus Service: constructs service (evidence: `lib/gtk3/app.ts`)
- GTK4 App Runtime → App D-Bus Service: constructs service (evidence: `lib/gtk4/app.ts`)
- App Management API → App D-Bus Service: proxies calls (evidence: `lib/app/index.ts`)
- GTK3 App Runtime → Astal Compatibility: imports patches (evidence: `lib/gtk3/app.ts`)
- GTK4 App Runtime → Astal Compatibility: imports patches (evidence: `lib/gtk4/app.ts`)
- Timers And Polling → Process API: executes commands (evidence: `lib/time.ts`)
- Astal Compatibility → Astal GI Extensions: patches when available (evidence: `lib/overrides.ts`)
