NXST/docs/ARCHITECTURE.md

# NXST Architecture

## Layer Diagram

```
                ┌──────────────────────────────┐
                │          ui/                 │
                │  TitlesLayout, UsersLayout   │
                │  TransferOverlay, HeaderBar  │
                └──────────────┬───────────────┘
                               │ calls
                ┌──────────────▼───────────────┐
                │         service/             │
                │      TransferService         │
                └──────┬───────────────┬───────┘
                       │               │
          ┌────────────▼──┐    ┌───────▼────────┐
          │   infra/net/  │    │   infra/fs/    │
          │ TransferService│   │  io, directory │
          │ (sender thread │   │  filesystem    │
          │  recv threads) │   │  handles       │
          └────────────┬──┘    └───────┬────────┘
                       │               │
          ┌────────────▼───────────────▼────────┐
          │              domain/                │
          │  Title, Account, TransferState      │
          │  Result<T>, protocol constants      │
          └─────────────────────────────────────┘
                               │
          ┌────────────────────▼────────────────┐
          │    libnx, Plutonium, SDL2, devkitpro│
          └─────────────────────────────────────┘
```

**Hard layering rules:**
- `domain/` depends on nothing in the project.
- `infra/` depends only on `domain/`.
- `service/` depends on `domain/` + `infra/`.
- `ui/` depends only on `service/` + `domain/` — must not include `<arpa/inet.h>`, `<sys/socket.h>`, `<pthread.h>`, or call `recv`/`send` directly.
- `app/` (MainApplication, main.cpp) wires everything together.

---

## Key Types

### `nxst::TransferService` (`include/nxst/service/transfer_service.hpp`)

Owns all network state for both transfer directions. One instance lives in `MainApplication`.

| Method | Description |
|--------|-------------|
| `startSend(index, uid)` | Backup save, discover receiver, stream files |
| `startReceive(index, uid, title_name)` | Listen for sender, receive files, restore save |
| `cancelSend()` / `cancelReceive()` | Interrupt in-flight transfer (socket shutdown) |
| `isSendDone()` / `isReceiveDone()` | Polled by UI render loop |
| `restoreSucceeded()` / `restoreError()` | Restore outcome after receive |

**Threading model:**

```
UI thread (Plutonium event loop)
  └─ startSend()
       └─ senderEntry [pthread, detached]
            ├─ findServer()        — UDP multicast, 100 ms poll slices
            ├─ io::backup()        — creates local save backup
            └─ TCP send loop

  └─ startReceive()
       ├─ broadcastEntry [pthread, detached]  — UDP multicast listener
       └─ acceptEntry   [pthread, detached]
            ├─ TCP receive loop
            └─ io::restore()      — mounts save, clears, copies, commits
```

Cancellation: `cancelSend()` / `cancelReceive()` call `shutdown(SHUT_RDWR)` on all open sockets. Blocking `read`/`recvfrom`/`accept` return errors immediately. Atomic flags are checked at loop boundaries.

### `nxst::Result<T, E>` (`include/nxst/domain/result.hpp`)

85-line tagged-union result type. No exceptions, no `std::variant`. Used for `io::backup` and `io::restore` return values.

```cpp
auto result = io::backup(title_index, uid);
if (!result.isOk()) {
    failSend("Backup failed: " + result.error());
    return;
}
fs::path dir = result.value();
```

`Result<void, E>` specialisation available for operations that succeed without a value.

### `nxst::FsFileSystemHandle` / `nxst::FileHandle` (`include/nxst/infra/fs/handles.hpp`)

RAII wrappers ensuring `fsFsClose` / `fclose` are called on all exit paths.

---

## Threading Invariants

- All `std::atomic` members in `TransferService` use sequential-consistency (default). No explicit `memory_order` needed at this concurrency level.
- `TransferState::status` is a `std::string` protected by `std::mutex status_mutex`. All other `TransferState` fields are atomics.
- `pthread_create` + `pthread_detach` is used throughout (libnx's supported path). Threads are never joined — they signal completion via `state.done = true` and set their active flag to false.
- Cancel is safe to call from any thread.

---

## File Map

```
include/nxst/
├── app/
│   ├── main.hpp              — global state (g_currentTime, g_sortMode, …)
│   └── main_application.hpp  — MainApplication : pu::ui::Application
├── domain/
│   ├── account.hpp           — AccountUid, Account::ids(), Account::username()
│   ├── common.hpp            — StringUtils (UTF-8/16, elide, accents)
│   ├── protocol.hpp          — wire constants (ports, sentinel, buffer size)
│   ├── result.hpp            — Result<T, E> tagged union
│   ├── title.hpp             — Title, getTitle(), getTitleCount()
│   ├── transfer_state.hpp    — TransferState (atomics + mutex-guarded status)
│   └── util.hpp              — StringUtils helpers, blinkLed
├── infra/
│   ├── fs/
│   │   ├── directory.hpp     — Directory iterator (libnx FsDir)
│   │   ├── filesystem.hpp    — FileSystem::mount/unmount wrappers
│   │   ├── handles.hpp       — FsFileSystemHandle, FileHandle (RAII)
│   │   └── io.hpp            — io::backup, io::restore, io::copyFile, …
│   ├── net/
│   │   └── socket.hpp        — Socket RAII wrapper (int fd)
│   └── sys/
│       └── logger.hpp        — nxst::log::info/warn/error (printf-checked)
├── service/
│   └── transfer_service.hpp  — TransferService
└── ui/
    ├── card.hpp              — Card UI component
    ├── const.h               — layout/color/font constants
    ├── header_bar.hpp        — HeaderBar (title + user avatar row)
    ├── hint_bar.hpp          — HintBar (button legend)
    ├── theme.hpp             — color, radius, spacing, type tokens
    ├── titles_layout.hpp     — TitlesLayout
    ├── transfer_overlay.hpp  — TransferOverlay (progress modal)
    ├── ui_context.hpp        — UiContext (selected user state)
    └── users_layout.hpp      — UsersLayout
```

---

## Build

```bash
# Configure (once — toolchain preset reads $DEVKITPRO automatically)
cmake --preset switch

# Build
cmake --build build

# Send to Switch via nxlink
cmake --build build --target send
```

Output: `build/NXST.nro`

See `README.md` for full build prerequisites.