STLPWebsite/WORKFLOW.md

# Production Workflow Guide

This guide explains the actual workflow for Starting Line Productions LLC website with both technical and non-technical users.

## User Types

### Technical Users / AI Agents
- **Access:** Local development environment (Docker port 5001)
- **Method:** Direct markdown file editing via git
- **Tools:** Text editor, git, Docker
- **Example:** You (Charles), AI agents working on documentation

### Non-Technical Users
- **Access:** Production server only (via Admin UI)
- **Method:** Visual content editing through Grav Admin interface
- **Tools:** Web browser
- **Example:** Staff, business owner making content updates

## Workflow Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                    Git Repository                        │
│            (git@knownelement.com/STLPWebsite.git)       │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
        ▼                         ▼
┌──────────────────┐   ┌─────────────────────────┐
│   Local Dev     │   │     Production        │
│  (Docker 5001) │   │   (Production URL)   │
└──────────────────┘   └──────────┬──────────────────┘
                            │
                    ┌───────┴───────┐
                    │               │
                    ▼               ▼
            ┌───────────┐   ┌───────────┐
            │  Website  │   │  Admin UI │
            │  Pages    │   │   Browser  │
            └───────────┘   └───────────┘
```

## Workflows

### Technical User Workflow (AI Agents, Charles)

**Use this when:** Adding new equipment pages, area documentation, structural changes

```bash
# 1. Work locally
cd /home/charles/Projects/STLPWebsite
docker compose up -d

# 2. Make changes
# Edit markdown files: config/www/user/pages/
# Test in browser: http://localhost:5001

# 3. Commit changes
git add .
git commit -m "feat(equipment): add CNC Lathe page"

# 4. Push to git repository
git push origin main

# 5. Deploy to production
# (SSH into production server)
ssh user@production-server.com
cd /var/www/grav
git pull origin main
rm -rf user/cache/*
```

**Flow:**
Local Dev → Git Commit → Git Push → Production Pull

### Non-Technical User Workflow (Staff, Business Owner)

**Use this when:** Updating existing content, changing text, minor edits

```bash
# 1. Access production admin UI
https://startinglineproductions.com/admin

# 2. Login with admin credentials
username: admin
password: [your-password]

# 3. Navigate to Pages
# Find the page you want to edit

# 4. Make changes using visual editor
# Edit content directly in browser
# Click "Save"

# 5. Changes are immediately visible on production
```

**Flow:**
Admin UI → Production Filesystem → Visible on Site

### Syncing Admin Changes to Git (Manual Process)

**Use this when:** Non-technical users have made changes via Admin UI and those changes need to be preserved in git

**Why this is needed:**
- Admin UI saves changes directly to production filesystem
- These changes are NOT in git repository
- If production server is lost or restored from git, admin changes will be LOST
- Technical user must periodically pull these changes and commit to git

**When to run:**
- After significant content updates via Admin UI
- Before major deployments or server migrations
- Weekly (recommended) as a backup procedure
- After non-technical users report making important changes

**Steps:**

```bash
# 1. SSH into production server
ssh user@production-server.com

# 2. Check what has changed
cd /var/www/grav
git status

# 3. Add all changed files (from admin edits)
git add user/pages/
git add user/config/  # If admin changed config

# 4. Review changes before committing
git diff --staged

# 5. Commit changes
git commit -m "feat: update content via Admin UI
- Updated [specific pages]
- Changed [specific sections]
- Modified by [staff member] via Admin"

# 6. Push to git repository
git push origin main
```

**Example Scenario:**

```
Day 1-5: Staff makes various content updates via Admin UI
  - Updates pricing on Resources page
  - Adds new project to Contact page
  - Changes phone number on Contact page
  - Edits equipment descriptions

Day 6: Charles (technical user) syncs to git
  - SSH into production
  - Runs git status (shows 4 changed files)
  - Reviews changes
  - Commits: "feat: weekly content updates via Admin UI"
  - Pushes to git repository

Result: All admin changes are now safely in git
```

## Automated Sync (Optional Enhancement)

If you want to automate the sync process, you can:

### Option 1: Cron Job (Simple)

Run a script periodically to check for changes and commit them.

**Production Server Crontab:**
```bash
# Check for admin changes and commit (daily at 6 AM)
0 6 * * * /var/scripts/sync-admin-changes.sh
```

**Script: sync-admin-changes.sh**
```bash
#!/bin/bash
cd /var/www/grav

# Check if there are uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
    # Add all changes
    git add -A

    # Create automatic commit
    git commit -m "chore: auto-commit admin UI changes
Date: $(date)
Changes detected in user/pages or user/config"

    # Push to git
    git push origin main

    echo "Admin changes synced to git"
else
    echo "No changes detected"
fi
```

**Pros:** Automatic, no manual intervention
**Cons:** Commits everything without review, could commit mistakes

### Option 2: Manual Trigger (Recommended)

Run sync only when you know changes were made.

**Add to bash aliases:**
```bash
# Add to ~/.bashrc
alias sync-admin='ssh production-server.com /var/scripts/sync-admin.sh'
```

**Sync script: sync-admin.sh**
```bash
#!/bin/bash
cd /var/www/grav

echo "Checking for Admin UI changes..."
git status

read -p "Do you want to commit and push these changes? (y/n): " answer

if [ "$answer" == "y" ]; then
    git add -A
    echo "Enter commit message (Ctrl+C to cancel):"
    read message
    git commit -m "$message"
    git push origin main
    echo "Changes synced to git"
else
    echo "Sync cancelled"
fi
```

**Usage:**
```bash
# After staff makes changes, run:
sync-admin

# Review changes, enter commit message, confirm
```

**Pros:** Human review before committing, safe
**Cons:** Requires manual trigger

## Troubleshooting Sync Issues

### Issue 1: Git Conflicts

**Problem:** Both technical user (local git) and non-technical user (admin UI) edited the same file.

**Scenario:**
1. Charles adds new content to CNC Mill page locally
2. Commits and pushes to git
3. Staff edits same CNC Mill page via Admin UI
4. Charles tries to pull from production to sync changes
5. Git reports conflict

**Solution:**

```bash
# On production server
cd /var/www/grav

# Pull local changes (this will show conflict)
git pull origin main

# Open conflicted file
vim user/pages/04.equipment/01.cnc/01.cnc-mill/default.md

# Look for conflict markers:
# <<<<<<< HEAD
# Admin UI version
# =======
# Git version
# >>>>>>> origin/main

# Manually resolve conflict (keep what you want)
# Remove conflict markers

# Save and exit

# Add resolved file
git add user/pages/04.equipment/01.cnc/01.cnc-mill/default.md

# Commit resolution
git commit -m "fix: resolve merge conflict in CNC Mill page
- Merged admin UI changes with git changes
- Kept both [specific content]"

# Push resolution
git push origin main
```

**Prevention:**
- Communicate with staff before making major changes
- Check git status on production before editing (if you're technical user)
- Use different files when possible

### Issue 2: Admin Changes Not Persisting

**Problem:** Staff makes changes via Admin UI but they disappear.

**Possible Causes:**

1. **Cache Issue**
```bash
# Clear cache on production
ssh production-server.com
cd /var/www/grav
rm -rf user/cache/*
```

2. **Permissions Issue**
```bash
# Fix permissions
chown -R www-data:www-data user/
find user -type d -exec chmod 775 {} \;
find user -type f -exec chmod 664 {} \;
```

3. **Plugin Conflict**
```bash
# Check logs
tail -50 user/logs/grav.log

# Disable conflicting plugin (temporarily)
mv user/plugins/problematic-plugin user/plugins/problematic-plugin.disabled
```

### Issue 3: Git History Lost

**Problem:** Admin UI changes are not being synced, git repository is outdated.

**Consequence:** If production server crashes, all admin UI changes are lost.

**Solution:**
- Sync admin changes to git regularly (at least weekly)
- Implement automated sync if frequent admin edits
- Monitor git status on production

## Best Practices

### For Technical Users (You, AI Agents)

1. **Always test locally** before pushing to production
2. **Check production git status** before pulling (to see if admin made changes)
3. **Communicate** with staff when making structural changes
4. **Sync regularly** to capture admin UI changes
5. **Document** any manual interventions

### For Non-Technical Users (Staff)

1. **Use Admin UI** for content updates only (not structural changes)
2. **Report** any issues or errors immediately
3. **Notify** technical user when making significant content updates
4. **Understand** that Admin UI changes are not automatically backed up to git

### For Business Owner

1. **Technical User:** Handles all major updates, new pages, structural changes
2. **Staff Updates:** Content updates via Admin UI are synced periodically to git
3. **Weekly Backup:** Technical user syncs admin changes to git weekly
4. **Monthly Review:** Review what changes have been made via Admin UI

## Quick Reference

### Technical User Commands

```bash
# Local development
docker compose up -d
docker exec stlp-grav rm -rf user/cache/*

# Git workflow
git add .
git commit -m "message"
git push origin main

# Sync admin changes from production
ssh production-server.com
cd /var/www/grav
git status                    # Check what changed
git add user/pages/           # Add admin changes
git commit -m "feat: sync admin changes"
git push origin main

# Deploy to production
ssh production-server.com
cd /var/www/grav
git pull origin main
rm -rf user/cache/*
```

### Non-Technical User Actions

```
1. Open browser
2. Go to: https://startinglineproductions.com/admin
3. Login
4. Navigate to Pages
5. Edit content
6. Click Save
7. Changes are live
```

### Sync Frequency Recommendations

| Activity | Frequency | Who |
|----------|------------|-----|
| Minor content updates (price changes, text edits) | Weekly | Technical user syncs |
| Major content updates (new equipment, area changes) | Immediately after | Technical user syncs |
| Emergency content updates | Immediately after | Technical user syncs |
| Regular sync (backup) | Weekly (e.g., Monday 9 AM) | Automated or manual |

## Communication Protocol

### Before Making Changes

**Technical User:**
- Check: Are any staff actively using Admin UI?
- Notify: "I'm updating X page, avoid editing it for 30 minutes"

**Non-Technical User:**
- Check: Is technical user making updates today?
- Notify: "I'm updating X page via Admin UI"

### After Making Changes

**Technical User:**
- Notify: "I've updated X page, please review"
- Sync: Pull from production if staff made changes

**Non-Technical User:**
- Notify: "I've updated X page via Admin UI, please sync to git"
- Technical user performs sync

## Emergency Procedures

### Production Site Down

**If production site crashes:**

1. **Quick Check:**
   ```bash
   ssh production-server.com
   cd /var/www/grav
   rm -rf user/cache/*
   ```

2. **If still down:** Restore from git
   ```bash
   cd /var/www/grav
   git pull origin main
   rm -rf user/cache/*
   ```

3. **If git has issue:** Restore from backup
   ```bash
   # Find most recent backup
   ls -lh /var/backups/grav/

   # Restore
   tar -xzf /var/backups/grav/grav_backup_YYYYMMDD.tar.gz
   ```

### Lost Admin UI Changes

**If admin changes were not synced and server lost:**

1. **Check backups:**
   ```bash
   ls -lh /var/backups/grav/
   ```

2. **Restore from backup:**
   ```bash
   cd /var/www/grav
   tar -xzf /var/backups/grav/grav_backup_recent.tar.gz
   ```

3. **Sync to git:**
   ```bash
   git add -A
   git commit -m "restore: restore from backup after server failure"
   git push origin main
   ```

## Summary

**Key Points:**
- Technical users work in local dev (Docker), push to git, deploy to production
- Non-technical users work in production Admin UI only
- Admin UI changes are NOT in git - must be manually synced
- Sync admin changes to git regularly (at least weekly)
- Use communication to avoid conflicts
- Implement automated sync if frequent admin edits

**Critical Rule:**
> Admin UI changes MUST be synced to git to prevent data loss
> This is a manual process unless automated

---

**For more details:**
- See AGENTS.md for technical guidelines
- See DEPLOYMENT.md for production deployment
- See README.md for general project information