# Metro Fabric — Grid Dashboard ## Project Handoff for Claude Code --- ## What This Is **Grid** is the control panel for Metro Fabric (`grid.metrofabric.net`) — a full-stack agentic ISP platform. It's not just infrastructure management. The product has two layers: - **Infrastructure layer** — ISP-classified IPs, BGP routing, bare metal compute, subnets, geolocation - **Traffic layer** — IP pools, proxy sessions, Docker workloads, traffic rules, success analytics, targets Target customers: Bright Data, Oxylabs, AI agent companies, LLM pipeline operators. These customers can't get ISP-classified IPs co-located with compute anywhere else. That's the positioning. --- ## Files ``` /Users/vincentas/dev/Metro Fabric/Grid/ ├── grid-dashboard.html # Main control panel (single HTML file, ~13,498 lines) ├── grid-auth.html # Sign up + login + forgot password + SSO providers ├── ui-elements.html # Web UI Kit — components, brand guidelines, design tokens ├── demo.html # Demo preview — links, stats, brand, pricing, all sections overview ├── CLAUDE.md # Project journal — architecture, status, roadmap ├── DEV-GUIDE.md # Developer onboarding guide — setup, patterns, Cursor tips └── .cursorrules # Cursor IDE rules — auto-loaded by Cursor for AI assistance ``` Both are **single-file HTML apps** — all CSS and JS inline. No build step. Served via `python3 -m http.server 8765`. --- ## Brand Tokens ```css /* Primary */ --blue: #0ea5e9; /* Signal Blue — primary actions, active states */ --blue-dark: #0284c7; --blue-bg: #f0f9ff; --blue-bdr: rgba(14,165,233,0.2); /* Secondary */ --orange: #f97316; /* Metro Orange — traffic layer accent */ --orange-bg: #fff7ed; --orange-bdr: rgba(249,115,22,0.2); /* Semantic */ --success: #16a34a; /* [dark: #22c55e] */ --error: #dc2626; /* [dark: #ef4444] */ --warning: #d97706; /* [dark: #f59e0b] */ /* Surfaces (light) */ --bg: #f4f4f5; --bg-card: #ffffff; --bg-input: #ffffff; --bg-hover: #f4f4f5; --sidebar-bg: #ffffff; --border: #e4e4e7; --border-mid: #d4d4d8; /* Surfaces (dark) */ --bg: #070d1a; --bg-card: #0d1526; --bg-input: #111d33; --sidebar-bg: #0a1220; --border: rgba(255,255,255,0.08); /* Typography */ --text: #18181b; --text-body: #3f3f46; --text-muted: #71717a; --text-dim: #a1a1aa; ``` ```css /* AI Accent */ --ai-purple: #8b5cf6; /* [dark: #a78bfa] */ --ai-purple-dark: #7c3aed; --ai-purple-bg: #f5f3ff; --ai-purple-bdr: rgba(139,92,246,0.2); --ai-gradient: linear-gradient(135deg, #8b5cf6, #06b6d4); ``` **Fonts:** Geist (display/body) + Geist Mono (labels, code, monospace values) **Radii:** `--radius: 8px`, `--radius-lg: 12px` **Logo:** 3×3 grid mark, Signal Blue dots with 0.22 opacity on alternating cells **Theme:** Light default, dark toggle persists to `localStorage` key `mf-grid-theme`, also respects `prefers-color-scheme` --- ## Dashboard Architecture ### Layout ``` .app (flex row, 100vh) ├── .sidebar (224px fixed, flex column) │ ├── .sidebar-logo (Metro Fabric + GRID badge) │ ├── .sidebar-nav (scrollable nav items) │ ├── .sidebar-footer (user avatar + name + role + user menu popup + locale popup) │ └── .sidebar-collapse-btn (toggle collapsed icon-only mode) └── .main (flex column, flex:1) ├── .header (52px, breadcrumb + search + AI btn + helpdesk/status/notif popups + CTA) └── .content (scrollable, padding 24px) └── .view divs (one per section, display:none unless .active) Floating overlays (outside .app): ├── #ai-palette (Cmd+K command palette, z-index 500) ├── #ai-chat + overlay (AI chat drawer, z-index 300) └── #wt-overlay/spotlight/balloon (walkthrough onboarding, z-index 9000+) ``` ### Navigation ```javascript nav(section, el) // switches active view, updates header navSub(section, sub, el) // switches sub-section, triggers sub-renderer syncSidebarHighlight(section, sub) // syncs sidebar active state + breadcrumb (called by all tab switchers, uses regex to match second argument of navSub() for accurate sub-item highlighting) currentSection // global tracking current section currentSubSection // global tracking current sub-section headerCTA() // dispatches header button action per section ``` ### Theme toggle ```javascript toggleTheme() // switches light/dark, persists to localStorage ``` --- ## Sidebar Sections & Build Status ### Main | Section | ID | Status | |---|---|---| | Overview | `view-overview` | ✅ Built — AI Insights card, 2 stat rows (infra + traffic) with tooltips, PoP health grid, SVG bandwidth line chart (14 days, Y-axis scale, date labels, area fill, hover circles), workloads table, alerts, pool utilisation, activity feed | | Alerts & Events | `view-alerts` | ✅ Built — nav group with 8 sub-items: Active Alerts, Alert Routing (8 rules + add/edit/delete modal with type/severity/channel config), Contacts, Templates, Schedule, System Logs (unified from Containers + Workloads + Compute + Auto-Scaling with source tabs + sortable columns), Abuse Reports (3 cases with severity/status, message thread with staff/customer replies, status update) | ### Infrastructure | Section | ID | Status | |---|---|---| | Locations | `view-locations` | ✅ Built — nav group with sub-items: Map View (D3 world map, zoom/pan) + List View (continent groups, collapsible), detail drawer, filters | | Network | `view-network` | ✅ Built — 14 networks, pool+sessions column, sparklines, detail drawer with traffic layer card, 5-step provision wizard | | BGP Management | `view-bgp` | ✅ Built — 12 BGP sessions, filters, detail drawer (peer config, session params, routes) | | IP Geolocation | `view-geolocation` | ✅ Built — per-subnet card grid, 7 providers (IPXO, MaxMind, IP2Location, IPInfo, DB-IP, ipapi, ipgeolocation), match % bars with drifted IP counts, pending = gray, ETAs | | Compute | `view-compute` | ✅ Built — nav group with 2 tabs: Nodes (21 bare metal, inline Actions column with Console / Reboot / Manage buttons per row using .cr-btn pattern, drawer with CPU/RAM sparklines + IPMI console proxy + power actions + reinstall OS wizard + per-node activity log) + Logs (team audit log with sortable columns + level/search filters, auto-logging). All log tables globally have sortable columns. | | Subnets | `view-subnets` | ✅ Built — nav group with 2 sub-items (Subnets, BYOIP). **Subnets tab:** 14 subnets from NETWORKS, location/network/geo filters, pool assignment, compute nodes, redesigned Assign IPs modal (multi-location memory, CIDR /30-/16 selector, paginated subnet browser, bulk select with cross-location persistence). **BYOIP tab:** 6 prefixes, 4 stat cards, filterable table (source/status filters), 4-step add wizard (Source → Prefixes → Network → ROA), IPXO account import, third-party manual entry with auto-detect IPv4/IPv6 + RIR, multi-prefix support, per-prefix network assignment, ROA instructions with copy buttons, field validation (private/reserved/loopback/multicast ranges blocked, /8-/24 IPv4, /32-/48 IPv6, duplicate check), verify/retry/manage actions | ### Traffic Layer | Section | ID | Status | |---|---|---| | IP Pools | `view-pools` | ✅ Built — 5 pools, filters, detail drawer (feeding networks, rotation, workloads), create pool wizard | | Sessions | `view-sessions` | ✅ Built — 20 sessions, pool/status/target filters, per-row Rotate IP / Terminate actions, bulk selection bar (replaces header when items selected, uses showToast() instead of alert()), select all | | Workloads | `view-workloads` | ✅ Built — Container Manager with 7 tabs: Overview (stats + SVG CPU/RAM charts + top containers), Stacks (YAML editor), Containers (sortable + terminal + logs), Images, Registry (Docker Hub), Logs (sortable audit), Scaling (5 auto-scaling rules with metric/threshold/duration/action/cooldown, enable/disable toggle, create/edit wizard, 6-entry scaling history with success/failed status) | | Traffic Rules | `view-rules` | ✅ Built — 11 rules, target patterns, pool assignment, geo-matching, priority, hit counts, per-row Edit/Delete action buttons | | Success Analytics | `view-analytics` | ✅ Built — volume chart, success/block rate chart, by-pool & by-target breakdowns, block rate heatmap | | Targets | `view-targets` | ✅ Built — 12 target domains, pool assignment, success/block rates, rate limits, status, per-row Edit/Delete action buttons | ### Developer | Section | ID | Status | |---|---|---| | Access & API | `view-api` | ✅ Built — API keys (4), webhooks (3), usage stats with progress bar | | Marketplace | `view-marketplace` | ✅ Built — 12 integrations (GitHub, n8n, Cloudflare, AWS, GCP, Terraform, Grafana, Datadog, Slack, Docker Hub, PagerDuty, Zapier), card grid with deploy/disconnect | ### Account | Section | ID | Status | |---|---|---| | Settings | `view-settings` | ✅ Built — 6 sub-tabs: Profile (country/timezone required), Company, Team, Security (2FA with QR/recovery codes/disable modals, change password with strength meter, session timeout dropdown, active sessions with revoke, connected accounts: GitHub/GitLab/Microsoft/AWS/Google SSO with connect/disconnect), Notifications (channels + newsletter: Product Updates/Tips/Marketing), Preferences (3 cards: Display/Date&Time/Table&Layout). Profile has Sign Out button at bottom. Security has Danger Zone with Delete Account (checks active infra: blocks if running containers/networks/stacks, shows transfer options, or confirms with password + type DELETE). CTA saves with green feedback. | | Billing | `view-billing` | ✅ Built — 6 sub-tabs with content tabs: Overview (due invoice alert + stats + cost breakdown + usage gauges), Usage (infra/traffic/platform tables), Invoices (3 due + 3 paid + 3 credit notes, bulk pay, appreciation banner), Payment Methods (Visa/MC/Amex + PayPal/Crypto/AliPay/Bank), Plans (Starter/Growth/Enterprise with scaling tiers), Add Funds (credits + auto-reload + transaction history with View/PDF) | ### AI & Platform Features | Feature | ID / Selector | Status | |---|---|---| | AI Command Palette | `#ai-palette` | ✅ Built — Cmd+K overlay, fuzzy search, grouped commands (Quick Actions, Create, AI Actions, System), arrow key nav, "Ask AI" fallback | | AI Assistant Chat | `#ai-chat` | ✅ Built — right-side drawer, conversational AI with contextual responses, follow-up suggestions, typing indicator, auto-resize input | | AI-Enhanced Search | `#search-box` / `#search-dropdown` | ✅ Built — dropdown with AI suggestions, real-time search across locations/networks/pages, highlight matches, "Ask AI" fallback | | AI Insights Card | `#ai-insights` | ✅ Built — overview page card with live analysis badge, 4 proactive insights (anomalies, recommendations), clickable navigation | | Walkthrough Onboarding | `#wt-overlay` / `#wt-balloon` | ✅ Built — 9-step guided tour with spotlight effect, welcome modal with Metro Fabric logo, progress dots, back/next/skip, localStorage persistence (currently disabled for dev) | | Setup Wizard | `#setup-wizard` | ✅ Built — 3-step wizard that launches FIRST on page load: Country/Timezone → 2FA setup → Newsletter opt-in. After completion/skip, walkthrough tour starts. Skip shows toast with Settings directions. localStorage dev mode. | | Persistent Tab Bar | `#pinned-tabs` | ✅ Built — UniFi-style tab bar below header. Sections with unsaved form changes auto-pin when navigating away. Orange dot indicates dirty state. X button confirms discard. Saving removes the tab. Works on Settings, Billing, Alerts, API sections. | | Collapsible Sidebar | `.sidebar.collapsed` | ✅ Built — toggle button at bottom of sidebar, collapses to 56px icon-only mode. Auto-collapses below 1200px viewport. Persists to localStorage. Preferences toggle controls default. | | Platform Tooltips | `.mf-tip` | ✅ Built — data-tip attribute system with hover tooltips on key elements (stat cards, header buttons, sidebar nav groups, AI insights). Click tooltip icon shows option to disable all. Respects Settings > Preferences toggle. `body.tips-off` class hides all. | | AI Header Button | `.ai-btn` | ✅ Built — purple/cyan gradient sparkle button in header, pulse animation, opens AI chat | | Header Popups | `#popup-helpdesk/status/notifs` | ✅ Built — Helpdesk (live chat, docs, report issue), System Status (per-service health), Notifications (recent alerts with navigation) | | User Menu | `#user-menu` | ✅ Built — expandable popup in sidebar footer, links to Settings/Billing/Tour, sign out, language & currency selector | | Locale Selector | `#locale-popup` | ✅ Built — language (English, Spanish, French, German, Chinese, Japanese) + currency (USD, EUR, GBP) in sidebar footer popup | --- ## Key Data Structures ### LOCS (80 PoPs) ```javascript { id, city, country, region, isp, ips, compute, status, // 'active' | 'degraded' | 'down' | 'available' lat, lng, // for map projection capacity, // 0-100, available capacity remaining equinix // IBX designation e.g. 'LD4/LD5' } ``` ### NETWORKS (14 networks) ```javascript { id, name, location, isp, subnet, ips, compute, uptime, // percentage float bw, // [float x7] — last 7 days Tbps status, // 'active' | 'degraded' | 'down' pool, // IP pool name or null sessions, // active session count successRate, // float or null workloads, // string[] of running image names rotation // e.g. 'Rotating · 30s' or null } ``` ### ALERTS (12 alerts) ```javascript { id, sev, // 'critical' | 'warning' | 'info' type, // 'bgp' | 'geo' | 'compute' | 'billing' | 'workload' | 'pool' | 'abuse' title, desc, location, time, status, // 'active' | 'acknowledged' | 'resolved' eta // string or null } ``` --- ## Header CTA Dispatcher The header "+ [Action]" button calls `headerCTA()` which dispatches based on `currentSection`: ```javascript const ctaActions = { network: () => openNetworkWizard(), alerts: () => markAllRead(), locations: () => openNetworkWizard(), compute: () => ctaAddComputeNode(), subnets: () => ctaAssignIps(), api: () => ctaCreateApiKey(), settings: () => ctaSaveSettings(), billing: () => ctaAddFunds(), pools: () => openPoolWizard(), workloads: () => openWlWizard(), sessions: () => { /* select all active */ }, rules: () => ctaAddTrafficRule(), analytics: () => ctaExportAnalytics(), targets: () => ctaAddTarget(), bgp: () => ctaAddBgpSession(), geolocation: () => ctaRunGeoVerification(), marketplace: () => ctaRequestIntegration(), }; ``` --- ## Provision Network Wizard 5-step modal (`#net-wizard`): 1. **Location** — pick from active PoPs 2. **ISP** — location-aware ISP options with AS numbers 3. **Subnet** — name + /24 to /20 size 4. **Pool** — attach to existing IP pool (or skip) 5. **Confirm** — summary + provision State: `wizData = { location, isp, subnet, name, pool }` Functions: `openNetworkWizard()`, `closeNetworkWizard()`, `renderWizStep()`, `wizStep(dir)` --- ## Location Map Uses D3 v7 + TopoJSON loaded from CDN at runtime (lazy, only when Locations view becomes active). ```javascript mapProjection // d3.geoNaturalEarth1 mapZoomBehavior // d3.zoom, scaleExtent [0.6, 12] mapSvgSel // d3 selection of #world-svg ``` Dots scale inversely with zoom (`r / k`) so they stay constant visual size. Fallback: equirectangular projection if D3 fails to load. --- ## AI Command Palette Cmd+K overlay (`#ai-palette`), structured as grouped command list: ```javascript AI_COMMANDS = [ {group:'Quick Actions', items:[...]}, // 15 nav items (all sections) {group:'Create', items:[...]}, // 7 wizard/create actions {group:'AI Actions', items:[...]}, // 5 AI-powered queries {group:'System', items:[...]}, // 3 system actions ]; ``` Functions: `openAiPalette()`, `closeAiPalette()`, `renderPaletteItems(query)`, `paletteSelect(idx)` Keyboard: `⌘K` toggle, `↑↓` navigate, `Enter` select, `Esc` close Any unmatched query shows "Ask AI" option that opens AI chat with the query. --- ## AI Chat Panel Right-side drawer (`#ai-chat`, 420px) with simulated conversational AI. ```javascript AI_RESPONSES = { ... } // keyword-matched response bank getAiResponse(msg) // matches user input to responses, returns {text, followUps} sendAiMessage(text) // renders user msg, typing indicator, then AI response openAiChat() // slides panel in closeAiChat() // slides panel out ``` Responses cover: network health, pool optimization, Sydney outage, bandwidth trends, session analytics, and generic fallbacks. --- ## AI-Enhanced Search Search box (`#search-box`) with dropdown (`#search-dropdown`). ```javascript SEARCH_INDEX = [...] // locations + networks + all sections, each with action() renderSearchDropdown(q) // filters index, shows results + "Ask AI" fallback ``` Empty state shows AI suggestions + recent items. Typing filters across all indexed items with highlight. --- ## Walkthrough Onboarding 10 items total (1 welcome + 9 guided steps): | Step | Target | What it highlights | |------|--------|--------------------| | 0 | (centered modal) | Welcome screen with Metro Fabric logo, "Show me around" CTA | | 1 | `.sidebar-logo` | Introduces Grid as the control plane | | 2 | `.sidebar-nav` | Sidebar navigation structure | | 3 | `#search-box` | Smart search + ⌘K command palette | | 4 | `.ai-btn` | AI Assistant button | | 5 | `#hdr-cta` | Context-aware header action button | | 6 | `#ai-insights` | AI Insights proactive monitoring card | | 7 | `.stats-grid` | Infrastructure & traffic stats | | 8 | `.sidebar-footer .user-row` | Account / user profile | | 9 | `.notif-btn[title="Notifications"]` | Alerts & notifications bell | ```javascript WT_STEPS = [...] // step definitions with target, arrow, title, body, placement startWalkthrough() // begins tour from step 0 endWalkthrough() // closes tour, sets localStorage restartWalkthrough() // clears localStorage, restarts ``` Spotlight: blue glow box-shadow with 9999px spread for dimming. Balloon: auto-flips placement when it would overflow viewport. Persistence: `localStorage` key `mf-grid-walkthrough` (currently commented out for dev). --- ## Billing 6 sub-tabs rendered by `renderBillingSub(sub)`, triggered via `navSub('billing', sub, el)`. ### Hybrid Pricing Model - **Infrastructure:** $1.50/IP/month (volume discounts at 5K, 10K, 25K+ IPs), compute bundled, bandwidth commit included - **Traffic:** $5/GB standard, $8/GB geo-targeted, $0.85/1K session-hours, successful requests tracked - **Platform:** Starter $499/mo (manual scaling), Growth $2,499/mo (auto-scaling 5 rules), Enterprise custom (unlimited rules + custom metrics) ### Data Structures ```javascript BILLING_PLAN // current plan: name, price, apiLimit, pools, locations, team BILLING_USAGE // infra (ips, compute, bandwidth), traffic (transfer, requests, sessions), platform (api, webhooks, team) BILLING_INVOICES // 6 months of invoices: id, date, period, amount, status, dueDate/paidDate BILLING_PAYMENTS // payment methods: type, last4, exp, isDefault, name ``` ### Sub-tabs | Tab | Content | |-----|---------| | Overview | Stat cards (plan, MTD, projected, credits), cost breakdown bars, plan usage gauges, due invoice alert | | Usage | 3 tables — infrastructure, traffic, platform — with quantities, rates, subtotals | | Invoices | 6-month history, status badges (paid/due), View/PDF/Pay actions | | Payment Methods | Card list with default toggle, add/remove, wire transfer info | | Plans | 3-tier comparison (Starter/Growth/Enterprise), feature lists, upgrade buttons | | Add Funds | Credits balance, auto-reload config, quick-add buttons ($1K/$5K/$10K), custom amount | --- ## Auth File (grid-auth.html) Three views: `view-signup`, `view-login`, `view-forgot` **Sign up:** 2-step form - Step 1: first name, last name, email, password (strength meter), confirm - Step 2: company name, website (auto-prepends https://), use case, bandwidth tier, company size, annual revenue, terms - Step 3: email verification screen **Login:** email + password, demo credentials (`demo@metrofabric.net` / `Demo1234!`), forgot password link **Left panel:** Two-tier product story — Infrastructure (blue) + Traffic Layer (orange) **Tagline:** "The network your AI agents can't get anywhere else." **Subtitle:** Option D — "The infrastructure layer your AI agents can't get anywhere else. ISP-classified IPs and bare metal compute, co-located and managed from a single control plane." Icons (helpdesk, system status, theme toggle) appear centered below each form card. --- ## Build Conventions - **Single HTML file** — all CSS in `