ASTRO Tech and more

11/6/2025 · Witness in the Machine

Integration to Modern Web Infrastructure.

Astro Web Development: Technical Architecture

From Industrial Systems Integration to Modern Web Infrastructure

Project Structure

Astro is Project-Level, Not System-Level

Astro lives in your project directory, not as a system service:

~/Projects/my-astro-site/
├── node_modules/
│   └── astro/
│       └── dist/
│           └── content/
│               └── loaders/
├── src/
│   ├── pages/
│   ├── components/
│   └── layouts/
├── public/
├── astro.config.mjs
└── package.json

Key commands:

• npm run dev - Start development server (localhost:4321)
• npm run build - Compile to static files in dist/
• npm install - Install dependencies

The Build Pipeline

From Code to Production

Development Phase
├── npm run dev
├── Edit files in src/
└── Hot reload (instant preview)
    ↓
Build Phase
├── npm run build
├── Astro compiles everything
└── Creates dist/ folder
    ↓
Deployment Phase
├── Push to Git (GitHub/GitLab)
├── Cloudflare Pages auto-builds
└── Deploys to edge CDN
    ↓
Production
└── Static files served globally

WordPress vs Astro Comparison

Dependencies and Node Modules

What’s in node_modules/?

The node_modules/ folder contains all project dependencies:

node_modules/
├── astro/              # Framework core
├── react/              # For interactive islands
├── sharp/              # Image optimization
├── vite/               # Build tool (bundler)
├── remark-*/           # Markdown processing
├── rehype-*/           # HTML transformation
└── [hundreds more...]

Dependency Philosophy

Modern approach: Small, focused packages (Unix philosophy for JavaScript)

Industrial parallel:

• SCADA needs: PLC drivers, database connectors, visualization libraries
• Web needs: Framework, build tools, content processors, UI libraries

In package.json (what YOU specify):

{
  "dependencies": {
    "astro": "^5.0.0",
    "react": "^18.0.0"
  }
}

npm install pulls in:

• Direct dependencies (astro, react)
• Their dependencies
• Dependencies of dependencies
• Result: 500+ packages in node_modules/

Import Resolution

How Import Paths Work

import { glob } from 'astro/loaders';

Resolves to:

node_modules/astro/dist/content/loaders/glob.js

The loaders directory contains:

loaders/
├── glob.js       # Pattern-based file loading
├── glob.d.ts     # TypeScript definitions
├── file.js       # Individual file loading
├── file.d.ts
├── index.js      # Main exports
├── index.d.ts
├── types.js      # Type definitions
└── errors.js     # Error handling

File types:

• .js files = Actual executable code
• .d.ts files = TypeScript type definitions (for IDE autocomplete)

Data Structures and OOP Patterns

Astro Uses Typed Data Structures

// Define schema (like a class definition)
const blogCollection = defineCollection({
  loader: glob({ 
    pattern: '*.md', 
    base: './src/content/blog' 
  }),
  schema: z.object({
    title: z.string(),
    date: z.date(),
    author: z.string(),
  })
});

Data flow:

1. Loader scans filesystem
2. Parses frontmatter from markdown
3. Returns array of objects
4. Schema validates structure (Zod = runtime type checking)
5. Build system processes data
6. Pages query collection: const posts = await getCollection('blog')

C++ Equivalent

class BlogPost {
  string title;
  date publishDate;
  string author;
};

vector<BlogPost> posts = loader.loadPosts();

Same concept: strongly-typed data structures passed through a processing pipeline.

Edge Computing and IoT Architecture

The Parallel: Web Infrastructure = Industrial IoT

Industrial SCADA System:

Sensor (data source)
    ↓
PLC/Gateway (data acquisition)
    ↓
Validation/Filtering (data integrity)
    ↓
Processing (transformation)
    ↓
SCADA Edge Nodes (distributed monitoring)
    ↓
Central Dashboard (visualization)

Modern Web Stack (Astro + Cloudflare):

Content Source (markdown, API, CMS)
    ↓
Astro Loader (data acquisition)
    ↓
Schema Validation (data integrity)
    ↓
Build Process (transformation)
    ↓
Cloudflare Edge (distributed deployment)
    ↓
Browser (visualization)

Key Insight: Every IoT Device = Data Structure on Network

IoT Architecture:

• Device exposes API endpoint
• Returns JSON (data structure)
• Edge processes/validates
• Distributes to network

Web Architecture:

• Content source exposes data
• Loader returns structured data
• Build validates/transforms
• CDN distributes globally

Islands Architecture

Strategic Interactivity

Concept: Most of the page is static HTML, but specific components (“islands”) are interactive.

Static HTML (fast, cacheable)
    +
Interactive Islands (React/Vue/Svelte components)
    =
Optimal Performance

Example:

---
// Static at build time
const posts = await getCollection('blog');
---

<h1>Blog Posts</h1>
{posts.map(post => <article>{post.data.title}</article>)}

<!-- Interactive island -->
<Counter client:load />

Industrial parallel:

• Most infrastructure: Static, reliable, fast
• Sensors/actuators: Interactive, strategic placement
• Minimal overhead where not needed

Benefits

1. Performance: Ship minimal JavaScript
2. Reliability: Static = fewer failure points
3. Cost: Less compute needed
4. SEO: Full HTML available immediately

File System and Directory Structure

What You Work With

src/
├── pages/              # Routes (index.astro = homepage)
│   ├── index.astro
│   ├── about.astro
│   └── blog/
│       └── [slug].astro
├── components/         # Reusable UI pieces
│   ├── Header.astro
│   └── Footer.astro
├── layouts/           # Page templates
│   └── BaseLayout.astro
└── content/           # Content collections
    └── blog/
        ├── post-1.md
        └── post-2.md

public/                # Static assets (copied as-is)
├── images/
└── fonts/

astro.config.mjs       # Configuration
package.json           # Dependencies
tsconfig.json          # TypeScript settings

What You Ignore

node_modules/          # Dependencies (never edit)
dist/                  # Build output (generated)
.astro/               # Cache (generated)

Technical Advantages

Why Astro for Production

Performance:

• Pre-rendered HTML
• Minimal JavaScript shipped
• Edge CDN distribution
• Sub-second page loads

Security:

• No database
• No server-side code in production
• Static files only
• No plugin vulnerabilities

Reliability:

• No runtime dependencies
• Distributed edge network
• No database failures
• Predictable behavior

Developer Experience:

• Hot reload in development
• TypeScript support
• Component-based architecture
• Framework-agnostic (use React, Vue, Svelte, etc.)

Cost:

• Static hosting (cheap/free)
• No server maintenance
• Minimal compute needed

Build Process Details

What Happens During Build

1. File Discovery

   • Scans src/pages/ for routes
   • Loads content collections
   • Processes components

2. Content Loading

   • Loaders fetch data (filesystem, APIs, CMS)
   • Schema validation
   • Data transformation

3. Compilation

   • Astro components → HTML
   • CSS extraction and optimization
   • JavaScript bundling (minimal)
   • Image optimization

4. Output Generation

   • Creates dist/ folder
   • Static HTML files
   • Optimized assets
   • Sitemap, RSS, etc.

Build Output Example

dist/
├── index.html
├── about/
│   └── index.html
├── blog/
│   ├── post-1/
│   │   └── index.html
│   └── post-2/
│       └── index.html
├── _astro/
│   ├── styles.abc123.css
│   └── client.def456.js
└── images/
    └── hero.optimized.webp

Integration Points

Cloudflare Pages Deployment

Git-based workflow:

1. Push code to GitHub
2. Cloudflare detects push
3. Runs npm run build
4. Deploys dist/ to edge network
5. Live in ~30 seconds

Environment variables:

• Set in Cloudflare dashboard
• Available during build
• For API keys, feature flags, etc.

Content Sources

Astro can load content from:

• Local files: Markdown, JSON, YAML
• APIs: REST, GraphQL
• CMS: Contentful, Sanity, WordPress (headless)
• Databases: At build time

System Comparison: Industrial → Web

Key Takeaways

1. Astro is project-based, not system-level
2. Dependencies are libraries - modern web uses many small packages
3. Build pipeline transforms source → static output
4. Data structures flow through typed schemas
5. Edge deployment = distributed, reliable infrastructure
6. Islands architecture = strategic interactivity
7. Same engineering principles as industrial systems integration

Resources

• Astro Documentation: https://docs.astro.build
• Loaders location: node_modules/astro/dist/content/loaders/
• Package manager: npm (Node Package Manager)
• Build tool: Vite (fast, modern bundler)
• Deployment: Cloudflare Pages, Netlify, Vercel

Quick Command Reference

# Create new Astro project
npm create astro@latest

# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Find Astro installation
find ~ -name "astro.config.mjs"

# View loaders
ls node_modules/astro/dist/content/loaders/