dev_arc_aws/design-decisions.md

ArchNest — Design Decisions & Page Reference

Living reference for visual/UX conventions and what's actually built on each page. Apply the Global Rules consistently to any new page. The Page Notes section describes the real, deployed implementation — not a mockup. If you change a page's layout or data source, update its section here in the same PR.

This file replaces the old archnest-blueprint.md (original 6-page mockup pitch, since deleted — superseded by the real 11-page app below) and glance.md (original Glance spec with fictional config files like systems.config/infra.config that were never built — also deleted). Anything from those files still true (color palette, typography, card style, dropdown menu shape) has been folded in below.

---

Global Rules (apply to every page)

Sidebar

• Expanded width: 200px. Collapsed width: 64px (icons only).
• User can manually collapse/expand via a toggle button (not just responsive breakpoints).
• Main content margin-left must match the sidebar width exactly.
• Bottom of sidebar: live "System Status" widget — green dot + "All Systems Operational" or "X Issue(s) Detected", driven by polling integration status (not the fictional ping-sweep config described in the old spec).

Page Title (Top Bar)

• Color: gold #C8A434 — not white. Use inline style={{ color: '#C8A434' }} if a Tailwind class doesn't apply.
• Font: 18px, bold, uppercase, tracking-wide.
• No border on the top bar — it blends into the page background.
• Pages with a pageSubtitles entry (currently only BookNest) render a larger 28px title + subtitle line instead, and the top bar grows from 56px → 72px — see TopBar.tsx's pageSubtitles map and App.tsx's topBarHeight lookup, which must be kept in sync or the layout clips/gaps.

Colors

Dark Mode (Default — Shipped)

Role	Value
Background (page)	#0D0E10
Background (cards)	#141518
Background (sidebar)	#0A0B0D
Border (cards)	#1E2025
Border/accent (hover/active)	#C8A434 (gold)
Success	#2ECC71
Warning	#E67E22
Danger	#E74C3C
Text (primary)	#E8E6E0
Text (secondary)	#7A7D85

Light Mode (Planned — Palette Documented)

Role	Value
Background (page)	#F7F6F3 (warm off-white)
Background (cards)	#FFFFFF (pure white)
Background (sidebar)	#FAF9F7 (very light warm gray)
Border (cards)	#E8E5DF (soft warm border)
Border/accent (hover/active)	#C8A434 (gold — same as dark)
Success	#2ECC71
Warning	#E67E22
Danger	#E74C3C
Text (primary)	#1A1A1A (near-black)
Text (secondary)	#6B6560 (warm gray)

Hero banners per mode:

• Dark: assets/themes/archnest-default/archnest-default-dark.png — dark sci-fi cityscape with neon arches
• Light: assets/themes/archnest-default/archnest-default-light.png — luminous white/gold cityscape, bright sky

Geometric/card backgrounds per mode:

• Dark: textured black slate with angular gold-lit geometric cuts (top-left and bottom-right diagonal slashes with warm gold edge lighting). Dominant colors: near-black slate #1A1815, charcoal #0F0E0C, gold edge glow #C8A434 → #8B6914.
• Light: cream marble with matching diagonal geometric cuts and warm gold edge lighting. Dominant colors: warm cream #F0EDE6, gold highlights #C8A434.

---

Forest Theme

A second theme with dark and light modes. Same structural layout as the default but with a different visual identity — mountainous alien landscapes with amber/gold point lights and a massive planet in the sky.

Forest — Dark Mode

Role	Value	Notes
Page background	#080806	Near-black with warm brown undertone
Card background	#121210	Dark charcoal-brown
Sidebar background	#0A0A08	Deepest surface
Border	#1E1C18	Warm dark border
Accent	#D4A850	Warm amber/gold (slightly warmer than default)
Success	#2ECC71
Warning	#E67E22
Danger	#E74C3C
Text primary	#E8E4DC	Warm off-white
Text secondary	#7A7568	Warm gray-brown

Hero banner: dark alien mountain landscape with massive planet, amber point lights on a grid floor, warm gold highlights on peaks. Deep blacks with scattered amber/gold sparks. Asset: assets/themes/forest/forest-dark.png

Forest — Light Mode

Role	Value	Notes
Page background	#F5F2ED	Warm ivory
Card background	#FFFFFF	Pure white
Sidebar background	#FAF8F4	Lightest warm tone
Border	#E5E0D8	Soft warm border
Accent	#D4A850	Same amber/gold as dark mode
Success	#2ECC71
Warning	#E67E22
Danger	#E74C3C
Text primary	#1A1810	Warm near-black
Text secondary	#6B6558	Warm brown-gray

Hero banner: luminous white/ivory mountain landscape with massive planet, golden sparkle points on a marble-like floor, peaks dusted in white with gold vein highlights. Ethereal, bright, airy. Asset: assets/themes/forest/forest-light.png

Tailwind v4 @theme custom colors (text-gold, bg-card, etc.) don't always apply reliably — fall back to inline style={{ color: '#C8A434' }} when a color isn't rendering, and verify visually after changes.

Typography

• Card titles: 10-11px, uppercase, tracking-[1.5px], secondary color, font-medium.
• Large numbers: 24-28px, bold, primary color.
• Subtitles/labels: 10-11px, secondary color.
• Body text in lists: 13px, primary color.
• Timestamps: 11px, secondary color.

Card Style

• Border radius: 12px. Background #141518. Border 1px solid #1E2025.
• Padding: 16-24px depending on density. No shadows (flat design).
• Hover: border transitions to gold, 0.2s ease.

Content Alignment

• All rows in a page share the same horizontal padding (px-6 at the parent container level) so the hero banner, status cards, and content rows line up left/right.

Animations

• Card hover: border → gold, 0.2s ease.
• Progress ring / sparkline: animate from 0 on load, ~1s.
• Progress bars: fill animation ~0.8s.

Icons

• Lucide React, 14-18px depending on context. Gold for active/accent, secondary color for inactive. Gold glow on active sidebar items: shadow-[0_0_6px_rgba(200,164,52,0.5)].
• Gotcha: the installed lucide-react version's TypeScript types list some brand/wordmark icons (Github, Gitlab, Linkedin, Youtube) that aren't actually exported at runtime — tsc --noEmit stays clean while the page renders blank with a runtime SyntaxError only visible in the Vite dev log. Verify icon names against the package's actual exports before importing anything brand-flavored.

No Footer

• No page has a fixed footer/status bar. Don't add one unless explicitly requested.

Target Display

• Primary design target: 16-inch / 1920px-wide screen. Don't constrain content width unnecessarily — design should feel spacious.

User Avatar & Dropdown (TopBar, every page)

• 36px circle, gold border + glow, shows uploaded avatar image or initials.
• Adjacent: display name + "Administrator" role label, chevron (rotates on open).
• Dropdown menu: header (name + email) → Profile (/settings?tab=profile) → Appearance (/settings?tab=appearance) → Security (/settings?tab=security) → Help & Support (/help) → divider → Sign Out (red, danger styling). See TopBar.tsx.

---

Page Notes (what's actually built, page by page)

All pages below consume real backend data via src/lib/api.ts — zero mock data anywhere in the app. Where a section says "real backend data," it means an actual SQL-backed or live-polled endpoint, not a config file or static array.

Glance (/)

• Hero banner (image with radial-gradient fade mask) + KPI cards overlapping the bottom edge via negative margin.
• 4 status cards: System Status (% of integrations reachable), Infrastructure (resource count + health breakdown from api.listResources()), Integrations (connected/total from api.listIntegrations()), Bookmarks (total + favorites from api.listBookmarks()).
• Middle row (3 columns): Resource Overview (top 6 resources + status), Recent Activity (5 latest from api.listEvents(5)), problem/critical resources widget.
• Bottom row: Connected Integrations grid + 4 Shortcuts buttons (to Settings, BookNest, Infrastructure).
• No footer. Hides the hero gracefully if the banner image fails to load.
• There is no systems.config/infra.config/ping-sweep/fail2ban machinery — that was speculative spec from before the backend existed. Health figures are derived directly from each integration adapter's testConnection() result, polled by the existing /api/integrations list.

Infrastructure (/infrastructure)

• Hero banner at the App.tsx layout level (showHero includes this route), extending behind the sticky, transparent-on-hero-routes TopBar.
• Sub-tabs: Overview (only enabled tab) and Network (disabled, "Coming soon" — intentional, leave alone unless asked).
• 4 status cards: Total Resources, Healthy, Warnings, Critical — from api.listResources().
• Middle row: Resource Distribution (donut by integration type) + Node Status (4-col tile grid, one tile per resource — replaced an earlier world-map concept since a map doesn't make sense for a small/single-site setup).
• Bottom row: Integration Health list + Recent Activity (api.listEvents(4)).
• Card backgrounds use a cardDim + cardVignette (radial-gradient, closest-side keyword — a fixed % leaves a visible hard edge on straight sides) combo on the middle row only, per explicit visual preference; bottom row stays plain/regular.

BookNest (/booknest)

• Hero banner reused at layout level with page-specific tuning (heroPaddingTop/heroObjectPosition lookup maps in App.tsx).
• Large 28px title + "Your Digital Library" subtitle (the one page using pageSubtitles), header grows to 72px.
• Page stats row (Links / Categories / Favorites) + "Delete All" bulk action.
• Main column: Quick Access (top 5 categories) + bookmark groups grid (4 cols, full CRUD with hover edit/delete/star).
• Right sidebar (spans both grid rows via gridRow: '1 / span 2'): Favorites, Recently Added (5 newest), Link Health donut, Category Breakdown donut.
• Add/edit bookmark modal supports auto-detected favicons via guessServiceIconUrl() or manual icon entry.
• All data from api.listBookmarks() / api.listBookmarkCategories() with real create/update/delete calls — no local-only state.

Terminal (/terminal)

• Left sidebar: SSH hosts (integrations of type ssh), click to connect.
• Tab bar + 1/2/4-pane split layout, each pane an independent xterm instance.
• Sessions persist across in-app navigation: the xterm instances + WebSockets are owned by src/lib/TerminalSessionContext.tsx (mounted above the router), and their DOM nodes are re-parented into the page on mount / moved to a hidden root on unmount rather than disposed. Closing a tab/pane or logging out tears a session down; a full browser reload still drops them. (Self-hosted caps the grid at 4 panes; "as many as fit" is a paid-tier roadmap item.)
• Preferences panel (theme: ArchNest Dark/Matrix/Solarized/Midnight Blue, font size 11-16px, font family) — stored in localStorage (archnest-terminal-prefs), not synced server-side.
• WebSocket to /api/terminal: connect/input/resize/list_tmux/disconnect messages; supports attaching to an existing tmux session or starting a new one.
• Certificate auth (OPKSSH) shells out to the system ssh binary under a pty rather than using the JS SSH client.
• Session logging to ARCHNEST_SESSION_LOG_DIR is backend-supported but has no dedicated viewer UI yet.

Tunnels (/tunnels)

• List + create form for local/remote/dynamic (SOCKS5) SSH tunnels.
• Create form fields conditionally show/hide based on mode (no endpoint host/port fields for dynamic mode).
• Status color map: stopped #7A7D85, connecting #C8A434, retrying #E0A030, connected #2ECC71, error #E74C3C. Polls every 3s.
• Backed by api.listTunnels()/createTunnel()/connectTunnel()/disconnectTunnel()/deleteTunnel().

Files (/files)

• SSH host selector + breadcrumb-navigable SFTP directory browser.
• File editor modal: plain textarea, files up to 50MB (anything larger is download-only). Heuristic binary detection (null bytes/control chars) decides base64 vs. text encoding.
• Inline directory creation, rename, delete, upload, download.
• Host-to-host transfer modal: pick source file + destination host/path, copy-or-move toggle, live progress bar fed by api.getTransfer(id) polling.

Containers (/containers)

• Host selector spans three sources: Docker Engine TCP API (integrations of type docker), Docker-over-SSH (integrations of type ssh, runs the docker CLI on the host), and read-only push agents (hosts that POST reports).
• Intra-page tabs: tab 1 is the container spreadsheet (Name/Image/State/CPU/Memory/Ports/Actions); clicking a container name opens a closeable per-container detail tab (overview/state+health/stats/ports/ networks/mounts/env-with-secrets-masked/labels). Detail is richest for agent hosts (full docker inspect); docker/ssh sources degrade gracefully.
• Per-container state badge (running/paused/exited/dead) with context-aware action buttons (Start/Stop/Restart/Pause/Unpause/Remove) — buttons disable themselves for invalid transitions. Agent rows are read-only (no actions).
• Live CPU/memory stats: polled for Docker-API running containers; embedded in the report for agent hosts; not available for the SSH list view.
• Logs modal (configurable tail) and exec modal (interactive shell) for docker/ssh sources, via /api/docker/exec (base64-framed) or /api/docker-ssh/exec (plain UTF-8). See docs/docker-agent-monitoring.md.

Remote Desktop (/remote-desktop)

• Left sidebar: hosts from integrations of type remote_desktop.
• Main area is a Guacamole canvas tunneled over WebSocket to /api/guacamole, proxying to the guacd sidecar container (RDP/VNC/Telnet).
• Requires ARCHNEST_GUAC_CRYPT_KEY — sessions fail without it (the backend warns on startup if it's missing).

Host Metrics (/host-metrics)

• Left sidebar: SSH hosts. Selecting one starts a 5-second polling loop against api.getHostMetrics(integrationId), cleared on deselect.
• Cards: CPU/Memory/Disk gauges (color thresholds: green <75%, yellow 75-90%, red ≥90%) + Uptime, then Network Interfaces, Processes (top 10), Listening Ports, Firewall Rules (UFW/iptables), Login Activity.
• Backed by 10 sequential SSH-exec collectors under backend/src/ssh/metrics/ (cpu, memory, disk, uptime, network, system, processes, ports, firewall, login-stats) — sequential on purpose, to avoid exceeding OpenSSH's MaxSessions limit per host.

Settings (/settings)

• Fixed 200px left nav, 7 sections: Profile, Appearance, Security, Integrations, Notifications, Data & Backup, About. URL-deep-linkable via ?tab= (useSearchParams) — use this pattern for any future section.
• Profile: display name, email, avatar upload (FileReader.readAsDataURL → base64 data URL, persisted via api.updateMe() — this one is a real backend round-trip, unlike the rest of the page below).
• Appearance: accent color swatches — local-state only, doesn't persist or apply anywhere (see Known Stubs in HANDOFF.md).
• Security: password-change form + 2FA toggle — currently placeholder UI pending the Phase 2 auth work in HANDOFF.md.
• Integrations: one card per type (Proxmox/Docker/NetBird/Cloudflare/AWS/ Uptime Kuma/Weather/Remote Desktop/SSH), each with type-specific fields (secrets masked, eye-toggle to reveal, "Test Connection" button). Real CRUD via api.createIntegration()/updateIntegration()/deleteIntegration()/testIntegration().
• Notifications: toggles — placeholder, no delivery mechanism (see Known Stubs in HANDOFF.md).
• Data & Backup: full JSON export/import of integrations + secrets + bookmarks + tunnels via backend/src/routes/data.ts — this is the one endpoint that intentionally round-trips decrypted secrets, by design, for backup portability.
• About: static version/license/links info.

Help (/help)

• Fully static — no backend calls. 11 guide cards (one per real page) with a short description and tips. Update this page whenever a new page ships.

Login (/login) / Enrollment (/enrollment)

• Login.tsx: username/password form → api.login() → AuthContext.
• Enrollment.tsx: two-step first-run flow — (1) create the admin account via api.setup(), gated to only work while the users table is empty; (2) optional "Connect Your Services" integration onboarding grid (skippable, same integration form as Settings). Routed to based on GET /api/system/setup-status.

---

Backend Architecture (current, not aspirational)

• backend/ — Fastify 5 + TypeScript (ESM, tsx dev / tsc -b build), better-sqlite3 for storage, deployed as its own Docker container alongside the frontend and a guacd sidecar.
• Auth: JWT (@fastify/jwt) with server-tracked sessions and a multi-user schema (admin/member roles, 10-seat cap). Authentik SSO is deferred to a paid AWS add-on — see ROADMAP.md.
• Integration credentials split across integrations (non-secret config) and secrets (AES-256-GCM-encrypted, keyed by ARCHNEST_SECRET_KEY) tables — secrets never appear in a generic "list integrations" response by construction, not by remembering to redact a field.
• Every integration type has an adapter in backend/src/integrations/ implementing testConnection() (required) and listResources() (optional); registry.ts maps IntegrationType → adapter. All 9 types (proxmox/docker/netbird/cloudflare/aws/uptime_kuma/weather/ssh/remote_desktop) are real, working adapters — none are stubs anymore.
• backend/src/ssh/ is the shared SSH transport layer powering Terminal, Files, Tunnels, Transfers, and Host Metrics: connect.ts (jump-host chaining, host-key verification, cert auth), sftp.ts (ephemeral SFTP), transfer.ts (host-to-host streamed copy/move with progress + cancel), docker.ts (runs the docker CLI over SSH for the Containers page — injection-safe ref validation), and metrics/ (the 10 collectors listed above).
• Docker container data has three transports: backend/src/docker/ + routes/docker.ts (Engine TCP API), ssh/docker.ts + routes/dockerSsh.ts (CLI over SSH), and routes/agents.ts (token-gated push-agent ingest into the docker_agent_reports table, read-only). See docs/docker-agent-monitoring.md.
• Vite dev server proxies /api → http://localhost:4000; prod routes /api to the backend container via Nginx Proxy Manager.

Future Integration Notes

• AWS/Cloudflare/NetBird/Proxmox/Uptime Kuma adapters are real but currently surface basic resource inventory + health only — deeper cost/pricing/budget data (mentioned in the old blueprint) is not implemented and not currently planned; revisit only if explicitly requested.
• Mesh prerequisite gate (require a verified NetBird mesh before the app can be configured) is designed in docs/mesh-prerequisite-gate.md but not built — it has open decisions pending user sign-off, and must default OFF so it can't lock the live instance.