The Potato Society

System Architecture

Properties2
descriptionTechnical architecture of The Potato Society digital garden
tagsarchitecture, quartz, sync, github, cloudflare

4 min read

System Architecture & Sync Guide

How The Potato Society Digital Garden Works

This document explains the technical architecture behind potatosociety.uk and provides instructions for updating the website.

🔗 Symlink Architecture Overview

The system uses a symbolic link (symlink) approach to keep the Obsidian vault clean while allowing Quartz to access the content:

Obsidian Vault: C:\VAULT\proxmox-vault\20 Projects\ProjectHome
                ├── Index.md
                ├── Hacking.md
                ├── AI_Engineering.md
                ├── Satellite_Operations.md
                ├── System_Architecture.md
                └── [all other notes]

Quartz Installation: C:\quartz-portfolio
                     ├── quartz.config.ts
                     ├── package.json
                     ├── node_modules/
                     └── content → [SYMLINK TO VAULT]

The content folder in the Quartz installation is a directory junction (Windows symlink) pointing directly to your Obsidian vault. This means:

  1. ✅ Your Obsidian vault remains untouched and clean
  2. ✅ Quartz sees all your markdown files as if they were in its content folder
  3. ✅ Changes made in Obsidian immediately reflect on the website
  4. ✅ No duplication of files or manual copying required

⚙️ Technical Components

1. Quartz Static Site Generator

  • Framework: Quartz v4 (https://quartz.jzhao.xyz)
  • Hosting: Cloudflare Pages
  • Domain: potatosociety.uk
  • Build Command: npx quartz build --no-serve
  • Output Directory: public/

2. Configuration Files

  • quartz.config.ts: Custom black-and-white minimalist theme
  • package.json: Dependencies and build scripts
  • tsconfig.json: TypeScript configuration

3. Sync Mechanism

  • Local: PowerShell sync script (sync.ps1)
  • Remote: GitHub Web UI + Cloudflare Pages auto-deploy
  • Branch: main (default)

🔄 How to Update the Website

  1. Edit files in your Obsidian vault (C:\VAULT\proxmox-vault\20 Projects\ProjectHome)
  2. Run the sync script: .\sync.ps1
  3. The script will:
    • Pull latest changes from GitHub
    • Stage all modifications
    • Commit with timestamp
    • Push to GitHub
  4. Cloudflare Pages automatically detects the push and rebuilds the site

Method B: Remote Updates via GitHub Web UI

  1. Go to: https://github.com/[your-username]/[repo-name]
  2. Navigate to the file you want to edit
  3. Click the pencil icon to edit
  4. Make your changes
  5. Scroll down and click “Commit changes”
  6. Add a commit message and confirm
  7. Cloudflare Pages automatically detects the push and rebuilds the site

Method C: Direct Obsidian Editing

  1. Edit files directly in Obsidian
  2. The changes are immediately visible locally
  3. Remember to run .\sync.ps1 periodically to push changes to GitHub

📜 Sync Script (sync.ps1)

The sync script automates the Git workflow:

# Navigate to quartz directory
cd C:\quartz-portfolio
 
# Pull latest changes
git pull
 
# Stage all changes
git add .
 
# Commit with timestamp
$timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
git commit -m "Sync: $timestamp"
 
# Push to GitHub
git push

🌐 Cloudflare Pages Configuration

Build Settings

  • Framework: None (Static site)
  • Build command: npx quartz build --no-serve
  • Build output directory: public
  • Root directory: /quartz-portfolio

Environment Variables

None required for basic Quartz deployment.

Custom Domain

  1. In Cloudflare Pages, go to your project settings
  2. Under “Custom domains”, add potatosociety.uk
  3. Configure DNS:
    • Create CNAME record: @ → [your-project].pages.dev
    • Or follow Cloudflare’s DNS setup instructions
  4. Enable “Always use HTTPS”
  5. Enable “Automatic HTTPS Rewrites”
  6. Set cache level to “Standard” or “Aggressive” as needed

🔒 Security Considerations

  1. Private Files: Add private to ignorePatterns in quartz.config.ts
  2. Templates: Add templates to ignorePatterns
  3. Obsidian Files: Add .obsidian to ignorePatterns
  4. Git Ignore: Ensure .gitignore excludes sensitive files
  5. Environment Secrets: Never store API keys or secrets in markdown files

📱 Mobile & Offline Access

Since this is a static site:

  • Fully responsive design
  • Works offline after initial load (SPA enabled)
  • Fast loading times
  • Low bandwidth usage
  • Compatible with all modern browsers

🛠️ Troubleshooting

If the site doesn’t update:

  1. Check GitHub for recent commits
  2. Verify Cloudflare Pages build logs
  3. Run npx quartz build --no-serve locally to test
  4. Check for build errors in the console
  1. Verify wikilinks use correct format: [[Page Name]]
  2. Check that target files exist in the vault
  3. Ensure file names match exactly (case-sensitive on some systems)

If styling looks wrong:

  1. Verify quartz.config.ts is correctly formatted
  2. Check for syntax errors in the TypeScript file
  3. Clear browser cache
  4. Try hard refresh (Ctrl+F5)

🔮 Future Enhancements

  • Add search functionality
  • Implement dark/light mode toggle
  • Add analytics tracking
  • Integrate comments/giscus
  • Add RSS feed
  • Implement sitemap.xml
  • Add structured data (JSON-LD)
  • Optimize images/assets
  • Add CI/CD testing
  • Implement content versioning
  • Add backup/restore procedures

Last updated: $(Get-Date -Format “yyyy-MM-dd HH:mm”) Architecture documented for potatosociety.uk

Graph View

Backlinks