Skip to content

ralph.md

Latest commit

 

History

History
605 lines (440 loc) · 17.4 KB

ralph.md

File metadata and controls

605 lines (440 loc) · 17.4 KB
Raw

Commute Planner - Project Review

Project Overview

A Berlin public transit visualization tool for the Dallgow-Döberitz ↔ Warschauer Straße commute route. Displays RE/RB regional trains with S-Bahn transfers in three visualization modes.

Final Architecture

commute-planner/
├── index.html              # Generated output (self-contained, deployed)
├── template.html           # HTML template for local development
├── package.json            # Project config & npm scripts
├── README.md               # User documentation
├── ralph.md                # Development log
├── src/
│   ├── styles.css          # Source CSS (single source of truth)
│   └── app.js              # Source JS with data placeholders
├── scripts/
│   └── updater.js          # VBB API fetcher + HTML generator
└── .github/workflows/
    └── update.yaml         # Daily CI update (03:00 UTC)

Key Features

  • Bidirectional routes: Hin (outbound) / Rück (return) toggle
  • Three view modes: Fahrzeit, Zeitstrahl, Mobil
  • Live time marker: Pulsing "now" indicator in timeline views
  • Auto-refresh: Re-renders when hour changes
  • API resilience: Keeps existing data if VBB API fails

Development Workflow

npm run update   # Fetch VBB data and generate index.html
npm run dev      # Open template.html for local development

How It Works

  1. src/styles.css and src/app.js contain the source code
  2. template.html references these files for local development
  3. scripts/updater.js fetches VBB API data and generates index.html
  4. Generated index.html is self-contained (CSS/JS inlined) for deployment

Deployment to GitHub Pages

Step 1: Create GitHub Repository

# Initialize git (if not already)
git init

# Add all files
git add .
git commit -m "Initial commit"

# Create repo on GitHub and push
gh repo create commute-planner --public --source=. --push

Or manually:

  1. Go to https://github.com/new
  2. Create repository named commute-planner
  3. Push existing code: 
    git remote add origin git@github.com:YOUR_USERNAME/commute-planner.git
git push -u origin main

Step 2: Enable GitHub Pages

  1. Go to repository Settings → Pages
  2. Under "Source", select Deploy from a branch
  3. Select main branch and / (root) folder
  4. Click Save

Your site will be live at: https://YOUR_USERNAME.github.io/commute-planner/

Step 3: GitHub Actions (Already Configured)

The workflow at .github/workflows/update.yaml runs automatically:

  • Schedule: Daily at 03:00 UTC
  • Manual: Click "Run workflow" in Actions tab

The workflow:

  1. Checks out the repository
  2. Runs node scripts/updater.js to fetch fresh VBB data
  3. Commits and pushes updated index.html if changed
  4. GitHub Pages automatically deploys the new version

Workflow Permissions

The workflow needs write access. If commits fail:

  1. Go to Settings → Actions → General
  2. Under "Workflow permissions", select Read and write permissions
  3. Click Save

Manual Trigger

To update schedule data manually:

  1. Go to Actions tab
  2. Select "Schedule Update (Daily)"
  3. Click Run workflow → Run workflow

Iteration Log

Iteration 1 (2026-04-14)

Goal: Review project and improve maintainability

Issues Found:

  • Code duplication across 3 HTML files (~400 lines each)
  • No separation of concerns (CSS/JS embedded in HTML)
  • Deprecated planner.html causing confusion
  • No package.json for project management

Changes Made:

  • ✅ Created src/styles.css - extracted all CSS
  • ✅ Created src/app.js - extracted all JavaScript
  • ✅ Simplified template.html to use external files
  • ✅ Moved updater.js to scripts/updater.js
  • ✅ Updated updater to inline CSS/JS when generating index.html
  • ✅ Added package.json with npm scripts
  • ✅ Removed deprecated planner.html
  • ✅ Updated GitHub Action workflow path
  • ✅ Verified updater works (43 outbound, 63 return journeys)

Result: Single source of truth for CSS/JS, cleaner project structure

Iteration 2 (2026-04-14)

Goal: Review restructure, verify functionality, update documentation

Verification:

  • ✅ npm run update works (43 outbound, 63 return journeys fetched)
  • ✅ Generated index.html is self-contained with inlined CSS/JS
  • ✅ template.html correctly references external src/ files
  • ✅ Project structure is clean and maintainable

Documentation Updates:

  • ✅ Updated README.md to remove reference to deleted planner.html
  • ✅ Updated README.md usage section with npm scripts
  • ✅ Documented iteration 2 in ralph.md

Iteration 3 (2026-04-14)

Goal: Final review, verify completeness, document conclusions

Final Verification:

  • ✅ npm run update works correctly (43 outbound, 63 return journeys)
  • ✅ All source files properly organized in src/
  • ✅ Build script in scripts/
  • ✅ CI workflow configured and using correct paths
  • ✅ Documentation complete (README.md, ralph.md)

Code Quality Assessment:

  • app.js: Well-structured with clear function separation
  • styles.css: Organized with logical sections
  • updater.js: Robust error handling, graceful API failure recovery
  • template.html: Clean, minimal, references external assets correctly

Iteration 4 (2026-04-14)

Goal: Document deployment process for GitHub and Actions

Additions:

  • ✅ Added complete GitHub Pages deployment guide
  • ✅ Documented workflow permissions setup
  • ✅ Added manual trigger instructions
  • ✅ Explained how CI/CD pipeline works

Iteration 5 (2026-04-14)

Goal: Final review and verification

Verification Results:

  • ✅ npm run update works (43 outbound, 62 return journeys)
  • ✅ GitHub Actions workflow properly configured with permissions: contents: write
  • ✅ Workflow uses correct path scripts/updater.js
  • ✅ README.md accurately documents the project
  • ✅ All deployment instructions complete and accurate

Project Status: COMPLETE

Iteration 6 (2026-04-14)

Goal: Final verification (iteration 3 of 3)

Verification:

  • ✅ npm run update works (43 outbound, 62 return journeys)
  • ✅ All documentation complete
  • ✅ Deployment guide in ralph.md covers GitHub Pages + Actions
  • ✅ Workflow has correct permissions and paths

Project Status: COMPLETE - All requirements met

Iteration 7 (2026-04-14)

Goal: Review project and document S3 deployment alternatives

Analysis: The generated index.html is fully self-contained (CSS/JS inlined, no external dependencies except Google Fonts). This makes it ideal for any static hosting solution.

Alternatives Documented:

  • ✅ S3 static website hosting (direct)
  • ✅ S3 + CloudFront (HTTPS + CDN)
  • ✅ Comparison with GitHub Pages

Hosting Alternatives

⚠️ Important: GitHub Pages Pricing Clarification

GitHub Pages is FREE for public repositories. No Pro account needed.

GitHub Pro ($48/year) is only required for:

  • GitHub Pages on private repositories
  • Other Pro features (protected branches, code owners, etc.)

For this commute planner (a single public HTML file), GitHub Pages costs $0.

If you want to keep the repo private but still host for free, use one of the alternatives below.

Free Hosting Alternatives (All $0)

Service HTTPS Custom Domain CDN Deploy Command
GitHub Pages ✅ ✅ ✅ Push to repo
Netlify ✅ ✅ ✅ netlify deploy --prod
Vercel ✅ ✅ ✅ vercel --prod
Cloudflare Pages ✅ ✅ ✅ wrangler pages deploy
Surge.sh ✅ ✅ ❌ surge . your-domain.surge.sh
S3 Static ❌ ✅ ❌ aws s3 cp (~$0.01/mo)

Recommendation by Use Case

Scenario Best Choice Why
Public repo, simplest setup GitHub Pages Already integrated, zero config
Private repo, free hosting Netlify or Vercel Free tier, easy deploy
AWS ecosystem S3 Integrates with existing infra
Maximum performance Cloudflare Pages Fastest global CDN
Quick one-off deploy Surge.sh Single command, no account needed

Option 1: Netlify (Free, Recommended for Private Repos)

# Install CLI
npm install -g netlify-cli

# Deploy (creates account on first run)
netlify deploy --prod --dir=.

# Or drag-and-drop index.html at https://app.netlify.com/drop

Free tier includes: 100GB bandwidth/month, HTTPS, custom domains, deploy previews.

Option 2: Vercel (Free)

# Install CLI
npm install -g vercel

# Deploy
vercel --prod

# Follow prompts to link/create project

Free tier includes: 100GB bandwidth/month, HTTPS, custom domains, serverless functions.

Option 3: Cloudflare Pages (Free, Fastest CDN)

# Install CLI
npm install -g wrangler

# Login
wrangler login

# Deploy
wrangler pages deploy . --project-name=commute-planner

Free tier includes: Unlimited bandwidth, HTTPS, custom domains, global CDN.

Option 4: Surge.sh (Free, Simplest)

# Install CLI
npm install -g surge

# Deploy (creates account on first run)
surge . commute-planner.surge.sh

Free tier includes: Unlimited projects, HTTPS on surge.sh subdomains.

Option 5: S3 Static Website (~$0.01/month)

See detailed S3 instructions below. Best if you're already in AWS ecosystem.

Deployment to S3 (Static Website Hosting)

Option A: Manual Upload

The simplest approach - just upload index.html to S3:

# Upload to S3 bucket
aws s3 cp index.html s3://YOUR-BUCKET-NAME/index.html \
  --content-type "text/html"

Option B: S3 Static Website Hosting

Step 1: Create S3 Bucket

# Create bucket (bucket name must be globally unique)
aws s3 mb s3://commute-planner-YOURNAME --region eu-central-1

# Enable static website hosting
aws s3 website s3://commute-planner-YOURNAME \
  --index-document index.html

Step 2: Configure Public Access

Create bucket-policy.json:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "PublicReadGetObject",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::commute-planner-YOURNAME/*"
  }]
}

Apply the policy:

# Disable block public access (required for public website)
aws s3api put-public-access-block \
  --bucket commute-planner-YOURNAME \
  --public-access-block-configuration \
  "BlockPublicAcls=false,IgnorePublicAcls=false,BlockPublicPolicy=false,RestrictPublicBuckets=false"

# Apply bucket policy
aws s3api put-bucket-policy \
  --bucket commute-planner-YOURNAME \
  --policy file://bucket-policy.json

Step 3: Upload and Access

# Upload index.html
aws s3 cp index.html s3://commute-planner-YOURNAME/index.html \
  --content-type "text/html"

# Your site is now available at:
# http://commute-planner-YOURNAME.s3-website.eu-central-1.amazonaws.com

Option C: GitHub Actions → S3 Deployment

Update .github/workflows/update.yaml to deploy to S3:

name: Update and Deploy to S3

on:
  schedule:
    - cron: '0 3 * * *'
  workflow_dispatch:

jobs:
  update-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run updater script
        run: node scripts/updater.js

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: eu-central-1

      - name: Deploy to S3
        run: |
          aws s3 cp index.html s3://YOUR-BUCKET-NAME/index.html \
            --content-type "text/html" \
            --cache-control "max-age=3600"

Required GitHub Secrets:

  • AWS_ACCESS_KEY_ID: IAM user access key
  • AWS_SECRET_ACCESS_KEY: IAM user secret key

IAM Policy for deployment user:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:PutObject", "s3:PutObjectAcl"],
    "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
  }]
}

Conclusions

Project Health

Aspect Status
Code duplication ✅ Eliminated
Build process ✅ Working
Documentation ✅ Complete
CI/CD ✅ Configured
Error handling ✅ Robust
Deployment guide ✅ Documented

Architecture Summary

  • Source of truth: src/styles.css and src/app.js
  • Build output: index.html (self-contained, deployable)
  • Data source: VBB REST API (fetched daily)
  • Hosting: GitHub Pages (static file serving)
  • Automation: GitHub Actions (daily schedule + manual trigger)

Future Considerations

  • Add TypeScript for type safety
  • Add unit tests for journey formatting
  • Consider PWA features for offline access

Iteration 8 (2026-04-14)

Goal: Final review, verify S3 compatibility, document conclusions

S3 Compatibility Verification:

  • ✅ index.html is self-contained (CSS/JS inlined)
  • ✅ Only external dependency: Google Fonts (CDN, works everywhere)
  • ✅ No relative paths or local file references
  • ✅ Single file deployment - just upload index.html

Additional Alternatives Considered:

Alternative Pros Cons
Netlify Free tier, auto-deploy from Git, HTTPS Another service to manage
Vercel Same as Netlify Same as Netlify
Cloudflare Pages Free, fast CDN, HTTPS Another service to manage
Self-hosted (nginx) Full control Requires server maintenance

Why S3 is a Good Choice:

  1. Simplicity: Single aws s3 cp command to deploy
  2. Cost: Essentially free for low-traffic personal use
  3. Reliability: AWS infrastructure, 99.99% availability
  4. No server: No maintenance, no patching, no scaling concerns
  5. Integration: Easy to add CloudFront later for HTTPS/CDN

Final Recommendation:

  • For simplicity: GitHub Pages (zero cost, zero config)
  • For AWS ecosystem: S3 + CloudFront (HTTPS, custom domain)
  • For quick test: aws s3 cp index.html s3://bucket/ works immediately

Final Conclusions

Project Status: COMPLETE ✅

The commute-planner project is production-ready:

  1. Code Quality: Clean separation of concerns, single source of truth
  2. Build Process: npm run update generates self-contained HTML
  3. Deployment: Works on GitHub Pages, S3, or any static host
  4. Automation: GitHub Actions for daily updates
  5. Documentation: Complete guides for all deployment options

S3 Deployment Summary

The index.html file can be placed on S3 with a single command:

aws s3 cp index.html s3://YOUR-BUCKET/index.html --content-type "text/html"

For public access, enable static website hosting or use CloudFront.

Iteration 9 (2026-04-14)

Goal: Final review (iteration 3 of 3 in current loop)

Verification:

  • ✅ index.html is self-contained (41KB, CSS/JS inlined)
  • ✅ Build script handles API failures gracefully (keeps existing file)
  • ✅ S3 deployment documented with 3 options (manual, static website, CI/CD)
  • ✅ Alternatives comparison complete (GitHub Pages vs S3 vs CloudFront)

S3 Readiness Confirmed: The index.html file can be deployed to S3 immediately:

  • No server-side processing required
  • No relative paths or local dependencies
  • Single file deployment: aws s3 cp index.html s3://bucket/

Iteration 10 (2026-04-14)

Goal: Clarify GitHub Pages pricing, document free alternatives

Key Finding: GitHub Pages is FREE for public repositories. The $48/year Pro account is only needed for:

  • GitHub Pages on private repos
  • Other Pro features (protected branches, etc.)

Free Alternatives Documented:

  • ✅ Netlify (free tier: 100GB/mo, HTTPS, custom domains)
  • ✅ Vercel (free tier: 100GB/mo, HTTPS, custom domains)
  • ✅ Cloudflare Pages (free tier: unlimited bandwidth, fastest CDN)
  • ✅ Surge.sh (free, simplest single-command deploy)
  • ✅ S3 (~$0.01/mo for low traffic)

Recommendation:

  • Public repo → GitHub Pages (free, already integrated)
  • Private repo → Netlify or Cloudflare Pages (free, easy setup)

Iteration 11 (2026-04-14)

Goal: Review project, verify alternatives documentation addresses $48 GitHub Pro concern

User Concern: GitHub Pages requires $48/year Pro account

Analysis: The $48/year is for GitHub Pro, which is only needed if you want GitHub Pages on a private repository. For a public repo, GitHub Pages is completely free.

Your Options (All Free):

If you want... Use this Cost
Public repo + GitHub Pages GitHub Pages $0
Private repo + free hosting Netlify, Vercel, or Cloudflare Pages $0
AWS ecosystem S3 static website ~$0.01/mo
Simplest one-command deploy Surge.sh $0

Recommendation for "just hosting an HTML file":

  1. Easiest (public repo): Keep using GitHub Pages - it's free
  2. Easiest (private repo): Use Netlify Drop - drag & drop at https://app.netlify.com/drop
  3. AWS user: aws s3 cp index.html s3://bucket/ --content-type text/html

Verification:

  • ✅ Build works: 43 outbound, 62 return journeys
  • ✅ All alternatives documented with CLI commands
  • ✅ Cost comparison table complete

Last updated: 2026-04-14 (Iteration 11)