docs: initial product docs and design reference
Establishes the documentation foundation for the netOrk website: - CLAUDE.md — tech stack (React 18/Vite/Tailwind), design rules, tone of voice, and file structure guidance for the implementation instance - docs/PRODUCT.md — one-liner, elevator pitch, target audience, value props, full feature list, driver table, architecture summary - docs/DESIGN.md — exact Tailwind classes for colors, typography, spacing, and all reusable component patterns (cards, buttons, screenshot frames, badges, nav) lifted directly from the product UI - docs/PAGES.md — page-by-page content plan with route, purpose, section structure, and draft copy for every page No code yet — that follows in a separate instance. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Christian Manivong
+339
@@ -0,0 +1,339 @@
|
||||
# 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 |
|
||||
| `/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
|
||||
|
||||
---
|
||||
|
||||
### 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. Supported Drivers (full table)
|
||||
4. Networking & Inventory
|
||||
5. Configuration Management & Drift
|
||||
6. Scheduled Operations
|
||||
7. Monitoring & Health
|
||||
8. Security Integrations
|
||||
9. DNS Management
|
||||
10. Access Control (RBAC)
|
||||
11. NetBox Sync
|
||||
12. 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
|
||||
|
||||
---
|
||||
|
||||
## `/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`
|
||||
Reference in New Issue
Block a user