Technical Documentation

Architecture Overview

The IOMARS website is built as a modern, static site with dynamic content management capabilities. The architecture leverages a JAMstack approach for optimal performance, security, and scalability.

Technology Stack

Frontend

Vite - Modern build tool providing fast development server and optimized production builds
Tailwind CSS - Utility-first CSS framework for responsive design with dark mode support
Vanilla JavaScript - Client-side interactivity without heavy framework overhead
Marked.js - Markdown to HTML conversion for dynamic content
Gray Matter - YAML frontmatter parsing for content metadata

Content Management

Decap CMS - Git-based content management system (formerly Netlify CMS)
Netlify Identity - User authentication for CMS access
Git Gateway - Secure API access to GitHub repository
Markdown Files - Content stored as version-controlled markdown with YAML frontmatter

Build Process

The site uses a multi-stage build process that transforms content and generates static HTML:

build-news.js - Processes markdown files from content/news/, converts to HTML, and injects into news.html between marker comments
build-minutes.js - Generates meeting minutes archive from content/minutes/ with PDF links and summaries
build-certificates.js - Creates contest certificates display and dynamically generates summary section from metadata (contest_type, position, total_entries)
inject-solar.js - Injects live HF/VHF/UHF band conditions into index.html footer only
build-commits.js - Generates recent commit history for site transparency
Vite Build - Bundles JavaScript, processes CSS, optimizes assets, and generates production-ready files

Note: All build scripts use HTML comment markers (e.g., ) to identify injection points, allowing static HTML to be dynamically updated during builds.

Hosting & Deployment

Netlify Platform

The site is hosted on Netlify, which provides:

Continuous Deployment - Automatic builds triggered by Git commits to main/dev branches
Build Environment - Node.js environment executes prebuild scripts and Vite build process
Edge Functions - Serverless functions for API proxying (e.g., HamQSL solar data)
Form Handling - Native form processing for contact and membership forms
Identity Service - Authentication provider for CMS access
Git Gateway - Secure API for CMS to commit content changes to GitHub
Deploy Previews - Automatic preview deployments for pull requests

Cloudflare CDN

Cloudflare sits in front of Netlify, providing:

Global CDN - Content cached across 300+ edge locations worldwide for fast delivery
DDoS Protection - Enterprise-grade protection against distributed denial of service attacks
SSL/TLS - Automatic HTTPS with modern encryption protocols
Caching - Intelligent caching of static assets (HTML, CSS, JS, images) at the edge
DNS Management - Fast, reliable DNS resolution for iomars.im domain
HTTP/3 & QUIC - Modern protocols for faster page loads
Brotli Compression - Superior compression for faster transfers
Auto Minification - Automatic minification of HTML, CSS, and JavaScript

Content Delivery Flow

1

User Request

Visitor requests www.iomars.im from their browser

2

DNS Resolution

Cloudflare DNS resolves domain to nearest Cloudflare edge server

3

Edge Cache Check

Cloudflare checks if content is cached at the edge location

4

Cache Hit/Miss

Hit: Content served directly from edge (< 50ms)
Miss: Request forwarded to Netlify origin server

5

Origin Response

Netlify serves pre-built static HTML/CSS/JS from its CDN

6

Edge Caching

Cloudflare caches response at edge for subsequent requests

7

Delivery

Compressed, optimized content delivered to user's browser

Content Management Workflow

The Decap CMS provides a user-friendly interface for non-technical users to manage content:

1

Authentication

User logs in at /admin/ using Netlify Identity (email/password or OAuth)

2

Content Creation

User creates or edits content using rich text editor interface for News, Minutes, or Certificates

3

Media Upload

Images and PDFs uploaded directly through CMS interface to appropriate directories

4

Git Commit

CMS commits changes to GitHub via Git Gateway, creating markdown file with YAML frontmatter

5

Automatic Build

Netlify detects Git commit, triggers build process, and executes prebuild scripts

6

Deployment

New static site deployed to Netlify, Cloudflare cache invalidated, content live in ~2 minutes

Performance Optimizations

Static Generation

All HTML pre-rendered at build time
No server-side processing on each request
Instant page loads from CDN edge
Perfect Lighthouse scores achievable

Asset Optimization

Vite bundles and minifies JavaScript
Tailwind purges unused CSS classes
Cloudflare applies Brotli compression
HTTP/2 multiplexing for parallel downloads

Caching Strategy

Static assets cached with long TTL
HTML cached at edge with revalidation
Browser caching via Cache-Control headers
Service worker potential for offline support

Edge Computing

Content served from nearest edge location
Reduced latency for global visitors
Edge functions for dynamic API data
No origin server overhead

Security Features

Static Site - No database or server-side code reduces attack surface
HTTPS Everywhere - All traffic encrypted with modern TLS protocols
Git-based CMS - All content changes version controlled and auditable
Netlify Identity - Secure authentication with 2FA support
Cloudflare WAF - Web Application Firewall blocks common attacks
DDoS Protection - Automatic mitigation of volumetric attacks
Content Security Policy - Headers prevent XSS and injection attacks
No User Data Storage - Forms processed by Netlify, no database exposure

Repository Structure

IOMARS/
├── public/                      # Static assets
│   ├── admin/                   # Decap CMS configuration
│   │   └── config.yml          # CMS collections and fields
│   ├── certs/                  # Contest certificate PDFs
│   ├── images/                 # Site images
│   │   └── news/              # News article images
│   └── media/                  # Banner images
├── content/                    # Markdown content
│   ├── news/                  # News articles
│   ├── minutes/               # Meeting minutes
│   └── certificates/          # Contest certificates
├── src/                       # Source files
│   ├── main.js               # JavaScript entry point
│   ├── style.css             # Global styles
│   ├── themes.css            # Theme definitions
│   └── footer.js             # Footer component
├── *.html                     # Page templates
├── build-news.js             # News builder
├── build-minutes.js          # Minutes builder
├── build-certificates.js     # Certificates builder
├── inject-solar.js           # Solar conditions injector
├── build-commits.js          # Commit history builder
├── vite.config.js            # Vite configuration
├── tailwind.config.js        # Tailwind configuration
├── netlify.toml              # Netlify build settings
└── package.json              # Dependencies and scripts