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
@@ -0,0 +1 @@
|
|||||||
|
node_modules/\ndist/\n.env\n.env.local\n*.local\n.DS_Store
|
||||||
@@ -0,0 +1,93 @@
|
|||||||
|
# CLAUDE.md — netork-website
|
||||||
|
|
||||||
|
This is the official marketing website for **netOrk**, a self-hosted Network
|
||||||
|
Orchestration Platform. The goal is a fast, visually striking single-page (or
|
||||||
|
multi-page) site that communicates what netOrk does, who it is for, and how to
|
||||||
|
get started.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Purpose
|
||||||
|
|
||||||
|
Potential users land here and need to answer three questions in under 10 seconds:
|
||||||
|
1. What is this?
|
||||||
|
2. Is it for me?
|
||||||
|
3. How do I try it?
|
||||||
|
|
||||||
|
Everything on the site should serve those three questions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Content & Design Source of Truth
|
||||||
|
|
||||||
|
All product content (features, copy, page structure) is in `docs/`:
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `docs/PRODUCT.md` | Product description, target audience, value propositions, feature list |
|
||||||
|
| `docs/DESIGN.md` | Visual identity — exact Tailwind colors, typography, component patterns |
|
||||||
|
| `docs/PAGES.md` | Page-by-page content plan with section headings and copy drafts |
|
||||||
|
|
||||||
|
**Read these files before writing any code or copy.** They are the source of
|
||||||
|
truth. The design file in particular defines exact class names — use them.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
Mirror the netOrk UI exactly so the design language carries over:
|
||||||
|
|
||||||
|
| Layer | Choice |
|
||||||
|
|---|---|
|
||||||
|
| Framework | React 18 + TypeScript |
|
||||||
|
| Build | Vite |
|
||||||
|
| Styling | Tailwind CSS v3 |
|
||||||
|
| Routing | React Router v6 (or static if single page) |
|
||||||
|
| Icons | Heroicons (inline SVG, same as netOrk UI) |
|
||||||
|
| Animation | Tailwind transitions only — no GSAP, Framer, etc. |
|
||||||
|
|
||||||
|
**No external component libraries.** Build everything from Tailwind primitives,
|
||||||
|
exactly as netOrk's `ui/src/components/ui.tsx` does.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Design Rules (summary — full detail in docs/DESIGN.md)
|
||||||
|
|
||||||
|
- **Dark theme only.** Background `bg-slate-950`. Cards `bg-slate-900`.
|
||||||
|
- **Accent color:** `sky-500` / `sky-600` for CTAs, links, highlights.
|
||||||
|
- **No light mode toggle.** Ever.
|
||||||
|
- Font stack: system default (Tailwind sans). No Google Fonts.
|
||||||
|
- All interactive elements use `transition-colors` — no layout shifts.
|
||||||
|
- Screenshots/mockups of the actual app use a `border border-slate-700 rounded-xl
|
||||||
|
overflow-hidden` wrapper to frame them against the dark background.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Naming
|
||||||
|
|
||||||
|
```
|
||||||
|
netork-website/
|
||||||
|
├── CLAUDE.md ← this file
|
||||||
|
├── docs/
|
||||||
|
│ ├── PRODUCT.md
|
||||||
|
│ ├── DESIGN.md
|
||||||
|
│ └── PAGES.md
|
||||||
|
├── public/
|
||||||
|
│ └── screenshots/ ← actual app screenshots go here
|
||||||
|
├── src/
|
||||||
|
│ ├── components/
|
||||||
|
│ ├── pages/
|
||||||
|
│ └── main.tsx
|
||||||
|
├── index.html
|
||||||
|
├── package.json
|
||||||
|
└── tailwind.config.js
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tone of Voice
|
||||||
|
|
||||||
|
- Direct and technical — audience is engineers, not executives.
|
||||||
|
- No marketing fluff ("revolutionize", "empower", "seamless").
|
||||||
|
- Show, don't tell — a screenshot or code block beats three sentences of prose.
|
||||||
|
- German is fine for internal docs; the website copy is in **English**.
|
||||||
+261
@@ -0,0 +1,261 @@
|
|||||||
|
# netOrk — Visual Identity & Design System
|
||||||
|
|
||||||
|
This document defines the visual identity of netOrk and must be followed
|
||||||
|
exactly when building the website. The goal is zero visual discontinuity
|
||||||
|
between the product UI and the marketing site.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Principle
|
||||||
|
|
||||||
|
**The website looks like a dark-mode dev tool, not a SaaS landing page.**
|
||||||
|
No gradients, no floating orbs, no animated hero blobs. The aesthetic is
|
||||||
|
deliberate, minimal, and technical — consistent with the product itself.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Color Palette
|
||||||
|
|
||||||
|
All colors are Tailwind CSS v3 classes. Do not use hex values directly —
|
||||||
|
always use Tailwind class names to stay consistent.
|
||||||
|
|
||||||
|
### Backgrounds
|
||||||
|
|
||||||
|
| Layer | Class | Usage |
|
||||||
|
|---|---|---|
|
||||||
|
| Page / outermost | `bg-slate-950` | Body, full-bleed sections |
|
||||||
|
| Card / panel | `bg-slate-900` | Content cards, code blocks, feature boxes |
|
||||||
|
| Elevated element | `bg-slate-800` | Hover states, dropdowns, table rows on hover |
|
||||||
|
| Border | `border-slate-700` | Between sections, card outlines |
|
||||||
|
| Subtle border | `border-slate-800` | Inside cards, dividers |
|
||||||
|
|
||||||
|
### Text
|
||||||
|
|
||||||
|
| Role | Class |
|
||||||
|
|---|---|
|
||||||
|
| Primary | `text-slate-100` |
|
||||||
|
| Secondary / muted | `text-slate-400` |
|
||||||
|
| Tertiary / placeholder | `text-slate-500` |
|
||||||
|
| Accent (interactive) | `text-sky-400` |
|
||||||
|
| Danger | `text-red-400` |
|
||||||
|
|
||||||
|
### Accent (Interactive / CTA)
|
||||||
|
|
||||||
|
| State | Class |
|
||||||
|
|---|---|
|
||||||
|
| Default button | `bg-sky-600 text-white` |
|
||||||
|
| Hover | `hover:bg-sky-500` |
|
||||||
|
| Link / inline | `text-sky-400 hover:text-sky-300` |
|
||||||
|
| Active indicator | `text-sky-400` |
|
||||||
|
| Focus ring | `focus:ring-sky-500` |
|
||||||
|
|
||||||
|
### Semantic Colors
|
||||||
|
|
||||||
|
| Meaning | Color |
|
||||||
|
|---|---|
|
||||||
|
| Success / active | `text-green-400`, `bg-green-500/20` |
|
||||||
|
| Warning / caution | `text-yellow-400`, `bg-yellow-500/20` |
|
||||||
|
| Danger / error | `text-red-400`, `bg-red-500/20` |
|
||||||
|
| Info / neutral | `text-blue-400`, `bg-blue-500/20` |
|
||||||
|
|
||||||
|
### Status Badge Pattern
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Active / online
|
||||||
|
<span className="text-xs font-medium px-2 py-0.5 rounded-full bg-green-500/20 text-green-400">
|
||||||
|
active
|
||||||
|
</span>
|
||||||
|
|
||||||
|
// Offline
|
||||||
|
<span className="text-xs font-medium px-2 py-0.5 rounded-full bg-red-500/20 text-red-400">
|
||||||
|
offline
|
||||||
|
</span>
|
||||||
|
|
||||||
|
// Warning
|
||||||
|
<span className="text-xs font-medium px-2 py-0.5 rounded-full bg-yellow-500/20 text-yellow-400">
|
||||||
|
warning
|
||||||
|
</span>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Typography
|
||||||
|
|
||||||
|
Font stack: Tailwind default sans-serif (`font-sans`). **No Google Fonts.**
|
||||||
|
The product uses system fonts; the website must match.
|
||||||
|
|
||||||
|
| Element | Classes |
|
||||||
|
|---|---|
|
||||||
|
| Hero heading | `text-4xl md:text-6xl font-bold text-slate-100 leading-tight` |
|
||||||
|
| Section heading | `text-2xl md:text-3xl font-bold text-slate-100` |
|
||||||
|
| Subsection heading | `text-xl font-semibold text-slate-200` |
|
||||||
|
| Body text | `text-base text-slate-400 leading-relaxed` |
|
||||||
|
| Small / label | `text-sm text-slate-400` |
|
||||||
|
| Tiny / tag | `text-xs font-medium text-slate-500` |
|
||||||
|
| Code / monospace | `font-mono text-sky-400` |
|
||||||
|
| Accent text | `text-sky-400` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Spacing & Layout
|
||||||
|
|
||||||
|
- Max content width: `max-w-7xl mx-auto px-6`
|
||||||
|
- Section padding: `py-24` (desktop), `py-16` (mobile)
|
||||||
|
- Card padding: `p-6`
|
||||||
|
- Gap between grid items: `gap-6` or `gap-8`
|
||||||
|
- All layouts are mobile-first; use `md:` and `lg:` breakpoints.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Components
|
||||||
|
|
||||||
|
### Primary CTA Button
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<a
|
||||||
|
href="/docs/getting-started"
|
||||||
|
className="inline-flex items-center gap-2 px-6 py-3 rounded-lg
|
||||||
|
bg-sky-600 hover:bg-sky-500 text-white font-medium
|
||||||
|
transition-colors"
|
||||||
|
>
|
||||||
|
Get started
|
||||||
|
</a>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Secondary / Ghost Button
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<a
|
||||||
|
href="/features"
|
||||||
|
className="inline-flex items-center gap-2 px-6 py-3 rounded-lg
|
||||||
|
border border-slate-700 hover:border-slate-500
|
||||||
|
text-slate-300 hover:text-slate-100
|
||||||
|
transition-colors"
|
||||||
|
>
|
||||||
|
See all features
|
||||||
|
</a>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Feature Card
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className="rounded-xl border border-slate-800 bg-slate-900 p-6">
|
||||||
|
<div className="mb-4 flex h-10 w-10 items-center justify-center
|
||||||
|
rounded-lg bg-sky-600/10">
|
||||||
|
{/* Heroicon SVG, className="h-5 w-5 text-sky-400" */}
|
||||||
|
</div>
|
||||||
|
<h3 className="mb-2 text-lg font-semibold text-slate-100">Feature name</h3>
|
||||||
|
<p className="text-sm text-slate-400 leading-relaxed">
|
||||||
|
Description of the feature in one to three sentences.
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Screenshot Frame
|
||||||
|
|
||||||
|
App screenshots must be wrapped in this frame to integrate naturally
|
||||||
|
against the dark background:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className="rounded-xl border border-slate-700 overflow-hidden shadow-2xl">
|
||||||
|
<img src="/screenshots/device-list.png" alt="Device inventory" className="w-full" />
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
Optionally add a browser chrome header above the image:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className="flex items-center gap-1.5 border-b border-slate-700 bg-slate-800 px-4 py-2.5">
|
||||||
|
<span className="h-2.5 w-2.5 rounded-full bg-red-500/70" />
|
||||||
|
<span className="h-2.5 w-2.5 rounded-full bg-yellow-500/70" />
|
||||||
|
<span className="h-2.5 w-2.5 rounded-full bg-green-500/70" />
|
||||||
|
<span className="ml-4 text-xs text-slate-500 font-mono">netork.local</span>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Code Block
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<pre className="rounded-xl border border-slate-800 bg-slate-900 p-6
|
||||||
|
font-mono text-sm text-slate-300 overflow-x-auto">
|
||||||
|
<code>{`bash scripts/deploy.sh 192.168.1.1`}</code>
|
||||||
|
</pre>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Driver / Integration Badge
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<span className="inline-flex items-center gap-1.5 px-3 py-1 rounded-full
|
||||||
|
border border-slate-700 bg-slate-900
|
||||||
|
text-xs font-medium text-slate-300">
|
||||||
|
OpenWRT
|
||||||
|
</span>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Section Divider
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className="border-t border-slate-800" />
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Navigation
|
||||||
|
|
||||||
|
- Sticky top nav: `sticky top-0 z-10 bg-slate-900/80 backdrop-blur
|
||||||
|
border-b border-slate-800`
|
||||||
|
- Logo: left-aligned. Product name in `font-semibold text-slate-100`,
|
||||||
|
optionally prefixed with a small icon.
|
||||||
|
- Nav links: `text-sm text-slate-400 hover:text-slate-100 transition-colors`
|
||||||
|
- Active link: `text-slate-100`
|
||||||
|
- CTA in nav: small primary button `px-4 py-1.5 text-sm`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Animations & Transitions
|
||||||
|
|
||||||
|
- **Hover states:** always `transition-colors` (not `transition-all`).
|
||||||
|
- **No JavaScript animations** on initial page load — no entrance animations,
|
||||||
|
no scroll-triggered reveals via IntersectionObserver.
|
||||||
|
- Scroll behavior: `scroll-smooth` on `<html>` for anchor links.
|
||||||
|
- No parallax, no floating elements, no auto-playing videos.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Logo / Wordmark
|
||||||
|
|
||||||
|
The netOrk wordmark uses the following convention in the product:
|
||||||
|
- Lowercase `n`, uppercase `O`: **netOrk**
|
||||||
|
- Monospace context: `font-mono text-sky-400`
|
||||||
|
- Heading context: `font-bold text-slate-100` with `Ork` potentially in
|
||||||
|
`text-sky-400` if desired for emphasis
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Iconography
|
||||||
|
|
||||||
|
Use Heroicons (inline SVG). Sizes:
|
||||||
|
- Feature card icons: `h-5 w-5`
|
||||||
|
- Nav / button icons: `h-4 w-4`
|
||||||
|
- Hero / large decorative: `h-8 w-8` or `h-10 w-10`
|
||||||
|
|
||||||
|
All icons: `text-sky-400` in feature contexts, `text-slate-400` in
|
||||||
|
secondary/muted contexts.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## tailwind.config.js
|
||||||
|
|
||||||
|
No custom theme extensions needed. The default Tailwind v3 slate + sky
|
||||||
|
palette covers everything. The config only needs content paths:
|
||||||
|
|
||||||
|
```js
|
||||||
|
/** @type {import('tailwindcss').Config} */
|
||||||
|
export default {
|
||||||
|
content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
|
||||||
|
theme: {
|
||||||
|
extend: {},
|
||||||
|
},
|
||||||
|
plugins: [],
|
||||||
|
}
|
||||||
|
```
|
||||||
+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`
|
||||||
+173
@@ -0,0 +1,173 @@
|
|||||||
|
# netOrk — Product Description
|
||||||
|
|
||||||
|
## One-liner
|
||||||
|
|
||||||
|
**netOrk is a self-hosted network orchestration platform that discovers,
|
||||||
|
monitors, and manages heterogeneous network infrastructure from a single UI.**
|
||||||
|
|
||||||
|
## Elevator Pitch (3 sentences)
|
||||||
|
|
||||||
|
netOrk connects to your routers, switches, access points, firewalls, and servers
|
||||||
|
via NAPALM and custom vendor drivers — regardless of manufacturer. It continuously
|
||||||
|
polls device state, detects configuration drift, and lets you push corrections in
|
||||||
|
one click. All findings are synced to NetBox as the source of truth, and security
|
||||||
|
integrations with Wazuh and Graylog give you visibility across the full stack.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Target Audience
|
||||||
|
|
||||||
|
**Primary:** Network engineers and IT administrators managing small to medium
|
||||||
|
heterogeneous environments (10–500 devices) — mixed vendor, mixed OS.
|
||||||
|
|
||||||
|
**Secondary:** Serious homelab operators who run "prosumer" or enterprise-grade
|
||||||
|
hardware and want operational visibility beyond what consumer dashboards offer.
|
||||||
|
|
||||||
|
**Pain points this solves:**
|
||||||
|
- Multiple vendor-specific management UIs open at once
|
||||||
|
- No single view of "what's running where"
|
||||||
|
- Config changes made directly on devices — nobody knows what changed
|
||||||
|
- Manual SSH into every device to check interface status or VLAN membership
|
||||||
|
- Security tooling (Wazuh agents, syslog) not consistently deployed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Value Propositions
|
||||||
|
|
||||||
|
1. **One UI for everything** — OpenWRT APs, OPNsense firewalls, HP ProCurve
|
||||||
|
switches, Proxmox hosts, Linux servers, Fritz!Boxes, NAS devices, and more,
|
||||||
|
all managed in one place.
|
||||||
|
|
||||||
|
2. **Intent-based configuration** — Define desired state in netOrk (VLAN names,
|
||||||
|
SSID settings, AP radio profiles). netOrk pushes the config to devices and
|
||||||
|
corrects drift automatically or on demand.
|
||||||
|
|
||||||
|
3. **Automatic drift detection** — Every poll compares device config against the
|
||||||
|
DB. Drifted devices get a warning; a one-click fix stream applies the
|
||||||
|
correction via SSH/UCI/REST and shows live output.
|
||||||
|
|
||||||
|
4. **Scheduled automation** — Automatic reboots for OpenWRT APs (GTK key rotation
|
||||||
|
workaround), scheduled config fixes, package updates — all with time windows
|
||||||
|
and per-site concurrency limits.
|
||||||
|
|
||||||
|
5. **Security visibility** — Wazuh agent tracking with CVE counts and alert history
|
||||||
|
per device. Graylog syslog forwarding status and auto-fix. CrowdSec org-level
|
||||||
|
threat summary per device.
|
||||||
|
|
||||||
|
6. **Deep NetBox integration** — Devices, interfaces, IP addresses, prefixes,
|
||||||
|
VLANs synced to NetBox automatically. netOrk uses NetBox as the canonical
|
||||||
|
documentation target.
|
||||||
|
|
||||||
|
7. **Plugin system** — Integrations (Wazuh, Graylog, CrowdSec, apt-cacher-ng)
|
||||||
|
are plugins that can be enabled/disabled per deployment. Adding a new
|
||||||
|
integration follows a documented pattern.
|
||||||
|
|
||||||
|
8. **Self-hosted, no SaaS** — Runs in Docker Compose. Your data stays on your
|
||||||
|
infrastructure. No telemetry, no cloud dependency.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature List
|
||||||
|
|
||||||
|
### Device Management
|
||||||
|
- CRUD for devices with credential profiles and SSH key management
|
||||||
|
- Per-device poll intervals (minutes) or manual-only
|
||||||
|
- Status tracking: planned / staged / active / decommissioning / offline / disabled
|
||||||
|
- Vendor/model/OS auto-populated from NAPALM `get_facts()`
|
||||||
|
- Site assignment with FK to structured Site records
|
||||||
|
- AP Profile assignment for grouped OpenWRT config
|
||||||
|
|
||||||
|
### Discovery
|
||||||
|
- ICMP ping sweep, SNMP scan, HTTP/HTTPS probing
|
||||||
|
- Device fingerprinting: vendor + platform confidence scoring
|
||||||
|
- FQDN resolution (reverse DNS)
|
||||||
|
- Manual adoption from scan results (no auto-create to avoid inventory noise)
|
||||||
|
|
||||||
|
### Supported Device Drivers
|
||||||
|
Custom NAPALM drivers for all of the following:
|
||||||
|
|
||||||
|
| Driver | Device type |
|
||||||
|
|---|---|
|
||||||
|
| `openwrt` | OpenWRT access points |
|
||||||
|
| `opnsense` | OPNsense firewalls |
|
||||||
|
| `proxmox` | Proxmox VE hypervisors |
|
||||||
|
| `linux` | Generic Linux servers |
|
||||||
|
| `procurve` | HP ProCurve / Aruba switches |
|
||||||
|
| `tplink_jetstream` | TP-Link Jetstream managed switches |
|
||||||
|
| `netgear` | Netgear switches |
|
||||||
|
| `fritzbox` | AVM Fritz!Box routers |
|
||||||
|
| `zyxel` | Zyxel switches |
|
||||||
|
| `openmediavault` | OpenMediaVault NAS |
|
||||||
|
| `sonos` | Sonos speakers |
|
||||||
|
|
||||||
|
Plus all built-in NAPALM drivers: Cisco IOS/IOS-XE/NX-OS, Arista EOS, Juniper JunOS.
|
||||||
|
|
||||||
|
### Networking & Inventory
|
||||||
|
- Interface browser with IPv4/IPv6 addresses, MAC, speed, MTU
|
||||||
|
- LLDP neighbor discovery and topology graph
|
||||||
|
- ARP table and DHCP lease browser per device
|
||||||
|
- Subnet browser with interface-to-subnet assignments
|
||||||
|
- VLAN list grouped by site; per-VLAN device membership view
|
||||||
|
- SSID management with push to OpenWRT APs via UCI
|
||||||
|
|
||||||
|
### Configuration Management
|
||||||
|
- Config drift detection: desired state (DB) vs device state (poll snapshot)
|
||||||
|
- One-click drift fix stream with live SSH output in the browser
|
||||||
|
- UCI-based config push for OpenWRT (VLAN names, SSID settings, radio config)
|
||||||
|
- AP profile system: country code, HT/VHT mode, 802.11r, NTP, syslog, SSH port
|
||||||
|
|
||||||
|
### Scheduled Operations
|
||||||
|
- Scheduled reboots for OpenWRT APs with per-site concurrency lock
|
||||||
|
- Failback cron script written to device for netOrk-unreachable scenarios
|
||||||
|
- Scheduled config drift fixes with time-window enforcement
|
||||||
|
- Package update scheduling and one-click apply
|
||||||
|
|
||||||
|
### Monitoring & Health
|
||||||
|
- SNMP health metrics (CPU, memory, interface counters) via `get_health_metrics()`
|
||||||
|
- Per-device warning system with severity levels (error / warning / info)
|
||||||
|
- Docker container and image status (Proxmox/Linux)
|
||||||
|
- Service status and start/stop/restart (systemd)
|
||||||
|
- VM/container list with OS device cross-linking (Proxmox)
|
||||||
|
|
||||||
|
### Security Integrations (plugins)
|
||||||
|
- **Wazuh** — agent enrollment tracking, vulnerability counts (by severity),
|
||||||
|
recent alert history, CIS benchmark scores, one-click agent install fix stream
|
||||||
|
- **Graylog** — rsyslog forwarding status per device, one-click fix to write rule
|
||||||
|
- **CrowdSec** — org-level decisions, remediation metrics, top attack scenarios
|
||||||
|
|
||||||
|
### DNS
|
||||||
|
- DNS zone management with authoritative device assignment
|
||||||
|
- Forward record provisioning (A records from device interfaces)
|
||||||
|
- PTR record provisioning to reverse zones
|
||||||
|
- Pending job queue for zone changes when device is unreachable
|
||||||
|
|
||||||
|
### Access Control
|
||||||
|
- JWT authentication with remember-me (localStorage) or session-only (sessionStorage)
|
||||||
|
- RBAC with four built-in roles: viewer / operator / engineer / administrator
|
||||||
|
- Custom roles with any permission combination
|
||||||
|
- Full audit log of all orchestration actions
|
||||||
|
|
||||||
|
### NetBox Sync
|
||||||
|
- Pushes vendor, model, OS version, status to NetBox dcim.devices
|
||||||
|
- Syncs interfaces, IP addresses, prefixes, VLANs
|
||||||
|
- VM interfaces and disks for Proxmox hosts
|
||||||
|
|
||||||
|
### Developer / Operator Experience
|
||||||
|
- OpenAPI / Swagger at `/docs`
|
||||||
|
- Plugin system: new integrations follow a documented pattern
|
||||||
|
- Celery task queue with dedicated queues per workload type
|
||||||
|
- Docker Compose deployment (single command)
|
||||||
|
- Alembic migrations run automatically on deploy
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture in One Paragraph
|
||||||
|
|
||||||
|
netOrk runs as five Docker containers: a FastAPI API server, two Celery worker
|
||||||
|
pools (general + poll), a Celery Beat scheduler, and an nginx UI server. Redis
|
||||||
|
is the broker. PostgreSQL stores all state. Device communication is always
|
||||||
|
blocking I/O executed in Celery workers — FastAPI request handlers are
|
||||||
|
async-only for DB and quick operations. Custom NAPALM drivers live in `vendor/`
|
||||||
|
as editable packages and self-register via `@register_driver`. The plugin system
|
||||||
|
(`netork/plugins/`) provides a hook bus, a plugin registry with enable/disable
|
||||||
|
state in the DB, and a documented pattern for adding integrations.
|
||||||
Reference in New Issue
Block a user