Tech Stack

Arcturus-Prime is built on Astro 5.17 with a hybrid rendering model, Tailwind CSS for styling, TypeScript throughout, and a constellation of dependencies for everything from terminal emulation to AI chat. This page documents every layer of the stack.

Framework: Astro 5.17+

Astro is the core framework. It delivers zero JavaScript to the client by default, hydrating interactive components only where explicitly requested. Arcturus-Prime uses Astro’s hybrid rendering model:

• SSG (Static Site Generation) is the default. Pages export prerender = true and are built to static HTML at build time.
• SSR (Server-Side Rendering) is enabled per-route by omitting the prerender export. These pages run as Cloudflare Workers on every request.

// Static page (built at compile time)
export const prerender = true;

// SSR page (runs on every request)
// Just don't export prerender, or set it to false
export const prerender = false;

About 81 pages are statically prerendered and 49 are server-rendered. Static pages serve instantly from the CDN. SSR pages have access to environment variables, KV bindings, and request headers.

Adapter: @astrojs/cloudflare 12.x

The Cloudflare adapter translates Astro’s SSR output into Cloudflare Workers format. It bundles all server-rendered pages and API routes into a single _worker.js deployed alongside the static assets.

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    platformProxy: {
      enabled: true,  // Enable local dev proxy for KV, D1, etc.
    },
  }),
});

The platformProxy option spins up a local miniflare instance during development so KV and other Cloudflare bindings work locally.

Styling: Tailwind CSS 3.4.17

Tailwind CSS provides utility-first styling with a custom configuration extending the default theme for Arcturus-Prime’s space-themed design system.

# Tailwind + typography plugin
tailwindcss: 3.4.17
@tailwindcss/typography: latest

The @tailwindcss/typography plugin handles prose styling for rendered Markdown content (blog posts, journal entries, documentation pages). It provides sensible defaults for headings, paragraphs, code blocks, tables, and lists within content.

Design System: CSS Custom Properties

The visual identity uses CSS custom properties for theming, enabling the space/cosmic aesthetic throughout the site:

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

  --glass-bg: rgba(15, 23, 42, 0.8);
  --glass-border: rgba(148, 163, 184, 0.1);
  --glass-hover: rgba(148, 163, 184, 0.15);
}

Glassmorphism effects (backdrop blur, semi-transparent backgrounds, subtle borders) are used extensively in the admin panel, command center, and cosmic layout. The variables are consumed by both Tailwind utilities and custom CSS.

Language: TypeScript

TypeScript is used throughout the project — Astro pages, API routes, utility libraries, and client-side scripts. The tsconfig.json extends Astro’s strict preset:

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"],
      "@lib/*": ["src/lib/*"]
    }
  }
}

Path aliases (@/, @components/, @layouts/, @lib/) are configured for clean imports throughout the codebase.

Content: MDX + Shiki

Content is authored in Markdown and MDX. Astro’s built-in content collections parse frontmatter with Zod schemas and render content with configurable plugins.

Syntax Highlighting

Code blocks are highlighted at build time using Shiki with the one-dark-pro theme:

// astro.config.mjs
export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: 'one-dark-pro',
      wrap: true,
    },
  },
});

Shiki renders syntax highlighting as inline styles at build time, so there is zero runtime JavaScript for code highlighting. The one-dark-pro theme matches the site’s dark aesthetic.

MDX Support

MDX extends Markdown with JSX component support. This allows embedding interactive Astro components directly in content files:

---
title: "Some Post"
---

import Terminal from '@components/Terminal.astro';

Here is a terminal demo:

<Terminal commands={['ls -la', 'cat /etc/hostname']} />

Fonts: Self-Hosted

Two font families are self-hosted (no external CDN calls):

Font	Usage	Weight Range
Space Grotesk	Body text, headings, UI (sans-serif)	300-700
JetBrains Mono	Code blocks, terminal, monospace UI elements	400-700

Font files live in public/fonts/ and are loaded via @font-face declarations. Self-hosting eliminates the Google Fonts dependency and the associated privacy/performance concerns.

@font-face {
  font-family: 'Space Grotesk';
  src: url('/fonts/SpaceGrotesk-Variable.woff2') format('woff2');
  font-weight: 300 700;
  font-display: swap;
}

@font-face {
  font-family: 'JetBrains Mono';
  src: url('/fonts/JetBrainsMono-Variable.woff2') format('woff2');
  font-weight: 400 700;
  font-display: swap;
}

Client-Side Navigation: ViewTransitions

Astro’s <ViewTransitions /> component is included in both BaseLayout.astro and CosmicLayout.astro, enabling client-side navigation with animated page transitions. This means the site behaves like an SPA after the initial load — clicking links does not trigger a full page reload.

Critical: astro:page-load vs DOMContentLoaded

This is the single most important thing to know when writing client-side scripts for Arcturus-Prime:

// WRONG -- only fires on initial full page load
document.addEventListener('DOMContentLoaded', () => { init(); });

// CORRECT -- fires on initial load AND client-side navigations
document.addEventListener('astro:page-load', () => { init(); });

DOMContentLoaded only fires once — on the initial full page load. When a user navigates via a client-side link (which ViewTransitions handles), DOMContentLoaded does not fire again. The astro:page-load event fires on both the initial load and every subsequent client-side navigation.

This applies to all <script> tags, <script is:inline> tags, and <script define:vars> tags in pages, components, and layouts. Every interactive feature on the site uses astro:page-load.

Local Packages

Two local workspace packages are used:

@argonaut/core

The Argonaut system’s core library. Contains shared types, utilities, and logic for the Argonaut AI agent framework. This package is excluded from the SSR bundle (vite.ssr.external) because it has Node.js-specific dependencies that do not run in Workers.

@tendril/graph

Graph data structures and algorithms used by the Knowledge Graph feature. Provides the data model that feeds into the Cytoscape.js visualization on the knowledge graph page.

Key Dependencies

Visualization & UI

Package	Version	Purpose
cytoscape	latest	Interactive knowledge graph visualization
xterm	latest	Terminal emulator for browser-based terminal components
marked	latest	Markdown parsing for dynamic content rendering

AI & Machine Learning

Package	Version	Purpose
openai	latest	OpenRouter and OpenAI API client for AI chat
@google/generative-ai	latest	Google Gemini API client

These power the multi-provider AI chat interface in the admin panel. OpenRouter provides access to multiple model providers (Anthropic, OpenAI, Meta, etc.) through a single API.

Communication

Package	Version	Purpose
nodemailer	latest	SMTP email sending (dev/fallback)
resend	latest	Transactional email API (production)

The contact form and notification system use Resend in production for reliable email delivery. Nodemailer serves as a development fallback.

Database

Package	Version	Purpose
better-sqlite3	latest	Local SQLite database for development

Used only in local development for content indexing and caching. In production, all state lives in Cloudflare KV. This package is excluded from the SSR bundle.

Astro Integrations

Package	Purpose
@astrojs/cloudflare	Cloudflare Pages adapter
@astrojs/mdx	MDX content support
@astrojs/sitemap	Automatic sitemap generation
@astrojs/rss	RSS feed generation

Build & Development

Commands

Command	Description
npm run dev	Start dev server on localhost:4321
npm run build	Production build to dist/
npm run preview	Preview production build locally
npm run astro check	TypeScript type checking

Build Output

The build produces:

dist/
├── _astro/          # Hashed static assets (CSS, JS, images)
├── _headers         # Cloudflare Pages headers file
├── _redirects       # Cloudflare Pages redirects
├── _worker.js       # SSR Worker bundle
├── blog/            # Static blog pages
├── docs/            # Static doc pages
├── ...              # All other static pages
└── index.html       # Homepage

Static pages are plain HTML files. The _worker.js file contains all SSR logic and runs as a Cloudflare Worker.

Development Environment

The local dev server runs on localhost:4321 with hot module replacement. The Cloudflare platform proxy provides local KV, D1, and other binding emulation so the full stack works locally without deploying.