Repository Cleanup & Maintenance Policy¶

Archived record

This page describes the Firebase-era platform or a migration step that has completed. It is kept as history and is not a current runbook. The current platform is described from the home page.

Document Version: 1.0 Last Updated: 2026-02-06 Status: Active Audience: All developers, DevOps engineers, project maintainers

Executive Summary¶

This document codifies the repository cleanup performed on 2026-02-06 and establishes policies for:

What stays in the active repository
What's archived in /legacy/
What can be safely deleted
How foundation documents are managed
SME validation requirements for documentation updates

Foundation Documents (PROTECTED)¶

These 4 documents form the basis of our new backend deployment and frontend architecture. They can only be updated, never deleted. Any updates must be reviewed and validated by the appropriate SME personas:

1. `documentation/infra-architecture-complete.md`¶

Purpose: Complete architecture blueprint for both frontend and backend
Size: ~32 KB
SME Reviewers: CGOA, GPCA
Change Policy: Updates require CGOA (GitOps) and GPCA (Google Cloud) validation
Status: Protected, no deletion

2. `documentation/labs-platform-guide.md`¶

Purpose: Hostinger VPS labs backend (pull-based runner agent + Firestore job queue) — replaced the Kubernetes backend setup guide in v1.5.0
SME Reviewers: CGOA, GPCA
Change Policy: Updates require GitOps/GCP validation
Status: Protected, no deletion

3. `documentation/infra-frontend-setup.md`¶

Purpose: Frontend development environment and Firebase integration
Size: ~23 KB
SME Reviewers: GDEF, GHE
Change Policy: Updates require Firebase and GitHub Actions validation
Status: Protected, no deletion

4. `documentation/pipeline-deployment-guide.md`¶

Purpose: Complete deployment pipeline for both frontend and backend tiers
Size: ~42 KB
SME Reviewers: CAPA, CGOA, GDEF, GPCA, GHE (all 5 cloud/DevOps SMEs)
Change Policy: Updates require multi-SME validation (GitOps, Firebase, GCP, GitHub)
Status: Protected, no deletion

Cleanup Performed (2026-02-06)¶

✅ Items Deleted¶

Build Artifacts:

/build/ - Vite build output (85 files, ~50 MB)
Reason: Regenerated on every npm run build
Recovery: Run npm run build to restore

Unnecessary Binaries:

/helm-bin/ - Helm binary for Windows (3 files)
Reason: Use system helm via package manager instead
Recovery: Install via brew install helm (macOS) or choco install kubernetes-helm (Windows)

Debug & Cache Files:

firestore-debug.log - Firebase emulator debug log
.firebase/logs/ - Firebase extension logs
Reason: Debug artifacts, not needed in repository
Recovery: Regenerated by tools on demand

Generated Dependencies:

functions/node_modules/ - Regenerated with npm install
scripts/node_modules/ - Regenerated with npm install
Reason: ~300 MB of generated files, can be restored instantly
Recovery: cd functions && npm install or cd scripts && npm install

Total Space Freed: ~500 MB

🏗️ Items Kept (Active Development)¶

Frontend Application:

/src/ - All React source code (145 files)
/public/ - Static assets (739 files)
/tests/ - E2E tests (Playwright)
package.json, package-lock.json - Dependencies
All Vite, TailwindCSS, ESLint, Prettier configs

Backend Functions (Being Refactored):

/functions/ - Firebase Cloud Functions
functions/package.json - Still active, will migrate to VPS in Phase 2

CI/CD & Infrastructure:

/.github/workflows/ - All GitHub Actions workflows (24 workflows)
/platform/terraform/ - Current Terraform IaC for VPS
/labs/ - Hostinger VPS labs runner agent (replaced /platform/ansible/ in v1.5.0)

Documentation:

/documentation/ - All current deployment guides
agents.md - Project agent personas and guidance
readme.md - Project overview

Configuration & Secrets:

firebase.json, .firebaserc - Firebase project config
firestore.rules, storage.rules - Firebase security rules
.env.example - Environment template (no secrets)
All IDE configs (.vscode/, .devcontainer/)

Historical Reference:

/legacy/ - Complete archive of previous infrastructure
Contains: Old Kubernetes, Docker Compose, Terraform, Ansible, Python backend
Usage: Reference only during new backend implementation
Policy: Read-only, never update

Repository Organization Standards¶

Directory Structure¶

/
├── src/                          # ✅ Frontend application code
├── public/                       # ✅ Static assets
├── tests/                        # ✅ Test files
├── functions/                    # ✅ Firebase Cloud Functions (being refactored)
├── platform/                     # ✅ Current infrastructure (Terraform & Ansible)
│   ├── terraform/               # Active IaC for VPS
│   └── ansible/                 # Active automation for VPS
├── documentation/               # ✅ Current deployment guides (NEW)
│   ├── INFRA-*.md              # Foundation docs (protected)
│   ├── PIPELINE-*.md           # Deployment pipeline (protected)
│   ├── repo-cleanup-policy.md  # This file
│   └── templates/              # Content creation templates
├── legacy/                       # 📚 Historical reference (read-only)
│   ├── infrastructure/          # Old Kubernetes, Docker, etc.
│   ├── documentation/           # Old guides and plans
│   └── wiki/                    # Old wiki documentation
├── .github/                      # ✅ GitHub workflows and configs
├── .vscode/                      # ✅ IDE configuration
├── .husky/                       # ✅ Git hooks
├── config/                       # ✅ Configuration files
├── tools/                        # ✅ Build tools
├── scripts/                      # ✅ Utility scripts
├── node_modules/                # ✅ Frontend dependencies
├── .claude/                      # ✅ Claude Code settings
├── agents.md                     # ✅ Project agents & guidance
└── readme.md                     # ✅ Project overview

File Naming Convention¶

All new documentation files must follow: area-specialty-purpose.md (exactly 3 words)

Examples:

✅ labs-platform-guide.md
✅ terraform-vps-provisioning.md
✅ pipeline-deployment-guide.md
❌ deployment.md (too vague)
❌ kubernetes-deployment-setup-and-testing.md (too many words)

Where to Place:

Root level: Only readme.md, agents.md
Current docs: /documentation/ (new, actively maintained)
Reference: /legacy/documentation/ (archived, read-only)

Documentation Maintenance Policy¶

Foundation Document Updates¶

For changes to protected foundation documents:

Identify the change reason
Bug fix? Architecture improvement? New feature support?
Consult relevant SME personas
Check agents.md for which personas are SMEs
Example: PIPELINE-DEPLOYMENT-GUIDE requires all 5 DevOps SMEs
Create a detailed change summary
What's changing?
Why is it changing?
What will break if we don't change?
What could break from this change?
Get explicit SME approval
Post change proposal to relevant SMEs
Wait for approval before implementing
Document approval in commit message
Update the document
Make the change
Commit with SME approval reference
Example: docs(pipeline): Update deployment timeout (APPROVED: CAPA, CGOA)
Update this policy if needed
If a new protection rule is needed, update this document
If new SME roles are needed, add to agents.md

Non-Foundation Documentation¶

For new documentation files (not the 4 foundation docs):

Follow naming convention: area-specialty-purpose.md
Place in /documentation/ (not root, not legacy)
Get SME review before committing
Link from readme.md if it's discoverable
No deletion without team consensus

Legacy Documentation (Read-Only)¶

Do NOT:

Update files in /legacy/documentation/ or /legacy/wiki/
Delete legacy files (they're part of project history)
Rely on legacy docs for current decisions

Do:

Reference legacy docs when building new systems
Extract useful patterns/configurations
Create NEW docs in /documentation/ with improvements

.gitignore Standards¶

Always untracked (secrets, local, generated):

.env                          # Local environment (contains real secrets)
.kube_config_raw              # Kubernetes config
config/serviceAccountKey.json # Firebase service account
.claude/                       # Claude Code local settings
node_modules/                 # Frontend deps (rebuilt with npm install)
functions/node_modules/       # Function deps (rebuilt with npm install)
scripts/node_modules/         # Script deps (rebuilt with npm install)
build/                        # Vite build output (regenerated)
dist/                         # Build output (regenerated)
*.log                         # Log files
.firebase/                    # Firebase local config
.vite/                        # Vite cache

Always tracked (source control):

package.json, package-lock.json    # Dependency specifications
.env.example                        # Environment template
terraform/                          # IaC code
ansible/                            # Automation code
documentation/                      # All current docs
.github/workflows/                  # CI/CD definitions

Rollback Instructions¶

If any deleted files need to be restored:

# Restore build artifacts
npm run build

# Restore function dependencies
cd functions && npm install

# Restore script dependencies
cd scripts && npm install

# Restore helm binary
brew install helm              # macOS
choco install kubernetes-helm  # Windows

# Check git history for deleted files
git log --diff-filter=D --summary | grep delete

Repository Health Metrics¶

Target state after cleanup:

Metric	Target	Current
Total Size	< 2 GB	~1.5 GB
Untracked Secrets	0	0 ✅
Generated Files in Repo	0	0 ✅
Foundation Docs Protected	4/4	4/4 ✅
Dead Code in /legacy	0 actively used	All archived ✅
CI/CD Workflows	All active	24 workflows ✅

Future Cleanup Checks¶

Schedule: Monthly (1st of month)

# Check for new build artifacts
find . -name "build" -o -name "dist" -o -name ".vite"

# Check for debug logs
find . -name "*.log" -o -name "*.swp" -o -name "*.swo"

# Check for old node_modules outside root
find . -path ./node_modules -prune -o -name "node_modules" -print

# Verify foundation docs still exist
test -f documentation/infra-architecture-complete.md && echo "✅ infra-architecture-complete.md exists"
test -f documentation/infra-backend-setup.md && echo "✅ infra-backend-setup.md exists"
test -f documentation/infra-frontend-setup.md && echo "✅ infra-frontend-setup.md exists"
test -f documentation/pipeline-deployment-guide.md && echo "✅ pipeline-deployment-guide.md exists"

Questions & Escalation¶

If unsure about:

Whether a file should be deleted → Check agents.md for relevant SME, ask before deleting
Whether a doc needs updating → Post to relevant SME persona (see project guidance)
Whether something belongs in /legacy/ → It does if it's not actively used in current deployment

Do not guess. The SME personas in agents.md exist to provide guidance.

Status: ✅ Active Next Review: 2026-03-06 Last Cleanup: 2026-02-06 Cleanup Champion: Claude Code