Architecture & Repository Layout

Where things live in the repository, how a build turns them into one PS2 ELF, and the runtime rules that keep the console stable.

Repository layout

Path	Contents
`src/`, `include/`	The EE application. `dash_.c` is the dashboard (home, apps, files, tools, settings, themes, sound, worker thread, PNG/JPEG viewers, widgets); `filer.c` is the File Browser and copy engine; `main.c` is boot, MISC command dispatch and info screens; `config.c` is classic `LAUNCHELF.CNF` and network settings; `init.c` loads and resets IOP driver stacks on demand; `cloud_http.c`, `cloud_google.c`, `self_update.c`, `update_psu.c` are the native HTTPS, Google Drive and updater code; `mmce_backup.c`, `mmce_igr.c`, `mc_card_export.c` are backup/recovery; `neutrino_iso.c`, `popstarter.c`, `ember.c` are the external-core handoffs; `remote_control.c` and `pc_game_receiver.c` are the PC file protocols; `hdd*.c` and `hdl_rpc.c` are APA/HDL management; `pad.c`/`pad_ds34.c` are controller input; `embed_blobs.S` embeds plain binary payloads.
`iop/`	IOP (I/O processor) modules. Source-built with `ps2.yaml` targets: `udpfs_smap`, `ps2ips_rpc` (vendored PS2IP socket RPC server used by dashboard network clients such as clock sync), `usbd-ra`, `mmceman`, `vmcman`, `ps2hdd_osd`, `ata_bd`, `hdl_info`, `xparam`, `AllowDVDV`, `dev9_poweroff`, `smbman` (SMB1), `ps2host` (PS2Link file I/O), `oldlibs/ps2ftpd`, `pccf` (PC CARD CF). Optional `ds34usb`/`ds34bt` for the DualShock variant. `__precompiled/` holds the embedded UDPFS ministack and ioman peers, the embedded `smb2man.irx` SMB2/SMB3 driver (origin recorded in `SMB2MAN.md`), and the defective historical `udpfs_smap.irx` that the check script verifies is not embedded; every other module is a `ps2.yaml` target or an SDK package. `__v10/` holds the PS2SDK v1.0 DEV9/PS2IP fallback pair.
`ee_libs/`	EE libraries built by `ps2.yaml` because the SDK does not supply them in a usable form: `iopreboot` (`SifIopRebootBuffer`) and `hdd` (libhdd). Sound uses the SDK `audsrv-compat` package and the SDK `audio` driver, not code in this tree.
`loader/`, `igr/`	Two small separate ELFs embedded into the main one. `loader` is the ELF loader linked into the low-memory window `0x84000..0xa0000`; `igr/wle_igr.c` is the WLE-IGR trampoline installed for OPL Exit-to returns.
`exploits/`, `res/`, `Lang/`	Embedded payloads: memory-card exploit installer files (installer); UI sound effects, updater CA, BGM sidecar, button icons and the cloud config template; the nine built-in language tables.
`scripts/`	Build helpers, CI checks, packaging, release notes, wiki sync and host tools. See Building from Source.
`tests/`	Host-side regression tests (plain Python scripts, many compiling production C against stubs). See Contributing & Testing.
`docs/`, `docs-site/`	Maintainer notes and wiki guides in `docs/`; the published website source in `docs-site/` (`content/*.html`, `manifest.json`, `static/`, `build.py`).
`windows/`, `research/`, `__Headers/`	The optional Windows rclone cloud relay; a non-shipping sd2psXtd restore-transaction reference model; sample APA injection headers.
`.github/`, `.claude/`	Workflows (`compile.yml`, `docs-pages.yml`, `sync-wiki.yml`), the issue form, and the Claude cloud-session hook.
`ps2.yaml`, `iop/pccf/ps2.yaml`	PS2BUILD project definitions (the only build path).

How the build fits together

ps2.yaml declares IOP targets, EE libraries, the loader, the WLE-IGR helper and the main wLaunchELF target. IOP modules built here, SDK driver packages and the loader/IGR ELFs are listed under embed_irx: and become byte arrays inside the main ELF; plain files are embedded by src/embed_blobs.S. Feature flags (MMCE, MX4SIO, ETH, UDPFS, EXFAT, ILINK, DVRP, XFROM, DS34, WLE_NATIVE_CLOUD and others) are defines: on that target and gate code with #ifdef. The DualShock build is generated from the same file, so the two variants cannot drift. Everything is then packed with ps2pack and wrapped into the ZIP/PSU packages. Full commands are in Building from Source.

Runtime rules

One shell. main() performs early boot, input and display initialization, optional IGR backup, then calls DashRun(), which never returns. Settings, the File Browser, HDD Manager, Text Editor and exploit installer are dashboard screens.
Lazy drivers. Embedding a module only places it in the ELF; init.c decides when to load it, and each load_* function checks whether the stack is already resident. Storage and network stacks normally start when requested. Configured application scans, optional automatic startup services and IGR backup can also require them; embedding alone does not start a service.
Exclusive stacks. Some families cannot coexist (ETH versus UDPFS networking, MMCE versus MX4SIO on the same SIO2 bus, PS2 versus PSX HDD stacks, the PC CARD CF driver versus DEV9). Switching between them normally resets the IOP and clears residency tracking so the next access reloads what it needs (the PSX APA/DVR HDD stacks are the exception: they load without a reset). Neutrino quick-boot reuses the mounted stack; Ember's USB path performs a controlled clean rebuild first.
Background worker. One EE thread (dash_worker.c) runs queued file, memory-card and driver jobs at lower priority; while it runs the UI thread does no I/O of its own, jobs never draw or show dialogs, and completion callbacks run back on the UI thread. Anything that reboots the IOP or launches an ELF first drains the queue. Some USB and device probes are still synchronous IOP calls and can block on failing hardware.
Persistence. Dashboard state uses DASHBOARD.CNF, DASHAPPS.CNF and DASHLIB.CNF. Settings also exposes classic launch/tool options that are saved to LAUNCHELF.CNF, plus network configuration saved separately. The Settings session has explicit Save/Discard behavior; some direct actions, such as exporting a theme or saving launch/tool settings to another folder, write immediately. See Configuration for paths and file roles.
Safety first for backups. MMCE history is written to .PART files, verified and renamed; recovery produces new files and never overwrites an active card; direct restore stays disabled (research/sd2psxtd is a reference model only and is not linked into any ELF).

Refactoring status

The oversized legacy files have been split along behavior-neutral lines: main.c into main_actions, main_boot, main_modules, main_menu, main_info_screens, main_gameid and others; filer.c into filer_device, filer_mount, filer_fileops, filer_actions, filer_browser, filer_copy, gui_sort, gui_texteditor, gui_hdd0_format and psu_functions; PSU layout structs are shared via include/psu_types.h. The classic JPG-viewer subsystem was removed; images are viewed by the dashboard's bounded PNG (dash_png.c) and JPEG (dash_jpeg.c, libjpeg-turbo) decoders. The largest hand-written files now are dash_settings.c, dash_browser.c, init.c, main_exploit_installer.c and filer_browser.c (sh scripts/stale_code_audit.sh lists the top ten). Keep each further split behavior-neutral and verify it in an emulator and on real hardware.

Maintainer notes

More detail for maintainers lives in docs/architecture-maintenance.md, Building from Source, the dashboard reference docs/dashboard.md and the dated plans and audits under docs/plans/.