# abusoww/tuxmate architecture

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

- Interactive diagram: https://gitdiagram.com/abusoww/tuxmate
- Repository: https://github.com/abusoww/tuxmate

## Overview

1. **What this repo is**
   - TuxMate is a **Next.js 16 / React 19** application that generates **inspectable install commands and scripts** for Linux software setup.
   - It is primarily a **frontend-only product**: users choose apps and a target platform, and the app produces install output locally rather than running installs on their behalf.

2. **Top-level runtime boundary**
   - The app is organized around the **Next.js App Router** in `src/app/`, with `page.tsx` as the main entry, `layout.tsx` for global shell/styling, and `error.tsx` as the UI boundary for runtime failures.
   - `globals.css` provides the global visual baseline for the whole site.

3. **Core data model: the app catalog**
   - `src/lib/apps/*.json` is the main catalog source of truth, split by category such as dev tools, browsers, media, office, gaming, security, and more.
   - `src/lib/data.ts` likely aggregates and normalizes this catalog into the shape used by the UI and script generator.
   - Supporting data files like `aur-packages.json`, `nix-unfree.json`, `verified-flatpaks.json`, and `verified-snaps.json` add distro-specific metadata and verification signals.

4. **Script generation engine**
   - `src/lib/generateInstallScript.ts` is the orchestration layer that turns selected apps + distro context into output commands/scripts.
   - The actual distro implementations live under `src/lib/scripts/`, separated by target: `arch.ts`, `debian.ts`, `ubuntu.ts`, `fedora.ts`, `opensuse.ts`, `homebrew.ts`, `flatpak.ts`, `snap.ts`, and `nix.ts`.
   - `shared.ts` holds common shell/output logic, which suggests the generator is composed from reusable primitives rather than duplicated per distro.

5. **Distro-specific decision boundaries**
   - The architecture distinguishes between **native package managers** and **universal package systems**.
   - Native paths cover apt, pacman/AUR, dnf, zypper, nixpkgs, and Homebrew.
   - When a native mapping is missing, the generator falls back to broader mechanisms such as Flatpak, Snap, or script-based handling, matching the README’s “native-first resolution” behavior.

6. **Verification and trust metadata**
   - `src/lib/aur.ts`, `src/lib/verification.ts`, and `src/lib/nixUnfree.ts` add policy-aware checks around package choice.
   - The repo explicitly models trust signals such as **AUR allowlisting**, **verified Flatpak/Snap badges**, and **Nix unfree package warnings**.
   - This means the architecture is not just a lookup table; it includes a validation layer that shapes what the UI can safely present.

7. **UI composition**
   - UI components are grouped by function:
     - `src/components/app/` for the application catalog and category sections
     - `src/components/command/` for command output, drawers, popovers, and footer actions
     - `src/components/distro/` for distro selection and icons
     - `src/components/search/` for search overlay
     - `src/components/sidebar/` for navigation/filtering
     - `src/components/header/` for top-level informational links
     - `src/components/common/` and `src/components/ui/` for shared primitives
   - This suggests a **single interactive workspace** where selection, filtering, and command generation happen in one screen rather than across multiple routes.

8. **Interaction/state layer**
   - Hooks in `src/hooks/` coordinate behavior that crosses components:
     - `useKeyboardNavigation` for Vim/arrows/Enter/Esc style control
     - `useTheme` for light/dark theme state
     - `useTooltip` and `useDelayedTooltip` for hover behavior
     - `useVerification` for package trust/status presentation
     - `useLinuxInit` for Linux-specific initialization logic
   - These hooks indicate the app is heavily stateful on the client side, with a focus on fast keyboard-driven workflows.

9. **User flow through the system**
   - The likely flow is: **pick distro → browse/search apps → inspect category/package availability → generate command/script → copy or download**.
   - `src/components/command/` is the key output surface, while the app catalog and verification layers feed it the selected package data and warnings.
   - The README’s emphasis on “copy and run commands yourself” matches this architecture: the app is a **generator and reviewer**, not an execution engine.

10. **PWA and offline resilience**
   - `public/manifest.json` and `public/sw.js` show that the site is also a **Progressive Web App**.
   - The service worker uses a network-first strategy for resilient loading, which is important because the app’s value is largely static catalog + script generation and benefits from offline/poor-network usability.

11. **Analytics and observability**
   - `src/lib/analytics.ts` suggests a small client-side analytics boundary, but there is no sign of a heavier backend telemetry pipeline.
   - The architecture still appears fundamentally frontend-centric, with analytics as an auxiliary concern rather than a core subsystem.

12. **Testing and quality gates**
   - `src/__tests__/` contains focused Vitest coverage for data handling, AUR logic, shell escaping, and script behavior.
   - This is a strong signal that the main risk area is **correct command generation**, so tests concentrate on deterministic library logic rather than broad UI snapshotting.

13. **Build and deployment**
   - The repo supports multiple deployment paths: local Next.js dev/build, Docker (`Dockerfile`, `docker-compose.yml`), and CI/CD via GitHub Actions.
   - `wrangler.json` suggests Cloudflare-oriented deployment is also part of the architecture.
   - In other words, the app is packaged as a static-ish web experience that can be deployed in containerized or edge-hosted environments.

14. **Overall architecture summary**
   - The repository is best understood as three layers: **catalog data**, **script-generation logic**, and **interactive UI**.
   - Data flows from curated JSON registries into verification and resolution logic, then into distro-specific command generation, and finally into a client-side command drawer/searchable catalog experience.
   - The architecture is intentionally transparent: it optimizes for user inspection, distro accuracy, and low-trust execution rather than automation.

Main entry points: [`src/app/page.tsx`](https://github.com/abusoww/tuxmate/blob/main/src/app/page.tsx) (Home page), [`src/lib/data.ts`](https://github.com/abusoww/tuxmate/blob/main/src/lib/data.ts) (Catalog normalizer), [`src/components/command`](https://github.com/abusoww/tuxmate/tree/main/src/components/command) (Command panel), [`src/lib/verification.ts`](https://github.com/abusoww/tuxmate/blob/main/src/lib/verification.ts) (Verification layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App shell"]
  node_src_app_page["Home page<br/>Next.js entry<br/>[page.tsx]"]
  node_src_app_layout["App layout<br/>Next.js shell<br/>[layout.tsx]"]
  node_src_app_error["Error boundary<br/>UI boundary<br/>[error.tsx]"]
  node_src_app_globals["Global styles<br/>CSS baseline<br/>[globals.css]"]
end

subgraph group_catalog["Catalog data"]
  node_src_lib_apps[("App catalog<br/>JSON registry")]
  node_src_lib_data["Catalog normalizer<br/>data model<br/>[data.ts]"]
  node_src_lib_metadata[("Trust metadata<br/>policy data<br/>[aur-packages.json]")]
  node_src_lib_verification["Verification layer<br/>policy checks<br/>[verification.ts]"]
end

subgraph group_generation["Script generation"]
  node_src_lib_generator["Script orchestrator<br/>generator"]
  node_src_lib_scripts_index["Script registry<br/>dispatch<br/>[index.ts]"]
  node_src_lib_scripts_shared["Shared output<br/>shell helpers<br/>[shared.ts]"]
  node_src_lib_scripts_distros["Distro scripts<br/>package managers<br/>[arch.ts]"]
end

subgraph group_ui["Interactive UI"]
  node_src_components_app["Catalog UI<br/>component set"]
  node_src_components_command["Command panel<br/>component set"]
  node_src_components_distro["Distro picker<br/>component set"]
  node_src_components_search["Search overlay<br/>component set"]
  node_src_components_sidebar["Sidebar nav<br/>component set"]
  node_src_components_header["Header links<br/>component set"]
  node_src_hooks["Client hooks<br/>state hooks"]
end

subgraph group_platform["Platform layer"]
  node_public_pwa["PWA assets<br/>manifest/service worker<br/>[manifest.json]"]
  node_src_lib_analytics["Analytics<br/>client telemetry<br/>[analytics.ts]"]
  node_tests["Core tests<br/>vitest suite<br/>[data.test.ts]"]
end

node_src_app_page -->|"renders"| node_src_components_app
node_src_app_page -->|"selects distro"| node_src_components_distro
node_src_app_page -->|"searches"| node_src_components_search
node_src_app_page -->|"filters"| node_src_components_sidebar
node_src_app_page -->|"shows output"| node_src_components_command
node_src_app_layout -->|"loads"| node_src_app_globals
node_src_lib_apps -->|"normalized by"| node_src_lib_data
node_src_lib_metadata -->|"feeds"| node_src_lib_verification
node_src_lib_data -->|"selected apps"| node_src_lib_generator
node_src_lib_verification -->|"badges"| node_src_components_command
node_src_lib_generator -->|"dispatches"| node_src_lib_scripts_index
node_src_lib_scripts_index -->|"uses"| node_src_lib_scripts_shared
node_src_lib_scripts_index -->|"targets"| node_src_lib_scripts_distros
node_src_lib_scripts_distros -->|"shares"| node_src_lib_scripts_shared
node_src_components_command -->|"requests"| node_src_lib_generator
node_src_components_command -->|"shows trust"| node_src_lib_verification
node_src_components_distro -->|"sets target"| node_src_lib_generator
node_src_components_search -->|"queries"| node_src_lib_data
node_src_components_sidebar -->|"filters catalog"| node_src_lib_data
node_src_components_header -.->|"triggers"| node_src_lib_analytics
node_public_pwa -->|"supports shell"| node_src_app_layout
node_tests -->|"validates"| node_src_lib_data
node_tests -->|"validates"| node_src_lib_verification
node_tests -->|"validates"| node_src_lib_scripts_distros

click node_src_app_page "https://github.com/abusoww/tuxmate/blob/main/src/app/page.tsx"
click node_src_app_layout "https://github.com/abusoww/tuxmate/blob/main/src/app/layout.tsx"
click node_src_app_error "https://github.com/abusoww/tuxmate/blob/main/src/app/error.tsx"
click node_src_app_globals "https://github.com/abusoww/tuxmate/blob/main/src/app/globals.css"
click node_src_lib_apps "https://github.com/abusoww/tuxmate/tree/main/src/lib/apps"
click node_src_lib_data "https://github.com/abusoww/tuxmate/blob/main/src/lib/data.ts"
click node_src_lib_metadata "https://github.com/abusoww/tuxmate/blob/main/src/lib/aur-packages.json"
click node_src_lib_verification "https://github.com/abusoww/tuxmate/blob/main/src/lib/verification.ts"
click node_src_lib_generator "https://github.com/abusoww/tuxmate/blob/main/src/lib/generateInstallScript.ts"
click node_src_lib_scripts_index "https://github.com/abusoww/tuxmate/blob/main/src/lib/scripts/index.ts"
click node_src_lib_scripts_shared "https://github.com/abusoww/tuxmate/blob/main/src/lib/scripts/shared.ts"
click node_src_lib_scripts_distros "https://github.com/abusoww/tuxmate/blob/main/src/lib/scripts/arch.ts"
click node_src_components_app "https://github.com/abusoww/tuxmate/tree/main/src/components/app"
click node_src_components_command "https://github.com/abusoww/tuxmate/tree/main/src/components/command"
click node_src_components_distro "https://github.com/abusoww/tuxmate/tree/main/src/components/distro"
click node_src_components_search "https://github.com/abusoww/tuxmate/tree/main/src/components/search"
click node_src_components_sidebar "https://github.com/abusoww/tuxmate/tree/main/src/components/sidebar"
click node_src_components_header "https://github.com/abusoww/tuxmate/tree/main/src/components/header"
click node_src_hooks "https://github.com/abusoww/tuxmate/blob/main/src/hooks/useKeyboardNavigation.ts"
click node_public_pwa "https://github.com/abusoww/tuxmate/blob/main/public/manifest.json"
click node_src_lib_analytics "https://github.com/abusoww/tuxmate/blob/main/src/lib/analytics.ts"
click node_tests "https://github.com/abusoww/tuxmate/blob/main/src/__tests__/data.test.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_src_app_page,node_src_app_layout,node_src_app_error,node_src_app_globals toneBlue
class node_src_lib_apps,node_src_lib_data,node_src_lib_metadata,node_src_lib_verification toneAmber
class node_src_lib_generator,node_src_lib_scripts_index,node_src_lib_scripts_shared,node_src_lib_scripts_distros toneMint
class node_src_components_app,node_src_components_command,node_src_components_distro,node_src_components_search,node_src_components_sidebar,node_src_components_header,node_src_hooks toneRose
class node_public_pwa,node_src_lib_analytics,node_tests toneIndigo
```

## Components

### App shell

Next.js App Router entry and global presentation boundary

- [Home page](https://github.com/abusoww/tuxmate/blob/main/src/app/page.tsx): Next.js entry · Main interactive workspace entry point · `src/app/page.tsx`
- [App layout](https://github.com/abusoww/tuxmate/blob/main/src/app/layout.tsx): Next.js shell · Global frame, metadata, and styling scaffold · `src/app/layout.tsx`
- [Error boundary](https://github.com/abusoww/tuxmate/blob/main/src/app/error.tsx): UI boundary · App Router runtime failure handling · `src/app/error.tsx`
- [Global styles](https://github.com/abusoww/tuxmate/blob/main/src/app/globals.css): CSS baseline · Site-wide visual reset and theme baseline · `src/app/globals.css`

### Catalog data

App registry and normalization layer

- [App catalog](https://github.com/abusoww/tuxmate/tree/main/src/lib/apps): JSON registry · Category-split source of software entries · `src/lib/apps`
- [Catalog normalizer](https://github.com/abusoww/tuxmate/blob/main/src/lib/data.ts): data model · Aggregates and normalizes catalog data for the UI · `src/lib/data.ts`
- [Trust metadata](https://github.com/abusoww/tuxmate/blob/main/src/lib/aur-packages.json): policy data · AUR, Nix unfree, and verified package signals · `src/lib/aur-packages.json`
- [Verification layer](https://github.com/abusoww/tuxmate/blob/main/src/lib/verification.ts): policy checks · Package trust and verification helpers · `src/lib/verification.ts`

### Script generation

Resolution and distro-specific command builders

- [Script orchestrator](https://github.com/abusoww/tuxmate/blob/main/src/lib/generateInstallScript.ts): generator · Turns selections and distro context into install output · `src/lib/generateInstallScript.ts`
- [Script registry](https://github.com/abusoww/tuxmate/blob/main/src/lib/scripts/index.ts): dispatch · Selects the target generator implementation · `src/lib/scripts/index.ts`
- [Shared output](https://github.com/abusoww/tuxmate/blob/main/src/lib/scripts/shared.ts): shell helpers · Reusable command and script primitives · `src/lib/scripts/shared.ts`
- [Distro scripts](https://github.com/abusoww/tuxmate/blob/main/src/lib/scripts/arch.ts): package managers · Native and universal installers for Arch, Debian, Fedora, openSUSE, Ubuntu, Homebrew, Flatpak, Snap, and Nix · `src/lib/scripts/arch.ts`

### Interactive UI

Selection, search, and command output experience

- [Catalog UI](https://github.com/abusoww/tuxmate/tree/main/src/components/app): component set · Category sections, items, and app icons · `src/components/app`
- [Command panel](https://github.com/abusoww/tuxmate/tree/main/src/components/command): component set · Output drawer, footer actions, and AUR-related affordances · `src/components/command`
- [Distro picker](https://github.com/abusoww/tuxmate/tree/main/src/components/distro): component set · Distribution selection and iconography · `src/components/distro`
- [Search overlay](https://github.com/abusoww/tuxmate/tree/main/src/components/search): component set · Global app search and quick filtering · `src/components/search`
- [Sidebar nav](https://github.com/abusoww/tuxmate/tree/main/src/components/sidebar): component set · Navigation and filtering rail · `src/components/sidebar`
- [Header links](https://github.com/abusoww/tuxmate/tree/main/src/components/header): component set · Informational and contributor links · `src/components/header`
- [Client hooks](https://github.com/abusoww/tuxmate/blob/main/src/hooks/useKeyboardNavigation.ts): state hooks · Keyboard, theme, tooltip, verification, and Linux init behavior · `src/hooks/useKeyboardNavigation.ts`

### Platform layer

PWA, analytics, deployment, and test signals

- [PWA assets](https://github.com/abusoww/tuxmate/blob/main/public/manifest.json): manifest/service worker · Offline-capable app shell and runtime caching · `public/manifest.json`
- [Analytics](https://github.com/abusoww/tuxmate/blob/main/src/lib/analytics.ts): client telemetry · Lightweight usage tracking boundary · `src/lib/analytics.ts`
- [Core tests](https://github.com/abusoww/tuxmate/blob/main/src/__tests__/data.test.ts): vitest suite · Focused coverage for catalog, AUR, shell escaping, and script logic · `src/__tests__/data.test.ts`

## Connections

- Home page → Catalog UI: renders · Main page composes catalog browsing UI
- Home page → Distro picker: selects distro · Workspace starts with target platform choice
- Home page → Search overlay: searches · Provides app discovery and filtering
- Home page → Sidebar nav: filters · Uses navigation and category filtering
- Home page → Command panel: shows output · Displays generated commands and script actions
- App layout → Global styles: loads · Global shell applies site-wide styling
- App catalog → Catalog normalizer: normalized by · Raw catalog entries are aggregated into the app model
- Trust metadata → Verification layer: feeds · Trust data powers verification and warning logic
- Catalog normalizer → Script orchestrator: selected apps · Normalized catalog items become generator inputs
- Verification layer → Command panel: badges · Trust status is surfaced in the output area
- Script orchestrator → Script registry: dispatches · Orchestrator chooses the proper target implementation
- Script registry → Shared output: uses · Registry composes common shell primitives
- Script registry → Distro scripts: targets · Registry routes to distro-specific installers
- Distro scripts → Shared output: shares · Native and universal installers reuse shell helpers
- Command panel → Script orchestrator: requests · UI asks for install output based on current selection
- Command panel → Verification layer: shows trust · Command surface reflects verification status
- Distro picker → Script orchestrator: sets target · Chosen distro controls command generation
- Search overlay → Catalog normalizer: queries · Search operates over the normalized catalog
- Sidebar nav → Catalog normalizer: filters catalog · Sidebar constrains visible apps and categories
- Header links → Analytics: triggers · Top-level interactions can be measured lightly
- PWA assets → App layout: supports shell · Manifest and service worker reinforce app shell delivery
- Core tests → Catalog normalizer: validates · Coverage protects catalog normalization behavior
- Core tests → Verification layer: validates · Coverage checks trust and policy logic
- Core tests → Distro scripts: validates · Coverage exercises command generation paths
