website/docs/PAGES.md

# netOrk Website — Page Structure & Content Plan

This document defines every page of the website: its purpose, section
structure, and draft copy. Use this as the brief for implementation.

---

## Page Overview

| Route | Page | Priority |
|---|---|---|
| `/` | Landing (Home) | P0 — build first |
| `/features` | Full feature list | P1 |
| `/drivers` | Supported devices | P1 |
| `/docs/getting-started` | Installation guide | P1 |
| `/roadmap` | Roadmap — planned + under consideration | P1 |
| `/nis2` | NIS2 landing page — Art. 21 mapping, evidence, roadmap | P1 |
| `/docs/architecture` | Technical overview | P2 |
| `/plugins` | Plugin system | P2 |

---

## `/` — Landing Page

### Section 1 — Hero

**Purpose:** Answer "what is this?" in 5 seconds.

**Layout:** Full-width, centered. Heading + subheading + two CTAs + hero
screenshot below.

**Heading:**
```
Network orchestration
for heterogeneous infrastructure.
```
(`text-slate-100` for first line, second line in `text-sky-400` or keep
both `text-slate-100` — designer decides.)

**Subheading:**
```
netOrk discovers, monitors, and manages your routers, switches, access
points, firewalls, and servers from a single UI — regardless of vendor.
No SaaS dependency. Runs on your infrastructure.
```

**CTAs:**
- Primary: `Get started →` → `/docs/getting-started`
- Secondary: `View features` → `/features`

**Hero visual:** Full-width screenshot of the device inventory page
(dark UI visible, framed with the browser chrome component from DESIGN.md).

---

### Section 2 — Problem Statement

**Purpose:** Make the pain relatable.

**Layout:** Single centered paragraph or short 3-column stat row.

**Copy:**
```
Managing a mixed network means juggling a different admin UI for every
vendor — one for OPNsense, one for HP ProCurve, one for OpenWRT, one for
Proxmox. Config changes happen directly on devices with no audit trail.
You find out something drifted when it breaks.
```

---

### Section 3 — Core Capabilities (3-up)

**Purpose:** Communicate the three main things netOrk does.

**Layout:** 3 columns, each with icon + heading + 2–3 sentences.

**Card 1 — Discover & Inventory**
- Icon: `MagnifyingGlassIcon`
- Heading: `Discover everything on your network`
- Copy: `ICMP sweep, SNMP scan, and HTTP probing find devices before you
  add them. Fingerprinting identifies vendor and platform automatically.
  Adopt results into your inventory with a single click.`

**Card 2 — Monitor & Alert**
- Icon: `ChartBarIcon` or `SignalIcon`
- Heading: `Poll device state continuously`
- Copy: `Every device is polled on a configurable interval via NAPALM.
  Interface status, ARP tables, DHCP leases, VLAN membership, Docker
  containers, and SNMP health metrics — all in one place.`

**Card 3 — Configure & Enforce**
- Icon: `WrenchScrewdriverIcon`
- Heading: `Detect drift. Fix it.`
- Copy: `Define desired state in netOrk. On every poll, device config is
  compared against it. Drifted devices get a warning; a one-click fix
  stream applies the correction and shows you live SSH output.`

---

### Section 4 — Driver Grid

**Purpose:** Show breadth of vendor support.

**Layout:** Centered heading + wrapping badge grid.

**Heading:** `Works with your hardware`

**Subheading:**
```
netOrk ships with custom NAPALM drivers for 11 device types, plus all
built-in NAPALM drivers. New drivers follow a documented registration
pattern.
```

**Badge list** (see `docs/PRODUCT.md` — driver table):
OpenWRT, OPNsense, Proxmox VE, Linux, HP ProCurve / Aruba, TP-Link Jetstream,
Netgear, Fritz!Box, Zyxel, OpenMediaVault, Sonos,
Cisco IOS, Arista EOS, Juniper JunOS

Each badge uses the `Driver / Integration Badge` component from DESIGN.md.

---

### Section 5 — Screenshot Walkthrough (alternating)

**Purpose:** Show the UI concretely. Three alternating image + text rows.

**Row 1 — Left text, right screenshot**
- Heading: `Device detail at a glance`
- Copy: `Hostname, IP, vendor, OS version, last poll time, and active
  warnings on one card. Tabbed detail view for interfaces, LLDP neighbors,
  ARP table, VLAN membership, packages, services, and scheduled jobs.`
- Screenshot: DeviceDetailPage

**Row 2 — Right text, left screenshot**
- Heading: `Intent-based VLAN and SSID management`
- Copy: `Define VLAN names and SSID settings once. netOrk compares them
  against every polled device and pushes corrections automatically via
  UCI (OpenWRT) or the device's native API.`
- Screenshot: VlansPage or WirelessPage

**Row 3 — Left text, right screenshot**
- Heading: `Security visibility per device`
- Copy: `Wazuh agent status, CVE counts by severity, and recent alerts
  — all linked to the device record. One-click agent install if the
  agent is missing. Graylog syslog forwarding status with auto-fix.`
- Screenshot: SecurityTab inside DeviceDetailPage

**Row 4 — Right text, left screenshot**
- Heading: `Configuration backup and versioning`
- Copy: `Every poll captures a config snapshot into a local Git
  repository. The Config tab shows the full snapshot history, a
  side-by-side diff between any two points in time, and — for
  OPNsense — a Restore button. Unauthorized changes show up as a
  device warning.`
- Screenshot: ConfigTab inside DeviceDetailPage

**Row 5 — Left text, right screenshot**
- Heading: `Dashboards you actually build`
- Copy: `Pick from 13 widgets and arrange them on a WYSIWYG grid — no
  more fixed layout. Share a dashboard with a colleague, let them
  subscribe to your live version or clone it into their own, and pin
  favorites to the main menu.`
- Screenshot: DashboardDetailPage (edit mode)

---

### Section 5b — NIS2

**Purpose:** Hook for organizations evaluating netOrk in a NIS2 context.

**Layout:** Left column — label + Art. 21 mapping list. Right column — mock compliance overview UI.

**Label (eyebrow):** `NIS2 · Art. 21` (sky-500, uppercase, tracking-widest)

**Heading:** `Evidence, not paperwork.`

**Copy:**
```
NIS2 Art. 21 mandates asset inventory, patch management, access control,
and audit trails as baseline technical measures. netOrk doesn't bolt on a
compliance layer — these are its day-to-day outputs.
```

**Art. 21 mapping (4 rows, icon = monospace article ref in sky-500):**
- Art. 21 (2e) → Patch & vulnerability management — Per-device update status, Wazuh CVE counts by severity
- Art. 21 (2h) → Asset management & access control — Full device inventory, RBAC with four roles, complete audit log
- Art. 21 (2a) → Risk analysis baseline — Config drift detection, SNMP health metrics, security agent coverage
- Art. 21 (2b) → Incident detection — Wazuh alert history, CrowdSec decisions, Graylog syslog per device

**Mock UI (right column):** `MockCompliance` — per-site checklist with ✓/⚠ rows, each showing label + detail stat. Label: `netork.local / compliance / HQ`.

---

### Section 6 — Plugin System (brief)

**Purpose:** Signal extensibility without going deep.

**Layout:** Dark card, left-aligned.

**Heading:** `Built to extend`

**Copy:**
```
Integrations (Wazuh, Graylog, CrowdSec, apt-cacher-ng) are plugins
that register into the plugin system — they can be enabled or disabled
per deployment without code changes. Adding a new integration follows
a documented pattern with a hook bus, typed metadata, and a plugin
registry.
```

**CTA:** `Plugin system docs →` → `/plugins`

---

### Section 7 — Deployment (quick)

**Purpose:** Answer "how do I run this?" without going into detail.

**Layout:** Code block + short description.

**Heading:** `Self-hosted. One command.`

**Copy:**
```
netOrk runs in Docker Compose. Five containers: API, two worker pools,
a Beat scheduler, and an nginx UI server. No external dependencies beyond
Redis and PostgreSQL.
```

**Code block:**
```bash
# Clone + configure
git clone https://gitea.example.com/netork/netork.git
cp .env.example .env
# edit .env (DB URL, Redis password, secret key)

# Deploy
bash scripts/deploy.sh 192.168.1.10
```

---

### Section 8 — CTA Footer

**Layout:** Centered, full-width dark section.

**Heading:** `Start managing your network.`

**CTA:** `Read the docs →` → `/docs/getting-started`

---

## `/features` — Full Feature List

**Purpose:** Comprehensive reference for people who want to evaluate in depth.

**Layout:** Vertical list of expandable sections (or just long-scroll with
sticky section nav). One section per capability area.

**Sections** (map directly to feature list in `docs/PRODUCT.md`):
1. Device Management
2. Discovery
3. VM Provisioning
4. Supported Drivers (full table)
5. Networking & Inventory
6. Configuration Management & Drift
7. Configuration Automation (Ansible)
8. Scheduled Operations
9. Satellite Deployments
10. Monitoring & Health
11. Dashboards
12. Security Integrations
13. DNS Management
14. Access Control (RBAC)
15. NetBox Sync
16. Compliance & Audit (NIS2)
17. Developer Experience

Each section: `text-xl font-semibold text-slate-200` heading +
feature items as a clean list with `text-slate-400` body.

---

## `/drivers` — Supported Devices

**Purpose:** One-page reference for "does netOrk support my device?"

**Layout:** Full table + short description per driver.

**Table columns:** Driver name | Device type | Capabilities | Status

**Capabilities** — checkmarks or tags for:
- `get_facts` `get_interfaces` `get_lldp` `get_vlans` `get_ssids`
  `get_health_metrics` `get_docker` `scheduled_reboot` `config_push`

**Status:** `stable` / `beta` / `community` as a badge.

---

## `/docs/getting-started` — Installation

**Purpose:** Get someone from zero to a running instance.

**Sections:**

1. **Prerequisites**
   - Docker + Docker Compose
   - A PostgreSQL instance (or use the bundled profile)
   - Redis
   - A Linux host reachable by SSH from the server

2. **Quick start**
   ```bash
   git clone ...
   cp .env.example .env
   # Edit .env
   bash scripts/deploy.sh <server-ip>
   ```

3. **First run**
   - Navigate to `http://<server-ip>`
   - Complete the setup wizard (creates admin user)
   - Add your first device

4. **Adding a device**
   - Fill in hostname/IP, driver, and credentials
   - Click Poll to verify connectivity
   - Set a poll interval for continuous monitoring

5. **Next steps**
   - Configure NetBox sync
   - Set up Wazuh integration
   - Enable scheduled reboots for OpenWRT APs

---

## `/roadmap` — Roadmap

**Purpose:** Show what's being built and what's under consideration. Signal NIS2 investment clearly.

**Layout:** Page header + two vertical groups ("Planned" / "Under consideration"), each a list of items.

**NIS2 badge:** `NIS2` monospace tag (sky-500/10 bg, sky-400 text, sky-500/20 border) inline next to item title.

**Intro copy:**
```
What's being built and what's being evaluated. Items tagged NIS2 directly 
address NIS2 Art. 21 technical baseline requirements.
```

**Planned items (NIS2-tagged):**
- CVE tracking per device — NVD / OSV cross-reference
- Compliance dashboard — per-site Art. 21 checklist view

**Planned items (general):**
- Webhook engine — outbound events with HMAC signing
- Live job log streaming — WebSocket for all long-running tasks
- NetBox sync — manual trigger + status view

**Under consideration (NIS2-tagged):**
- Incident workflow — structured record + NIS2 Art. 23 Fristen-Tracker

**Under consideration (general):**
- mDNS scanner — media device discovery
- Prometheus + Grafana — metrics and dashboards
- Kubernetes Helm chart

---

## `/docs/architecture` — Technical Overview

**Purpose:** Give engineers the mental model before they look at code.

**Content:** Essentially the one-paragraph summary from `docs/PRODUCT.md`
expanded into a readable overview with the architecture diagram (ASCII or SVG).

**Sections:**
1. Overview (request → FastAPI → DB / Celery worker)
2. Driver system (NAPALM + custom drivers + registry)
3. Task queues (which queue does what)
4. Plugin system (register → hook bus → router mount)
5. Data model (UUID PKs, JSONB snapshots, intent-vs-state)

---

## `/plugins` — Plugin System

**Purpose:** Explain extensibility to potential contributors.

**Sections:**
1. What is a plugin? (metadata, router, tasks, hooks)
2. Built-in plugins (Wazuh, Graylog, CrowdSec, apt-cacher)
3. Writing a plugin (step-by-step with code snippets)
4. Hook bus (fire / call / transform)
5. Plugin registry and enable/disable

---

## Global Layout

### Navigation (all pages)

```
[ netOrk ]    Features    Drivers    Docs ▾    Plugins        [ Get started ]
```

`Docs` is a dropdown: Getting Started / Architecture

### Footer

```
netOrk — self-hosted network orchestration

Links:          Resources:        Legal:
Features        Getting Started   MIT License
Drivers         Architecture      Privacy (none collected)
Plugins         Changelog
```

Footer background: `bg-slate-900 border-t border-slate-800`
Footer text: `text-sm text-slate-500`