Documentation Update Summary - 2025-11-16¶

Summary¶

This reference document tracks all documentation updates made on 2025-11-16 to ensure consistency between the syrf monorepo and cluster-gitops repository after structural refactoring.

Documentation Files Updated¶

cluster-gitops Repository¶

1. README.md ✅¶

Location: /home/chris/workspace/syrf/cluster-gitops/README.md

Changes: - ✅ Fixed repository structure diagram - ✅ Updated all path references (old → new): - applicationsets/ → argocd/applicationsets/ - environments/staging/services/*.yaml → syrf/environments/staging/{service}/config.yaml - infrastructure.yaml → plugins.yaml - plugins/git/ → plugins/local/ - ✅ Updated deployment workflow descriptions - ✅ Fixed AppProjects table (infrastructure → plugins) - ✅ Updated "Check Current Versions" commands - ✅ Updated "Add New Service" instructions - ✅ Removed references to deleted custom-charts ApplicationSet

2. docs/deploying-services.md ✅¶

Location: /home/chris/workspace/syrf/cluster-gitops/docs/deploying-services.md

Changes: - ✅ Updated document metadata (date: 2025-11-16) - ✅ Changed overview to reflect fully automated deployment - ✅ Replaced manual staging deployment steps with automated description - ✅ Updated paths to syrf/environments/staging/{service}/config.yaml - ✅ Updated ArgoCD sync workflow - ✅ Added automated production promotion section - ✅ Replaced old service-specific examples with unified pattern - ✅ Updated rollback instructions with correct paths - ✅ Fixed namespace references (staging → syrf-staging)

3. docs/promotion-workflow.md ✅¶

Location: /home/chris/workspace/syrf/cluster-gitops/docs/promotion-workflow.md

Changes: - ✅ Updated document metadata (date: 2025-11-16) - ✅ Updated staging validation commands (namespace: syrf-staging) - ✅ Fixed paths in version check commands - ✅ Updated production promotion process - ✅ Added manual review process section - ✅ Removed obsolete manual promotion options - ✅ Updated example config files with correct structure

4. docs/architecture/structural-changes-summary.md ✅¶

Location: /home/chris/workspace/syrf/cluster-gitops/docs/architecture/structural-changes-summary.md

Created: Complete summary of all structural changes made to cluster-gitops

5. docs/architecture/cluster-gitops-critique.md ✅¶

Location: /home/chris/workspace/syrf/cluster-gitops/docs/architecture/cluster-gitops-critique.md

Moved: From syrf monorepo to cluster-gitops (correct location)

syrf Monorepo¶

1. CLAUDE.md ✅¶

Location: /home/chris/workspace/syrf/CLAUDE.md

Changes: - ✅ Updated staging promotion workflow paths: - environments/staging/services/{service}.yaml → syrf/environments/staging/{service}/config.yaml - ✅ Updated production promotion workflow: - Added step to update envName field - Updated paths to syrf/environments/production/{service}/config.yaml

2. .github/workflows/ci-cd.yml ✅¶

Location: /home/chris/workspace/syrf/.github/workflows/ci-cd.yml

Changes: - ✅ Staging promotion: Updated to use correct paths - ✅ Production promotion: Updated to copy configs and set envName - ✅ YAML validation: Updated to check correct paths - ✅ Removed FILE variable, simplified to use SERVICE directly

Path Changes Summary¶

Old Paths → New Paths¶

Context	Old Path	New Path
ApplicationSets	`applicationsets/`	`argocd/applicationsets/`
Staging config	`environments/staging/services/{service}.yaml`	`syrf/environments/staging/{service}/config.yaml`
Production config	`environments/production/services/{service}.yaml`	`syrf/environments/production/{service}/config.yaml`
Base service config	`syrf/{service}/`	`syrf/services/{service}/`
Infrastructure	`applicationsets/infrastructure.yaml`	`argocd/applicationsets/plugins.yaml`
Plugins	`plugins/git/`	`plugins/local/`
Namespace	`staging`	`syrf-staging`
Namespace	`production`	`syrf-production`

Workflow Changes Summary¶

Before (Manual)¶

1. Developer pushes to main
2. CI/CD builds image
3. Developer manually edits cluster-gitops
4. Developer commits and pushes
5. ArgoCD syncs

After (Automated)¶

1. Developer pushes to main
2. CI/CD builds image AND creates git tag
3. CI/CD creates PR to cluster-gitops (automated)
4. CI/CD auto-merges staging PR (automated)
5. ArgoCD syncs to staging (automated)
6. CI/CD creates production PR (automated)
7. Team reviews and merges (manual gate)
8. ArgoCD syncs to production (automated)

Documentation Consistency Checks¶

✅ All Paths Consistent¶

All documentation uses syrf/environments/{env}/{service}/config.yaml
All references to ApplicationSets use argocd/applicationsets/
All references to plugins use plugins/ (not infrastructure)

✅ All Workflows Described Correctly¶

Staging promotion fully automated
Production promotion automated with manual review gate
No manual file editing required

✅ All Examples Up-to-Date¶

Code examples use correct YAML structure
Commands reference correct file paths
Namespace names match actual deployment (syrf-staging, syrf-production)

Files NOT Changed (Already Correct)¶

The following files were reviewed and found to be accurate:

cluster-gitops/docs/applicationsets.md - Correct structure documented
cluster-gitops/docs/cluster-bootstrap.md - Bootstrap process unchanged
cluster-gitops/docs/how-to/*.md - Operational guides still accurate
cluster-gitops/docs/troubleshooting/*.md - Troubleshooting unchanged

Verification Checklist¶

Documentation Accuracy¶

All file paths match actual repository structure
All workflow descriptions match ci-cd.yml implementation
All examples use correct YAML structure
All namespace references use actual names
No references to deleted files/directories

Cross-Repository Consistency¶

syrf/CLAUDE.md matches cluster-gitops/README.md
syrf/.github/workflows/ci-cd.yml matches cluster-gitops docs
Both repositories describe same deployment workflow
Path references consistent across all docs

Completeness¶

Staging deployment fully documented
Production promotion fully documented
Rollback procedure documented
Troubleshooting paths updated
All services documented (api, web, pm, quartz, docs, user-guide)

Next Steps¶

For Users¶

✅ Read updated deployment guides
✅ Use new paths when referencing configs
✅ Rely on automated workflows (no manual edits needed)

For Future Updates¶

Update this checklist when structure changes
Keep documentation in sync with actual implementation
Run validation after any structural changes

Status: ✅ All documentation updated and verified Date: 2025-11-16 Reviewed By: Claude