ArgoBox
ArgoBox AI + Infrastructure + Labs
Ctrl+K
Site Architecture

Layouts & Components

ArgoBox layout system, component library, and design system documentation

February 23, 2026

Layouts & Components

ArgoBox uses four layouts and dozens of components organized by feature domain. The design system is built around a space/cosmic theme with glassmorphism effects, CSS custom properties for theming, and consistent patterns across all pages.

Layouts

Every page uses one of four layouts. The layout wraps the page content and provides common elements like the <head>, navigation, footer, and scripts.

BaseLayout

The standard layout for all public-facing pages.

<BaseLayout title="Page Title" description="SEO description">
  <slot />
</BaseLayout>

Includes:

  • <head> with SEO meta tags, Open Graph, Twitter cards
  • <ViewTransitions /> for client-side navigation
  • Header with site navigation
  • Footer with links and copyright
  • Font loading (Space Grotesk, JetBrains Mono)
  • Global CSS and Tailwind

Used by: Homepage, blog, journal, docs, about, contact, projects, resources, status, all public pages.

CosmicLayout

The admin/dashboard layout with the space-themed visual identity.

<CosmicLayout title="Admin" sidebar={true}>
  <slot />
</CosmicLayout>

Includes:

  • Everything from BaseLayout
  • Animated starfield background canvas
  • Nebula gradient overlays
  • AdminSidebar navigation (collapsible)
  • AdminModeIndicator (top bar showing current role)
  • NotificationSystem (toast notifications)
  • CommandPalette (Ctrl+K search)

Used by: All /admin/*, /command/*, /dashboard, /user/* pages.

The starfield is a <canvas> element with a JavaScript animation rendering parallax stars. The nebula gradients are CSS radial gradients with subtle animation. Together they create the immersive cosmic aesthetic without heavy GPU load.

BlogPost

Article layout for blog posts and journal entries.

<BlogPost frontmatter={post.data}>
  <Content />
</BlogPost>

Includes:

  • BaseLayout wrapper
  • Article header (title, date, reading time, tags)
  • Table of contents sidebar (auto-generated from headings)
  • Prose styling via @tailwindcss/typography
  • Previous/next post navigation
  • Related posts section

Used by: /blog/[slug], /journal/[...slug], /posts/[slug].

Note: BlogPost.astro does not currently exist in the codebase. Blog and journal pages use BaseLayout directly with prose styling applied inline.

MinimalLayout

A bare-bones wrapper for pages that need minimal chrome.

<MinimalLayout title="Login">
  <slot />
</MinimalLayout>

Includes:

  • Basic <head> with meta tags
  • <ViewTransitions />
  • No header, no footer, no navigation

Used by: /auth/login, /auth/logout, error pages, embed views.

Component Directories

Components are organized by feature domain in src/components/:

src/components/
├── admin/           # Admin panel components
├── chat/            # AI chat interface components
├── command/         # Command center widgets
├── dashboard/
│   └── widgets/     # Dashboard widget components
├── homelab/         # Homelab page components
├── labs/            # Playground/lab components
├── pentest/         # Security challenge components
├── space/           # Cosmic theme components (starfield, nebula)
├── status/          # Status page components
├── ui/              # Shared UI primitives
├── user/            # User portal components
├── build-swarm/     # Build swarm monitoring components
├── Header.astro     # Site header
├── Footer.astro     # Site footer
├── SEO.astro        # SEO meta tag component
├── PostCard.astro   # Blog post card
└── ...

Key Components

Terminal.astro

A typing animation component that simulates terminal output. Used on the homepage and various pages for visual effect.

<Terminal
  commands={[
    '$ ssh argo@argobox-lite',
    'Welcome to argobox-lite (10.0.0.199)',
    '$ docker ps --format "table {{.Names}}\t{{.Status}}"',
    'gitea          Up 14 days',
    'vaultwarden    Up 14 days',
    'openwebui      Up 3 days',
  ]}
  typingSpeed={40}
  lineDelay={800}
/>

The component renders a styled terminal window with a typing animation that plays through the provided command array. Each line appears character-by-character with configurable speed and delay between lines.

KnowledgeGraph.astro

An interactive knowledge graph visualization powered by Cytoscape.js. Renders nodes and edges representing relationships between concepts, technologies, and systems.

<KnowledgeGraph
  nodes={graphData.nodes}
  edges={graphData.edges}
  layout="cose"
/>

The component initializes a Cytoscape instance in a container div, applies the cosmic theme styling (cyan nodes, purple edges, dark background), and supports pan/zoom/click interactions. Graph data comes from the @argobox/tendril-graph local package.

Header & Footer

Standard site navigation components used by BaseLayout.

Header (src/components/Header.astro) features:

  • Logo + site name + subtitle "AI + Infrastructure + Labs" (links to /)
  • 8 navigation items: Blog, Journal, Projects, Docs, Infrastructure (dropdown with 6 items), Playground, Ask, More (dropdown with 8 items)
  • Infrastructure dropdown: Home Lab, Architecture, Cost Analysis, Workflows, Command Center, System Status
  • More dropdown: About, Toolkit, Modules, For Developers, For Employers, Community, Resources, Contact — each with FontAwesome icon and description
  • Search dropdown (magnifying glass icon) — fuzzy search over /search-index.json
  • UserMenu component (shows login/profile based on auth state)
  • Mobile hamburger menu (below 768px) with slide-down animation
  • Cost Analysis prewarm: on admin/command pages, the header pre-fetches /api/swarm/status and /api/swarm/nodes into localStorage on a 25-second interval so the Cost Analysis page loads instantly

Header CSS details:

  • .logo-container uses flex-shrink: 0 to prevent compression when nav fills the row
  • .site-subtitle uses white-space: nowrap to prevent wrapping into nav items
  • .nav-list uses gap: 0.25rem (items have internal padding of 0.5rem)
  • .main-nav has margin-left: 1.5rem for a fixed gap from the logo
  • At 1024px breakpoint: logo shrinks to 36px, nav font reduces to 0.8125rem
  • At 768px breakpoint: nav becomes a full-width dropdown menu below the header

Footer features:

  • Site links organized in columns
  • Social links (GitHub, etc.)
  • Copyright with current year
  • "Built with Astro" attribution

PostCard.astro

Blog post preview card used on the blog index, homepage featured posts, and related posts sections.

<PostCard
  title={post.data.title}
  description={post.data.description}
  pubDate={post.data.pubDate}
  slug={post.slug}
  tags={post.data.tags}
  heroImage={post.data.heroImage}
/>

Renders a card with the post title, excerpt, date, tags, and optional hero image. Uses glassmorphism styling with hover effects.

SEO.astro

Centralized SEO meta tag component included in all layouts.

<SEO
  title="Page Title"
  description="Page description for search engines"
  image="/images/og-default.png"
  type="article"
  publishDate={pubDate}
/>

Generates <title>, <meta> description, Open Graph tags, Twitter card tags, canonical URL, and JSON-LD structured data.

StatusPanel.astro

Real-time service status panel showing health checks for all monitored services.

<StatusPanel services={serviceList} refreshInterval={30000} />

Fetches service health data from /api/cache/status and displays green/yellow/red indicators with response times. Auto-refreshes on a configurable interval.

Admin Components

AdminSidebar

Collapsible sidebar navigation for the admin panel. Groups routes into sections (Content, AI, Tools, Infrastructure, System) with section headers and active route highlighting.

Desktop behavior: Fixed sidebar at 220px width. Collapse toggle (Ctrl+\) shrinks it to 56px with icon-only links and hover tooltips. Collapse state persists in localStorage.

Mobile behavior (below 768px): Sidebar is hidden off-screen (transform: translateX(-100%)). A hamburger button (#adminMobileMenuBtn) in the top-left opens it as a full-height overlay with a backdrop. Tapping a nav link or the backdrop closes it. The hamburger button, backdrop, and toggle JS are all in CosmicLayout.astro.

Scrollable navigation: The .sidebar-nav section uses overflow-y: auto with a thin custom scrollbar (4px, dark theme). With 18+ nav items and group headers, the nav scrolls when content exceeds viewport height. The header and footer remain pinned.

Customization: Nav items support user preferences (reordering, grouping, hiding) via resolveGroupedNav() from src/lib/user-preferences.ts. If no customization is set, items render as a flat list.

CommandPalette

Keyboard-triggered command palette (Ctrl+K or Cmd+K) that provides fuzzy search across:

  • All admin pages
  • Content entries (posts, journal, docs)
  • Quick actions (purge cache, trigger deploy, etc.)
  • API endpoints

Built as a modal overlay with a search input, filtered result list, and keyboard navigation (arrow keys + Enter). Results are ranked by fuzzy match score.

NotificationSystem

Toast notification system for real-time feedback in the admin panel. Supports four notification types:

Type Color Use Case
success Green (--nebula-green) Action completed successfully
error Rose (--nebula-rose) Action failed
warning Amber (--nebula-amber) Action completed with warnings
info Cyan (--nebula-cyan) Informational message

Notifications stack in the bottom-right corner, auto-dismiss after 5 seconds (configurable), and can be manually dismissed.

AdminModeIndicator

A thin bar at the top of the admin layout showing the current user's role and email. Color-coded by role:

Role Indicator Color
admin Cyan (--nebula-cyan)
member Purple (--nebula-purple)
demo Amber (--nebula-amber)

In dev mode, shows "DEV MODE" with a distinctive orange indicator.

Lab Components

LabLauncher

Entry point component for playground labs. Shows available labs as cards with descriptions, difficulty levels, and launch buttons.

TerminalEmbed

Embedded terminal component using xterm.js for browser-based terminal sessions. Used in the terminal playground, remote console, and pentest console features. Supports fullscreen mode via button, double-click on terminal, or Fullscreen API. Chrome bar auto-hides in fullscreen and reappears on hover. The terminal refits automatically on fullscreen transitions and viewport resize. On mobile (≤768px), the fullscreen button gets a prominent label and the terminal height is responsive via clamp().

<TerminalEmbed sessionId="abc123" containerId={0} />

VNCEmbed

VNC viewer component for remote desktop access to VMs via noVNC. Used in the Proxmox console proxy feature. Supports fullscreen mode via button, double-click, F11 key, or Fullscreen API. Chrome bar auto-hides in fullscreen. noVNC viewport rescales on fullscreen/resize transitions via ResizeObserver. On mobile (≤768px), the fullscreen button gets a prominent amber label and the VNC screen height is responsive via clamp().

See Mobile Responsiveness for the complete mobile design system including breakpoints, grid patterns, and touch target requirements.

ChallengeTracker

Progress tracking component for CTF and pentest challenges. Shows completed/remaining challenges, score, and time elapsed.

DocumentationPanel

Side panel component that displays contextual documentation alongside lab environments. Supports Markdown rendering and step-by-step instructions.

SessionBar

Top bar in lab environments showing session info: lab name, time remaining, connected user, and action buttons (reset, save, exit).

LabBubble

Floating indicator showing active lab session status. Appears in the bottom corner when a lab session is running, showing elapsed time and a quick-return link.

Design System

CSS Custom Properties

The design system is built on CSS custom properties for consistent theming:

:root {
  /* Primary palette */
  --nebula-cyan: #06b6d4;
  --nebula-purple: #8b5cf6;
  --nebula-amber: #f59e0b;
  --nebula-rose: #f43f5e;
  --nebula-green: #10b981;

  /* Glass effects */
  --glass-bg: rgba(15, 23, 42, 0.8);
  --glass-border: rgba(148, 163, 184, 0.1);
  --glass-hover: rgba(148, 163, 184, 0.15);
  --glass-blur: 12px;

  /* Spacing and sizing */
  --sidebar-width: 220px;
  --sidebar-collapsed: 56px;
  --header-height: 64px;
  --content-max-width: 1200px;
}

Glassmorphism Pattern

The signature visual pattern across the site:

.glass-panel {
  background: var(--glass-bg);
  backdrop-filter: blur(var(--glass-blur));
  border: 1px solid var(--glass-border);
  border-radius: 12px;
}

.glass-panel:hover {
  border-color: var(--glass-hover);
}

This pattern is applied to cards, panels, modals, dropdowns, and interactive surfaces throughout the site. The semi-transparent background with backdrop blur creates depth while maintaining readability.

Space Theme Elements

  • Starfield -- Canvas-rendered parallax stars in CosmicLayout
  • Nebula gradients -- Radial CSS gradients with slow animation
  • Glow effects -- Box shadows using palette colors with low opacity
  • Cosmic typography -- Space Grotesk for the space-age feel
  • Monospace accents -- JetBrains Mono for technical elements
layoutscomponentsdesign-systemuiastro