# Guardian Agent Memory & Engineering Reference (AGENTS.md)

This document provides a comprehensive operational memory, architectural record, and changelog of all work performed on **Guardian**. Future AI agents and engineers working on this repository should consult this file before making modifications.

---

## 1. Project Overview & Architecture

**Guardian** is an ultra-lightweight, self-hosted server & Docker dashboard + app launcher designed to run with minimal CPU and memory overhead on home servers, homelabs, VPSs, Raspberry Pis, and enterprise Linux hosts.

### Core Stack
- **Backend (`server/`)**: Node.js (v20+ / v22), TypeScript (`NodeNext`), Express, CORS.
  - Custom zero-overhead collectors for system telemetry (CPU, Memory, Disk, Network, Processes).
  - Docker daemon integration via standard `/var/run/docker.sock` Unix socket using direct Docker REST API calls (no heavy CLI wrappers).
  - Config persistence in JSON (`data/apps.json`, `data/settings.json`).
- **Frontend (`client/`)**: React 18, TypeScript, Vite, Tailwind CSS, Lucide icons, glassmorphic dark UI design system.
- **Packaging (`Dockerfile`, `docker-compose.yml`)**: Multi-stage Alpine container (`node:22-alpine`) supporting multi-architecture targets (`linux/amd64`, `linux/arm64/v8`). Published to GitHub Container Registry (GHCR):
  ```
  ghcr.io/vineetkishore01/guardian:latest
  ```

---

## 2. Key System Components & Collectors

### A. Host Telemetry (`server/src/collectors/`)
- **Host Metrics Fallback**: When running inside a Docker container, host metrics are extracted from mounted `/host/proc`, `/host/sys`, and `/host/etc/os-release` paths configured via environment variables:
  - `HOST_PROC=/host/proc`
  - `HOST_SYS=/host/sys`
  - `HOST_ETC=/host/etc`
- **Linux Distribution Genericity**: Designed and verified to work seamlessly across:
  - Debian, Ubuntu, Proxmox VE
  - TrueNAS SCALE, Unraid
  - Arch Linux, Alpine Linux
  - Raspberry Pi OS & ARM64 SBCs
- **Mount Propagation**: Uses `:ro,rslave` on host mounts (`/`, `/proc`, `/sys`) in `docker-compose.yml.example` to ensure dynamic host mount changes (such as plugging in external storage or new mountpoints) propagate into the container without throwing permission or stale handle errors.

### B. Docker Collector (`server/src/collectors/docker.ts`)
- Communicates directly with `/var/run/docker.sock`.
- Auto-detects running containers, health status, exposed ports, IP bindings, and resource usage.
- Enables 1-click web launcher mapping: automatically derives external URLs from port bindings or Docker labels (e.g. `guardian.url`, `traefik.http.routers.*`).

### C. Process Monitor (`server/src/collectors/processes.ts`)
- Reads `/proc` directly on Linux hosts or `/host/proc` when containerized.
- Extracts PID, process name, state, CPU utilization %, and RSS memory usage with zero dependencies.
- Gracefully handles non-Linux host platforms (e.g. Darwin/macOS local dev) by falling back to standard Node child process calls.

### D. Endpoint Health Checker (`server/src/collectors/endpoints.ts`)
- Configurable URL pinging for external / LAN services with latency tracking and status badge indication.

### E. Physical Disks & S.M.A.R.T. Health (`server/src/collectors/smart.ts`)
- Queries hardware drives using `smartctl` (`smartmontools` installed in runner image) with fallback to `/sys/block` and hwmon.
- Discovers physical block devices (`sd*`, `nvme*n*`, `vd*`), models, vendors, serial numbers, firmware, and form factors.
- Monitors overall SMART health (`passed`, `warning`, `failing`), temperatures, power-on hours, power cycles, and rotational speed (or SSD indication).
- Extracts critical homelab drive failure signals: reallocated sectors (ID 5), pending sectors (ID 197), uncorrectable sectors (ID 198), UDMA CRC cable errors (ID 199), and NVMe media errors/critical warnings.
- Tracks SSD/NVMe wearout % and endurance (TBW/TBR).
- Maps physical drive partitions directly to filesystem mountpoints.
- Caches measurements with a 60-second TTL to avoid spinning up sleeping disks, with a manual refresh trigger (`POST /api/disks/smart/refresh`).
- Falls back to realistic sample disks when off-host.

### F. Server Uptime & Availability (`server/src/collectors/host.ts`, `UptimeCard.tsx`)
- Measures continuous operation down to the second with a live ticking counter.
- Extracts boot time from `/proc/stat` (`btime`) or `/proc/uptime`.
- Analyzes lifetime CPU efficiency by computing idle vs active time since boot from `/proc/uptime`.
- Evaluates system stability status (`fresh_boot`, `stable`, `long_running` for 30d+ streaks) and load profile vs thread capacity.

---

## 3. Repository Branch Structure & Protection

### `main` Branch
- Contains only the application source code, configs, and container definitions:
  - `server/`: Backend TypeScript code.
  - `client/`: Frontend React application.
  - `Dockerfile`: Multi-stage build for application images.
  - `docker-compose.yml`: Local production testing.
  - `docker-compose.yml.example`: User-facing deployment template.
  - `README.md`: Project documentation.
- **Website Code Protection**:
  - The showcase landing page code is **explicitly excluded** from `main` so that anyone cloning the public repo receives a clean, focused application codebase.
  - `.gitignore` includes:
    ```gitignore
    # Website code lives on gh-pages branch only
    docs/*.html
    docs/*.css
    docs/*.js
    ```

### `gh-pages` Branch
- An isolated branch dedicated strictly to the public showcase landing page served at:
  - **Live URL**: `https://vineetkishore01.github.io/Guardian/`
- Contains:
  - `index.html`: Hero section, feature breakdown, live interactive installer, telemetry simulator, and screenshot gallery.
  - `styles.css`: Custom vanilla CSS with glassmorphic cards, radiant purple/cyan gradients, and responsive layouts.
  - `app.js`: Tab switching logic, copy-to-clipboard for the 1-line install command, animated telemetry preview, and Cloudflare visit tracking beacon.
  - 5 Retina high-resolution screenshots highlighting the real application UI.

---

## 4. Personal Visitor Analytics & Telemetry (Cloudflare Worker + KV)

To monitor traffic and virality on the public showcase website without heavy third-party trackers (like Google Analytics), a custom serverless Cloudflare Worker with KV storage was built and deployed.

### Worker Details
- **Worker Name**: `guardian-counterstill-sun-e8de`
- **Public URL**: `https://guardian-counterstill-sun-e8de.vineetkishore01.workers.dev`
- **KV Namespace**: `guardian_stats` (`dfe569263e6142f4a944fb48c339ba30`)
- **Cloudflare Account**: Configured and deployed using user's logged-in session via `ego-browser`.

### API Endpoints & Bot Protection
1. **Hit Beacon (`GET /hit?vid=...`)**:
   - **Client-Side Shielding (`app.js` on `gh-pages`)**:
     - Automation & WebDriver check (`navigator.webdriver`, `__nightmare`, `_phantom`, `__selenium_unwrapped`).
     - Headless screen / language anomaly filters.
     - User-Agent crawler regex filter (Googlebot, Bingbot, Baiduspider, Ahrefs, Semrush, ByteSpider, Censys, Shodan, WhatsApp, Telegram, Applebot, Discord, etc.).
     - Session deduplication (`sessionStorage.getItem('guardian_visited_session')`) to eliminate page refresh inflation.
     - Persistent anonymous device UUID (`localStorage.getItem('guardian_visitor_id')`) ensuring 1 device = 1 unique visitor across network changes (Wi-Fi, 5G, iCloud Private Relay).
     - Human interaction / active dwell verification (requires scroll, click, mousemove, keypress, or 3.5s of visible reading before firing).
   - **Server Edge Processing**:
     - Computes unique visitor status using client UUID (`vid_<vid>`) or IP fallback.
     - Enforces `totalVisits = Math.max(totalVisits, todayVisits)` to eliminate distributed KV counter drift.
2. **Executive Dashboard (`GET /`)**:
   - Access directly in a browser: `https://guardian-counterstill-sun-e8de.vineetkishore01.workers.dev/`
   - Returns a real-time dark-mode HTML dashboard displaying:
     - Total Pageviews
     - Unique Visitors
     - Today's Visits
     - Active Bot Shields badge
     - One-click stats reset trigger (`/reset?key=<see Cloudflare Worker env, not committed>`)

---

## 5. Local Development & Build Commands

### Initial Setup
```bash
# Root dependencies (concurrently dev runner)
npm install

# Server dependencies (Express, TypeScript, @types/node)
cd server && npm install

# Client dependencies (React, Vite, Tailwind CSS)
cd client && npm install
```

### Type Checking & Linting
Always ensure both workspaces compile with zero errors:
```bash
# Verify backend TypeScript compilation
./server/node_modules/.bin/tsc --project server/tsconfig.json --noEmit

# Verify frontend TypeScript compilation
./client/node_modules/.bin/tsc --project client/tsconfig.json --noEmit
```

### Running Locally
```bash
# Start both client and server concurrently
npm run dev

# Or start individually:
npm run dev:server   # Starts server with tsx watch on :3001
npm run dev:client   # Starts Vite dev server on :5173
```

### Building for Production
```bash
# Builds client into client/dist and server into server/dist
npm run build
```

---

## 6. Docker Deployment & Quick Install

### One-Line Install Command (Featured on Website)
```bash
curl -fsSL https://raw.githubusercontent.com/vineetkishore01/Guardian/main/docker-compose.yml.example -o docker-compose.yml && docker compose up -d
```

### Reference `docker-compose.yml.example`
```yaml
services:
  guardian:
    image: ghcr.io/vineetkishore01/guardian:latest
    container_name: guardian
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - NODE_ENV=production
      - HOST_PROC=/host/proc
      - HOST_SYS=/host/sys
      - HOST_ETC=/host/etc
    volumes:
      # Docker socket for container control and metrics
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # Host telemetry filesystem mounts with rslave propagation
      - /proc:/host/proc:ro,rslave
      - /sys:/host/sys:ro,rslave
      - /etc/os-release:/host/etc/os-release:ro
      # Persistent storage for custom pinned apps and user settings
      - guardian_data:/app/data

volumes:
  guardian_data:
    driver: local
```

---

## 7. Operational Guidelines for Future Agents

1. **Keep Website Code Out of `main`**:
   Never commit HTML/CSS/JS files intended for the showcase site to `main`. If making updates to the showcase website, checkout or work on `gh-pages` branch, commit, push to `origin gh-pages`, and switch back to `main`.
2. **Never Break Linux Distro Genericity**:
   When updating collectors in `server/src/collectors/`, always respect the `HOST_PROC`, `HOST_SYS`, and `HOST_ETC` environment variables and check for file existence before reading paths. Avoid distro-specific assumptions.
3. **Preserve Type Declarations**:
   Ensure `server/package.json` contains `@types/node` and that `./server/node_modules/.bin/tsc --noEmit` exits with 0 before completing any backend modifications.
4. **Cloudflare Worker Updates**:
   The worker script source is maintained in the Cloudflare Dashboard under `guardian-counterstill-sun-e8de`. If modifications are needed, test changes using `ego-browser` or the Cloudflare API.
5. **Host-Network and Namespace-Guest Port Discovery**:
   Docker daemon's `/containers/json` returns `Ports: []` for any container using `network_mode: host` or `network_mode: container:<parent>`.
   `fetchContainerDetail` extracts `raw.Config?.ExposedPorts`.
   - For `network_mode: host`: `publicPort` is mapped directly to `privatePort` (`0.0.0.0`) since the container listens directly on host interfaces.
   - For `network_mode: container:<parent>`: Guest exposed ports are matched against parent published ports.
   - `buildProbeTargets` filters out non-HTTP ports (e.g. DNS 53, RTSP 8554, MQTT 1883, HAP 51826) and prioritizes explicit `customUrl` to avoid false down alerts.
   - `resolveContainerUrl` in the frontend client uses intelligent fallback to well-known service ports so all containers get functional launch URLs.