# System

## Purpose

The system module exposes metrics, Docker info/stats, server info, updates, backups, power controls, disk management, thermal warnings, weather widgets, and status bar data.

## Locations

- Server-side: `lib/server/modules/system/`, plus Docker/network modules for some data
- Client-side: `modules/system/`, settings sections under `modules/settings/`
- Routes: `app/api/v1/system/`, `app/api/v1/docker/`, `app/api/v1/logs`

## Key Files

| File | Role |
|---|---|
| `lib/server/modules/system/service.ts` | Metrics snapshot collection |
| `lib/server/modules/system/info-service.ts` | Server info |
| `lib/server/modules/system/update-service.ts` | Update status/apply |
| `lib/server/modules/system/backup-service.ts` | Backup settings/list/run |
| `lib/server/modules/system/power-service.ts` | Shutdown/reboot/factory reset |
| `lib/server/modules/system/disk-service.ts` | Disk and partition operations |
| `modules/system/hooks/useSystemSse.ts` | Metrics SSE client |
| `modules/system/components/monitor.tsx` | System monitor UI |
| `modules/system/components/disk-manager.tsx` | Disk manager UI |
| `modules/settings/components/panel/sections/server-info-section.tsx` | Server info settings view |

## Public API

- `getSystemMetricsSnapshot()`
- `getSystemUpdateStatus()`, `scheduleSystemUpdate()`
- `getSystemBackupsSnapshot()`, `runSystemBackupNow()`
- `scheduleSystemReboot()`, `scheduleSystemShutdown()`, `scheduleFactoryReset()`
- `getServerInfo()`
- `listDisks()`, `formatPartition()`, `mountPartition()`, `unmountPartition()`, `createPartition()`, `deletePartition()`, `wipeDisk()`
- Client hooks: `useSystemMetrics()`, `useSystemSse()`, `useDockerInfo()`, `useDockerStats()`, `useDisks()`, `useServerInfo()`

## Contracts

- `lib/shared/contracts/system.ts`
- `lib/shared/contracts/disks.ts`
- `lib/shared/contracts/server-info.ts`
- `lib/shared/contracts/weather.ts`

## Database Tables

- `settings` for appearance/system settings stored as JSON
- Backup metadata is file-backed through the backup service, not a dedicated table in `schema.ts`.

## API Routes Owned

- `GET /api/v1/system/metrics`
- `GET /api/v1/system/stream`
- `GET /api/v1/system/info`
- `GET/PUT /api/v1/system/preferences`
- `GET/PUT /api/v1/system/security`
- `GET /api/v1/system/updates`
- `POST /api/v1/system/updates/check`
- `POST /api/v1/system/updates/apply`
- `GET/POST/PUT /api/v1/system/backups*`
- `GET/POST /api/v1/system/power/*`
- `GET/POST /api/v1/system/disks*`
- `GET /api/v1/logs`

## Known Issues

- `app/api/v1/system/stream/route.ts` authenticates before opening the SSE stream.
- Some metrics cache TTL constants are hardcoded in `lib/server/modules/system/service.ts`.
- Server info reads Linux host files and command output where available; fields can be null on unsupported hosts or containers.
- `modules/system/components/disk-manager.tsx` is over 500 lines.
- Power and disk routes are high-risk because they perform destructive host actions.

## How To Extend

To add a system setting:

1. Add contract fields in `lib/shared/contracts/system.ts`.
2. Add persistence/default logic in `lib/server/modules/system/preferences-service.ts` or the relevant service.
3. Add or update a route under `app/api/v1/system/`.
4. Add request helpers in `modules/settings/hooks/backend/api.ts`.
5. Add controller state in `modules/settings/components/panel/controllers.ts`.
6. Add UI in the relevant settings section.
7. Add tests for service, route, and save-policy helpers.