# copper-linux/copper architecture

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

- Interactive diagram: https://gitdiagram.com/copper-linux/copper
- Repository: https://github.com/copper-linux/copper

## Overview

Copper is a source-built Linux distribution with a custom live-boot path, PID 1, first-boot personalization, networking, and copper-sh. The principal workflow is booting the live image into a writable overlay, initializing the system, optionally personalizing it and starting DHCP, then presenting a login shell. The shell’s loop parses commands and dispatches builtins or external programs. Build-pipeline internals are omitted; the boot and service links reflect README documentation and the supplied source excerpts.

Main entry points: [`iso/src-init/copper-init.c`](https://github.com/copper-linux/copper/blob/main/iso/src-init/copper-init.c) (Copper PID 1), [`src/main.c`](https://github.com/copper-linux/copper/blob/main/src/main.c) (Shell loop and parser), [`iso/live/init`](https://github.com/copper-linux/copper/blob/main/iso/live/init) (Live initramfs), [`iso/boot/grub.cfg`](https://github.com/copper-linux/copper/blob/main/iso/boot/grub.cfg) (GRUB menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Live boot"]
  node_grub["GRUB menu<br/>[grub.cfg]"]
  node_liveinit["Live initramfs"]
  node_overlay["Writable root overlay"]
  node_kernel["Linux kernel"]
  node_iso["Copper live ISO"]
end

subgraph group_system["System services"]
  node_pid1["Copper PID 1<br/>[copper-init.c]"]
  node_network["Interface and DHCP setup<br/>[copper-init.c]"]
  node_dhcp["DHCP lease script<br/>[default.script]"]
end

subgraph group_setup["First boot"]
  node_wizard["First-boot wizard<br/>[copper-firstboot.c]"]
end

subgraph group_shell["Copper shell"]
  node_shell["Shell loop and parser<br/>[main.c]"]
  node_builtins["Builtin commands<br/>[builtins.c]"]
  node_shellapi["Builtin interface<br/>[builtins.h]"]
end

subgraph group_platform["System configuration"]
  node_busybox["BusyBox account tools"]
  node_programs["External commands"]
  node_rootconfig["Default root configuration"]
end

node_user(("Computer user"))

node_user -->|"selects boot"| node_grub
node_grub -->|"boots"| node_kernel
node_kernel -->|"starts"| node_liveinit
node_liveinit -->|"mounts root"| node_overlay
node_liveinit -->|"hands off"| node_pid1
node_pid1 -->|"reads settings"| node_rootconfig
node_pid1 -->|"starts"| node_network
node_network -->|"runs lease script"| node_dhcp
node_pid1 -->|"runs once"| node_wizard
node_wizard -->|"creates account"| node_busybox
node_pid1 -->|"starts tty login"| node_shell
node_user -->|"enters commands"| node_shell
node_shell -->|"uses interface"| node_shellapi
node_shell -->|"dispatches builtins"| node_builtins
node_shell -->|"executes external"| node_programs
node_iso -->|"contains boot menu"| node_grub

click node_grub "https://github.com/copper-linux/copper/blob/main/iso/boot/grub.cfg"
click node_liveinit "https://github.com/copper-linux/copper/blob/main/iso/live/init"
click node_overlay "https://github.com/copper-linux/copper/blob/main/iso/live/init"
click node_pid1 "https://github.com/copper-linux/copper/blob/main/iso/src-init/copper-init.c"
click node_network "https://github.com/copper-linux/copper/blob/main/iso/src-init/copper-init.c"
click node_dhcp "https://github.com/copper-linux/copper/blob/main/iso/rootfs-overlay/usr/share/udhcpc/default.script"
click node_wizard "https://github.com/copper-linux/copper/blob/main/iso/firstboot/copper-firstboot.c"
click node_busybox "https://github.com/copper-linux/copper/tree/main/iso"
click node_shell "https://github.com/copper-linux/copper/blob/main/src/main.c"
click node_builtins "https://github.com/copper-linux/copper/blob/main/src/builtins.c"
click node_shellapi "https://github.com/copper-linux/copper/blob/main/src/builtins.h"
click node_programs "https://github.com/copper-linux/copper/tree/main/iso"
click node_rootconfig "https://github.com/copper-linux/copper/tree/main/iso/rootfs-overlay"
click node_kernel "https://github.com/copper-linux/copper/tree/main/iso"
click node_iso "https://github.com/copper-linux/copper/tree/main/iso"

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_grub,node_liveinit,node_overlay,node_kernel,node_iso,node_user toneBlue
class node_pid1,node_network,node_dhcp toneAmber
class node_wizard toneMint
class node_shell,node_builtins,node_shellapi toneRose
class node_busybox,node_programs,node_rootconfig toneIndigo
```

## Components

### Live boot

- [GRUB menu](https://github.com/copper-linux/copper/blob/main/iso/boot/grub.cfg): `iso/boot/grub.cfg`
- [Live initramfs](https://github.com/copper-linux/copper/blob/main/iso/live/init): `iso/live/init`
- [Writable root overlay](https://github.com/copper-linux/copper/blob/main/iso/live/init): `iso/live/init`
- [Linux kernel](https://github.com/copper-linux/copper/tree/main/iso): `iso`
- [Copper live ISO](https://github.com/copper-linux/copper/tree/main/iso): `iso`

### System services

- [Copper PID 1](https://github.com/copper-linux/copper/blob/main/iso/src-init/copper-init.c): `iso/src-init/copper-init.c`
- [Interface and DHCP setup](https://github.com/copper-linux/copper/blob/main/iso/src-init/copper-init.c): `iso/src-init/copper-init.c`
- [DHCP lease script](https://github.com/copper-linux/copper/blob/main/iso/rootfs-overlay/usr/share/udhcpc/default.script): `iso/rootfs-overlay/usr/share/udhcpc/default.script`

### First boot

- [First-boot wizard](https://github.com/copper-linux/copper/blob/main/iso/firstboot/copper-firstboot.c): `iso/firstboot/copper-firstboot.c`

### Copper shell

- [Shell loop and parser](https://github.com/copper-linux/copper/blob/main/src/main.c): `src/main.c`
- [Builtin commands](https://github.com/copper-linux/copper/blob/main/src/builtins.c): `src/builtins.c`
- [Builtin interface](https://github.com/copper-linux/copper/blob/main/src/builtins.h): `src/builtins.h`

### System configuration

- [BusyBox account tools](https://github.com/copper-linux/copper/tree/main/iso): `iso`
- [External commands](https://github.com/copper-linux/copper/tree/main/iso): `iso`
- [Default root configuration](https://github.com/copper-linux/copper/tree/main/iso/rootfs-overlay): `iso/rootfs-overlay`

### Other components

- **Computer user**

## Connections

- Computer user → GRUB menu: selects boot
- GRUB menu → Linux kernel: boots
- Linux kernel → Live initramfs: starts
- Live initramfs → Writable root overlay: mounts root
- Live initramfs → Copper PID 1: hands off
- Copper PID 1 → Default root configuration: reads settings
- Copper PID 1 → Interface and DHCP setup: starts
- Interface and DHCP setup → DHCP lease script: runs lease script
- Copper PID 1 → First-boot wizard: runs once
- First-boot wizard → BusyBox account tools: creates account
- Copper PID 1 → Shell loop and parser: starts tty login
- Computer user → Shell loop and parser: enters commands
- Shell loop and parser → Builtin interface: uses interface
- Shell loop and parser → Builtin commands: dispatches builtins
- Shell loop and parser → External commands: executes external
- Copper live ISO → GRUB menu: contains boot menu