Architecture Overview

**Referenced Files in This Document** - [worker.js](file://worker.js) - [.eleventy.js](file://.eleventy.js) - [cloudflare-pages.toml](file://cloudflare-pages.toml) - [wrangler.jsonc](file://wrangler.jsonc) - [package.json](file://package.json) - [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk) - [src/assets/js/main.js](file://src/assets/js/main.js) - [src/assets/css/main.css](file://src/assets/css/main.css) - [src/assets/js/modules/navigation.js](file://src/assets/js/modules/navigation.js) - [src/assets/js/modules/theme-toggling.js](file://src/assets/js/modules/theme-toggling.js) - [src/assets/js/modules/carousel-system.js](file://src/assets/js/modules/carousel-system.js) - [src/_data/site.json](file://src/_data/site.json) - [src/_data/polling.js](file://src/_data/polling.js) - [src/admin/config.yml](file://src/admin/config.yml) - [tina/config.ts](file://tina/config.ts)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Security and Compliance
  9. Deployment Topology
  10. Troubleshooting Guide
  11. Conclusion

Introduction

This document describes the architecture of the Ace Strategies Prime platform, focusing on the integration between static site generation and serverless computing. The system uses Eleventy to generate a static site from Markdown and Nunjucks templates, then serves it via Cloudflare Workers and Workers for Platforms (WFP) Assets. Dynamic functionality—member authentication, API endpoints, and CMS integration—is handled by a single Cloudflare Worker script. The frontend JavaScript modules manage interactive UI features, while CSS is organized into modular stylesheets for maintainability.

Project Structure

The repository is organized around three primary layers:

  • Static site generation with Eleventy (templates, data, and passthrough copies)
  • Frontend assets (CSS and modular JS)
  • Cloudflare Worker for dynamic routes and asset proxying
graph TB
subgraph "Static Generation"
ELE[".eleventy.js"]
TPL["Nunjucks Templates<br/>layouts, includes, macros"]
DATA["_data files<br/>site.json, polling.js, JSON collections"]
ASSET_PASSTHROUGH["Passthrough Copy<br/>assets, admin, redirects"]
end
subgraph "Build Output"
SITE["_site (static)"]
end
subgraph "Cloudflare Runtime"
WRK["worker.js"]
WFP["Workers for Platforms Assets<br/>ASSETS binding"]
end
subgraph "Frontend"
LAYOUT["base.njk"]
CSS["main.css (imports modules)"]
JS_MAIN["main.js (imports modules)"]
JS_MODS["JS Modules<br/>navigation, theme, carousels"]
end
ELE --> TPL
ELE --> DATA
ELE --> ASSET_PASSTHROUGH
ELE --> SITE
WRK --> WFP
WFP --> SITE
LAYOUT --> CSS
LAYOUT --> JS_MAIN
JS_MAIN --> JS_MODS

Diagram sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [worker.js:1-321](file://worker.js#L1-L321)
  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [src/assets/js/main.js:1-37](file://src/assets/js/main.js#L1-L37)

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [worker.js:1-321](file://worker.js#L1-L321)
  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [src/assets/js/main.js:1-37](file://src/assets/js/main.js#L1-L37)

Core Components

  • Static site generator (Eleventy)
    • Passthrough copying for assets and admin
    • Watch targets for efficient development
    • Shortcodes and filters for templating
    • Collections for content types
    • Transforms for Obsidian syntax and HTML minification
  • Cloudflare Worker
    • Member authentication (magic-link login, session verification, logout)
    • API endpoints (polling data, GitHub OAuth for CMS)
    • Asset proxying via Workers for Platforms
  • Frontend
    • Modular CSS architecture
    • Modular JavaScript modules for UI interactions
    • Nunjucks layout with SEO metadata and structured data

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [worker.js:1-321](file://worker.js#L1-L321)
  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [src/assets/js/main.js:1-37](file://src/assets/js/main.js#L1-L37)

Architecture Overview

The platform follows a hybrid static/dynamic model:

  • Static content is generated during build and served from Cloudflare’s edge via Workers for Platforms.
  • Dynamic routes (authentication, API) are handled by the Worker, which also proxies static assets when appropriate.
  • The CMS integrates via GitHub OAuth endpoints exposed by the Worker, enabling secure editor sessions.
graph TB
CLIENT["Browser"]
CF["Cloudflare Edge"]
WRK["worker.js"]
WFP["Workers for Platforms Assets<br/>ASSETS"]
ELE["Eleventy Build<br/>_site output"]
KV["KV Namespaces<br/>MEMBER_EMAILS, MAGIC_TOKENS"]
RES["Resend API"]
GH["GitHub OAuth API"]
SHEETS["Google Sheets API"]
CLIENT --> CF
CF --> WRK
WRK --> KV
WRK --> RES
WRK --> GH
WRK --> SHEETS
WRK --> WFP
WFP --> ELE
ELE --> WFP

Diagram sources

  • [worker.js:1-321](file://worker.js#L1-L321)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)

Detailed Component Analysis

Cloudflare Worker: Member Authentication and APIs

The Worker implements:

  • Session management with signed cookies and HMAC verification
  • Magic-link login flow with token storage in KV
  • Logout clearing session cookies
  • Polling API proxying Google Sheets data with caching headers
  • GitHub OAuth endpoints for Sveltia/Tina CMS integration
sequenceDiagram
participant U as "User Browser"
participant W as "worker.js"
participant K as "KV : MEMBER_EMAILS"
participant T as "KV : MAGIC_TOKENS"
participant R as "Resend API"
U->>W : POST /alliance/login/ {email}
W->>K : Lookup member : <email>
W->>T : Put token : <hex> -> email (TTL)
W->>R : Send magic-link email
W-->>U : Redirect to /alliance/login?sent=1
U->>W : GET /alliance/verify/?token=<hex>
W->>T : Get token : <hex>
W->>W : Verify token and sign session
W-->>U : 302 to /alliance/members/ with session cookie

Diagram sources

  • [worker.js:77-177](file://worker.js#L77-L177)

Section sources

  • [worker.js:1-321](file://worker.js#L1-L321)

Eleventy Static Site Generation Workflow

Eleventy orchestrates:

  • Passthrough copy for assets, admin, and redirects
  • Watch targets for CSS, JS, and data
  • Shortcodes and filters for templating
  • Collections for news, cases, newsletters, team, services, and knowledge
  • Transforms for Obsidian wiki links and callouts
  • Production HTML minification
flowchart TD
Start(["Build Start"]) --> Copy["Passthrough Copy<br/>assets, admin, redirects"]
Copy --> Watch["Watch Targets<br/>css, js, data"]
Watch --> Data["_data files<br/>site.json, polling.js, JSON"]
Data --> Tpl["Nunjucks Templates<br/>layouts, includes, macros"]
Tpl --> Collections["Collections<br/>news, cases, team, services, knowledge"]
Collections --> Transforms["Transforms<br/>Obsidian syntax, HTML minify"]
Transforms --> Output["_site (static)"]
Output --> End(["Build Complete"])

Diagram sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Frontend JavaScript Modules and CSS Architecture

The frontend is composed of:

  • A main module that initializes feature modules
  • Feature modules for navigation, theme toggling, carousels, and more
  • A modular CSS architecture imported via main.css
graph LR
MAIN["main.js"]
NAV["navigation.js"]
THEME["theme-toggling.js"]
CAROUSEL["carousel-system.js"]
CSS["main.css (imports modules)"]
MAIN --> NAV
MAIN --> THEME
MAIN --> CAROUSEL
CSS --> NAV
CSS --> THEME
CSS --> CAROUSEL

Diagram sources

  • [src/assets/js/main.js:1-37](file://src/assets/js/main.js#L1-L37)
  • [src/assets/js/modules/navigation.js:1-78](file://src/assets/js/modules/navigation.js#L1-L78)
  • [src/assets/js/modules/theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)
  • [src/assets/js/modules/carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)
  • [src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)

Section sources

  • [src/assets/js/main.js:1-37](file://src/assets/js/main.js#L1-L37)
  • [src/assets/js/modules/navigation.js:1-78](file://src/assets/js/modules/navigation.js#L1-L78)
  • [src/assets/js/modules/theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)
  • [src/assets/js/modules/carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)
  • [src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)

CMS Integration (Tina/Sveltia) via GitHub OAuth

The Worker exposes:

  • OAuth start endpoint to initiate GitHub authorization
  • Callback endpoint to exchange code for access token and post it to the opener window
  • CORS preflight handling for cross-origin requests
sequenceDiagram
participant Editor as "CMS Editor"
participant W as "worker.js"
participant GH as "GitHub OAuth API"
Editor->>W : GET /api/auth
W->>GH : Redirect to authorize
GH-->>Editor : Redirect with code
Editor->>W : GET /api/auth/callback?code=...
W->>GH : Exchange code for access token
W-->>Editor : HTML with token posted to opener

Diagram sources

  • [worker.js:183-227](file://worker.js#L183-L227)

Section sources

  • [worker.js:183-227](file://worker.js#L183-L227)
  • [src/admin/config.yml:1-774](file://src/admin/config.yml#L1-L774)
  • [tina/config.ts:1-331](file://tina/config.ts#L1-L331)

Dependency Analysis

  • Build-time dependencies
    • Eleventy and plugins for templating, RSS, and minification
    • Wrangler for local development and deployment
    • Pagefind for search indexing
  • Runtime dependencies
    • Cloudflare Worker runtime with KV, Durable Objects, and Assets
    • External APIs: Resend, GitHub, Google Sheets
  • Internal dependencies
    • Worker depends on KV bindings and secrets
    • Templates depend on data files and shortcodes/filters
    • Frontend modules depend on shared CSS and layout
graph TB
Pkg["package.json scripts"]
Ele["Eleventy (.eleventy.js)"]
Wrk["worker.js"]
Wcfg["wrangler.jsonc"]
Site["_site (Assets)"]
CSS["main.css"]
JS["main.js + modules"]
Pkg --> Ele
Pkg --> Wrk
Wrk --> Wcfg
Ele --> Site
CSS --> Ele
JS --> Ele
Wrk --> Site

Diagram sources

  • [package.json:1-32](file://package.json#L1-L32)
  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [worker.js:1-321](file://worker.js#L1-L321)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)

Section sources

  • [package.json:1-32](file://package.json#L1-L32)
  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [worker.js:1-321](file://worker.js#L1-L321)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)

Performance Considerations

  • Static delivery via Workers for Platforms ensures low-latency, edge-cached asset serving.
  • API caching headers for polling data enable long-lived cache with stale-while-revalidate behavior.
  • HTML minification in production reduces payload sizes.
  • CSS and JS are organized into modular files to support granular caching and lazy loading where applicable.
  • Eleventy’s passthrough copy avoids unnecessary processing for static assets.

[No sources needed since this section provides general guidance]

Security and Compliance

  • Session management
    • Signed session cookies with HMAC verification and constant-time comparison
    • Secure, HttpOnly, SameSite, and Max-Age attributes
    • Session duration configured per environment
  • Token lifecycle
    • Magic-link tokens stored in KV with short TTL and immediately invalidated upon use
  • Secrets management
    • Session secret, Resend API key, GitHub OAuth credentials set via Wrangler secrets
  • CSRF and bot protection
    • Honey-pot field in login form to deter bots
  • CORS and OAuth
    • Strict origin checks and controlled OAuth callback flow

Section sources

  • [worker.js:12-58](file://worker.js#L12-L58)
  • [worker.js:81-91](file://worker.js#L81-L91)
  • [worker.js:97-147](file://worker.js#L97-L147)
  • [worker.js:153-177](file://worker.js#L153-L177)
  • [worker.js:183-227](file://worker.js#L183-L227)
  • [wrangler.jsonc:28-34](file://wrangler.jsonc#L28-L34)

Deployment Topology

  • Build pipeline
    • Eleventy generates static HTML/CSS/JS into _site
    • Pagefind indexing is integrated into the build step
  • Runtime
    • Worker handles dynamic routes and proxies static assets via ASSETS binding
    • KV namespaces store approved member emails and magic-link tokens
    • Secrets are injected at deploy time
  • Legacy Pages configuration remains for reference but is superseded by WFP
graph TB
Dev["Developer Machine"]
Build["Build (Eleventy + Pagefind)"]
Deploy["Deploy (wrangler deploy)"]
Worker["worker.js"]
Assets["ASSETS (Workers for Platforms)"]
Edge["Cloudflare Edge Network"]
Dev --> Build --> Deploy --> Worker --> Edge
Worker --> Assets
Assets --> Edge

Diagram sources

  • [package.json:5-12](file://package.json#L5-L12)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)

Section sources

  • [package.json:5-12](file://package.json#L5-L12)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)

Troubleshooting Guide

  • Member authentication issues
    • Missing KV namespaces or secrets cause 503 responses; verify bindings and secret creation
    • Expired or invalid magic-link tokens redirect to login with appropriate error parameters
  • API errors
    • Polling API requires configured Google Sheets identifiers; missing values return 503
    • OAuth callback failures surface error messages; verify GitHub client credentials
  • Static assets not updating
    • Ensure passthrough copy is enabled and assets are placed under src/assets
    • Confirm Workers for Platforms directory matches configured assets binding
  • Local development
    • Use preview script to build and run wrangler dev locally

Section sources

  • [worker.js:70-75](file://worker.js#L70-L75)
  • [worker.js:153-159](file://worker.js#L153-L159)
  • [worker.js:244-246](file://worker.js#L244-L246)
  • [worker.js:200-202](file://worker.js#L200-L202)
  • [package.json:9-12](file://package.json#L9-L12)

Conclusion

The Ace Strategies Prime platform combines a fast, scalable static site with targeted serverless functionality. The Cloudflare Worker centralizes authentication, CMS integration, and dynamic API endpoints while delegating asset delivery to Workers for Platforms. Eleventy’s modular configuration and the frontend’s modular architecture support maintainability and performance. The design balances developer productivity (with CMS and build tooling) and operational reliability (edge-native compute and KV-backed persistence).