hub/docs/DOC_MAINTENANCE.md

Documentation Maintenance Strategy

Last Updated: 2025-11-18

Purpose

This guide explains how to keep documentation current as the codebase evolves.

---

Documentation Structure

/
├── SYSTEM_ARCHITECTURE.md          ← Master guide (update when patterns change)
├── VERSIONING_AND_AUDITING.md      ← Quicksave and auditing reference
├── CLAUDE.md                       ← Quick reference for common mistakes
├── CONTRIBUTING.md                 ← Git workflow
│
├── docs/
│   ├── supplements/                ← Deep-dive implementation guides
│   │   ├── analytics.md
│   │   ├── permissions.md
│   │   ├── departments.md
│   │   ├── processing.md
│   │   ├── batch-system.md
│   │   ├── precognition.md
│   │   ├── performance.md
│   │   └── horizon.md
│   │
│   ├── features/                   ← Feature-specific documentation
│   │   ├── NOTIFICATIONS.md
│   │   ├── REAL_TIME.md
│   │   ├── PARENT_COMPANY_SUBDIVISIONS.md
│   │   └── BATCH_SYSTEM.md
│   │
│   ├── architecture/               ← Technical design docs
│   │   ├── URL_STRUCTURE.md
│   │   ├── DATABASE.md
│   │   ├── DATABASE_STRATEGY.md
│   │   ├── API.md
│   │   ├── MEDIA_STORAGE.md
│   │   └── MEDIA_STORAGE_QUICK_REFERENCE.md
│   │
│   ├── deployment/                 ← DevOps and infrastructure
│   │   ├── CI_CD.md
│   │   └── KUBERNETES.md
│   │
│   ├── development/                ← Developer setup guides
│   │   └── (future: LOCAL_DEV.md, DOCKER.md, SETUP.md)
│   │
│   └── archive/                    ← Old/deprecated docs (for reference only)

---

When to Update Documentation

✅ Update SYSTEM_ARCHITECTURE.md When:

1. New architectural pattern is introduced

   • Example: Adding a new scoping trait, new middleware pattern
   • Update: Relevant section in SYSTEM_ARCHITECTURE.md

2. Module system changes

   • Example: Adding has_new_module flag
   • Update: Section 2 "Permission & Module System"

3. Security pattern changes

   • Example: New authorization check pattern
   • Update: Section 5 "Security Patterns"

4. New critical technology added

   • Example: Adding Meilisearch for search
   • Update: "Technology Stack" section

5. Department system changes

   • Example: New tier of department access
   • Update: Section 3 "Department System"

6. Data model relationships change significantly

   • Example: Major refactor of how orders relate to businesses
   • Update: Section 11 "Data Models & Relationships"

✅ Update Supplement Docs When:

• analytics.md - Changes to tracking, campaign system, engagement scoring
• permissions.md - RBAC changes, new roles, impersonation updates
• departments.md - Department workflow changes, new capabilities
• processing.md - Processing operations, conversion types, yields
• batch-system.md - Batch management, inventory settings
• precognition.md - New form components, validation patterns
• performance.md - New caching strategies, indexing patterns
• horizon.md - Queue configuration, deployment changes

✅ Create New Feature Docs When:

• Building a new major feature (e.g., NOTIFICATIONS.md, REAL_TIME.md)
• Feature has its own UI, controllers, and workflows
• Put in docs/features/
• Reference from SYSTEM_ARCHITECTURE.md Section 14

❌ DON'T Document:

• Bug fixes - Git commits track these
• Small UI tweaks - Not architectural
• Temporary workarounds - Will be removed
• Feature additions - Git commits describe features

---

How to Update Documentation

Step 1: Identify What Changed

Ask yourself:

• Is this a new pattern that developers need to follow?
• Does this change how the system works?
• Would a new developer need to know this?

If YES → Update docs If NO → Just commit to git

Step 2: Find the Right Doc

Use this decision tree:

Is it about HOW the system works (patterns, architecture)?
├─ YES → Update SYSTEM_ARCHITECTURE.md
└─ NO ↓

Is it a deep implementation detail for a specific module?
├─ YES → Update relevant supplement (docs/supplements/)
└─ NO ↓

Is it a new feature with its own workflows?
├─ YES → Create feature doc (docs/features/)
└─ NO ↓

Is it database design or URL routing?
├─ YES → Update architecture doc (docs/architecture/)
└─ NO ↓

Is it deployment/DevOps?
├─ YES → Update deployment doc (docs/deployment/)
└─ NO ↓

Don't document it - use git commit message instead

Step 3: Update the Doc

For SYSTEM_ARCHITECTURE.md:

• Update the relevant section
• Update "Last Updated" date at top
• Update "Last major update" at bottom if significant

For supplement docs:

• Update specific sections
• Add "Last Updated" date if doesn't exist

For new docs:

• Follow existing format
• Add to appropriate directory
• Reference from SYSTEM_ARCHITECTURE.md Section 14

Step 4: Update References

If you created a new doc or moved content:

• Update SYSTEM_ARCHITECTURE.md Section 14 references
• Update CLAUDE.md if it's a critical pattern
• Add to relevant README if exists

---

Documentation Review Cadence

Monthly Review (First of Month)

Check:

• Is SYSTEM_ARCHITECTURE.md still accurate?
• Are module flags up to date?
• Are technology stack listings current?
• Do code examples still work?

Action:

• Review recent PRs for architectural changes
• Update outdated sections
• Archive deprecated docs

After Major Features

When merging a major feature branch:

1. Check if SYSTEM_ARCHITECTURE.md needs updates
2. Consider if new supplement doc needed
3. Update relevant existing docs

Before Onboarding New Developers

1. Read SYSTEM_ARCHITECTURE.md top to bottom
2. Fix any outdated information
3. Update examples if patterns changed
4. Ensure supplement docs are current

---

Common Maintenance Tasks

Adding a New Module Flag

1. Update SYSTEM_ARCHITECTURE.md:

   • Section 2: Add to "PREMIUM MODULES" list
   • Include description, controllers, see references

2. Update migration (in code)

3. Update Business model trait (in code)

4. Update blade directives (in code)

Changing a Core Pattern

Example: New way to scope departments

1. Update SYSTEM_ARCHITECTURE.md:

   • Section 3: Update "Data Filtering Pattern"
   • Section 11: Update "Critical Query Patterns"

2. Update supplement if relevant:

   • docs/supplements/departments.md

3. Add to "Common Mistakes to Avoid" if error-prone

Deprecating Old Patterns

1. Mark as deprecated in SYSTEM_ARCHITECTURE.md:

   **⚠️ DEPRECATED:** Use new pattern instead
   

2. Move full details to docs/archive/

3. Update CLAUDE.md to reference new pattern

4. Add migration path in deprecation notice

---

Documentation Quality Checklist

Before considering docs "done":

• SYSTEM_ARCHITECTURE.md is 100% accurate to current codebase
• All module flags are documented
• Technology stack matches composer.json
• Code examples actually work (tested)
• Security patterns are clearly explained
• Common mistakes section is up to date
• Supplement docs match their modules
• CLAUDE.md points to SYSTEM_ARCHITECTURE.md
• Old docs are in archive/
• No duplicate documentation exists

---

Tools for Keeping Docs Current

Git Hooks (Future Enhancement)

Consider adding a pre-commit hook that reminds:

# If migration file changed
echo "⚠️  Migration changed - update docs/architecture/DATABASE.md if schema changed"

# If middleware changed
echo "⚠️  Middleware changed - check SYSTEM_ARCHITECTURE.md Section 5"

PR Template (Future Enhancement)

Add to PR template:

## Documentation Updates

- [ ] Updated SYSTEM_ARCHITECTURE.md (if architectural change)
- [ ] Updated relevant supplement docs
- [ ] Created feature doc (if new major feature)
- [ ] No documentation needed (just bug fix/small change)

Documentation Audit Script (Future Enhancement)

Create a script to check:

• Are all composer packages listed in Technology Stack?
• Are all module flags documented?
• Are all middleware documented?
• Are all custom traits documented?

---

Questions to Ask

When in doubt about documentation:

1. Would a new developer need to know this?

   • YES → Document it
   • NO → Skip it

2. Is this a pattern that will be repeated elsewhere?

   • YES → Add to SYSTEM_ARCHITECTURE.md
   • NO → Just use clear code comments

3. Does this change how the system fundamentally works?

   • YES → Update architecture docs immediately
   • NO → Consider if it needs docs at all

4. Will this pattern cause bugs if misunderstood?

   • YES → Add to "Common Mistakes to Avoid"
   • NO → May not need docs

---

Summary: The Golden Rule

Document the PATTERNS, not the FEATURES.

Git handles feature tracking. Docs handle architectural knowledge.

Keep SYSTEM_ARCHITECTURE.md as the single source of truth for HOW the system works.

---

Contacts

Questions about documentation structure?

• Review this guide first
• Check SYSTEM_ARCHITECTURE.md
• Ask in team chat if still unclear

---

This is a living document. Update when documentation practices evolve.