shopdb-flask/docs/wiki-drafts/README.md

Wiki Page Drafts - 2026-09-11

This directory contains drafted wiki pages based on work completed Q3 2026. Copy these to the GitHub wiki at https://github.com/ge-aero/shopdb-flask/wiki.

New Pages to Create

1. ADR-019: Plugin Dynamic Settings Routes

File: ADR-019-Plugin-Dynamic-Settings-Routes.md
Wiki path: ADRs/ADR-019-Plugin-Dynamic-Settings-Routes
Summary: Documents the get_settings_routes() hook that lets plugins dynamically register settings pages (e.g., Operating Systems in Model Catalog). Fixes lean build failures from hardcoded plugin imports.

Key sections:

• Problem: Hardcoded imports break lean builds
• Decision: Backend hook + frontend dynamic route registration
• Implementation: BasePlugin hook, /api/plugins/settings-routes endpoint, ModelCatalogHub integration
• Benefits: Lean builds work, plugins self-contain UI, runtime flexibility

Related commits: fe09d2745e, d59d0c3194

---

2. Security Audit - September 11, 2026

File: Security-Audit-2026-09-11.md
Wiki path: Security/Security-Audit-2026-09-11
Summary: Comprehensive security review of endpoints plugin, C# agent, and tray app. 4 critical + 6 high vulnerabilities identified. 3 critical fixed, 1 critical planned.

Key findings:

• CRITICAL FIXED: Unauthenticated inventory updates
• CRITICAL FIXED: Hardcoded admin credentials
• CRITICAL FIXED: Collector key exposure in git
• CRITICAL PLANNED: Certificate validation disabled in agent
• HIGH: Password exposure in mcp-servers.json (fixed)
• HIGH: Audit log unbounded growth (planned Q4 2026)
• PERFORMANCE: 99.9% improvement opportunity with delta updates

Risk matrix: 8 critical + 10 high operational risks
Remediation status: 7 of 18 findings fixed or mitigated

---

3. Maintenance Footprint Baseline

File: Maintenance-Footprint-Baseline.md
Wiki path: Operations/Maintenance-Footprint-Baseline
Summary: Baseline assessment of operational burden: 936 hrs/year across database management, deployment, Docker, testing, and security. Identifies 147-205 hrs/year savings via automation.

Key metrics:

• Total burden: 936 hrs/year (23.4 work-weeks)
• Deployment coordination: 312 hrs/year (air-gap burden)
• Database management: 234 hrs/year (audit log retention critical)
• Docker management: 156 hrs/year (log rotation missing)
• Testing/validation: 130 hrs/year (pre-commit automation)
• Security/compliance: 78 hrs/year (scanning + updates)

Automation:

• 13 Claude Code skills created
• 147-205 hrs/year saved (from 936 baseline)
• 7 quick wins identified (4 hours - 6 hours effort each)

Risk matrix: 8 critical + 10 high operational risks

---

4. Architectural Findings - September 11, 2026

File: Architectural-Findings-2026-09-11.md
Wiki path: Architecture/Architectural-Findings-2026-09-11
Summary: Gortex semantic code analysis identified 22 architectural issues (6 critical, 6 high, 10 medium). Focus areas: plugin boundaries, dependency management, schema consistency.

Critical findings:

1. Circular dependencies between plugins (violates ADR-001 isolation)
2. Undeclared import dependencies (plugins import shopdb.core internals)
3. Schema drift (SQLAlchemy models != Alembic migrations)
4. Single points of failure (no HA in production)
5. Migration chain validation gaps (ADR-008 enforcement)
6. Implicit database connection sharing (transaction isolation)

High findings: 7. Frontend plugin import violations (ADR-013) 8. Site literals hardcoded in plugins (ADR-015) 9. Missing error handling on external calls 10. No rate limiting, no API versioning, state management inconsistencies

Remediation timeline: Q4 2026 - Q4 2027

---

Pages to Update

PLUGIN-DEVELOPMENT.md

Add section: "Plugin Settings Routes"

## Plugin Settings Routes

Plugins can extend core settings hubs (Model Catalog, Asset Config, etc.) by declaring routes via the `get_settings_routes()` hook.

### Example: Operating Systems in Model Catalog

```python
class ComputersPlugin(BasePlugin):
    def get_settings_routes(self) -> List[Dict]:
        return [{
            'hub': 'model-catalog',
            'path': 'operatingsystems',
            'name': 'model-catalog-os',
            'tab': 'Operating Systems',
            'component': '.plugins-staged/computers/views/OperatingSystemsList.vue'
        }]

The frontend fetches routes from /api/plugins/settings-routes and registers them dynamically via router.addRoute().

Benefits:

• Lean builds work (no hardcoded plugin imports)
• Plugins self-contain their UI extensions
• Runtime flexibility (enable/disable plugin affects tabs)

Reference: ADR-019 Plugin Dynamic Settings Routes

---

### API-REFERENCE.md
**Add endpoint:** `/api/plugins/settings-routes`

```markdown
## GET /api/plugins/settings-routes

Returns settings routes contributed by all enabled plugins via `get_settings_routes()` hook.

**Auth:** None (jwt-optional, deliberately anonymous for kiosk/TV displays)

**Response:**
```json
{
  "status": "success",
  "data": {
    "routes": [
      {
        "hub": "model-catalog",
        "path": "operatingsystems",
        "name": "model-catalog-os",
        "tab": "Operating Systems",
        "component": ".plugins-staged/computers/views/OperatingSystemsList.vue"
      }
    ]
  }
}

Used by: Settings hub pages (ModelCatalogHub, AssetConfigHub, etc.) to dynamically register plugin tabs.

Reference: ADR-019 Plugin Dynamic Settings Routes

---

### DEPLOYMENT.md
**Add section:** "Air-Gap Deployment Workflow"

```markdown
## Air-Gap Deployment

ShopDB deploys across three air-gapped environments:

Dev PC (gitea) <--USB--> Work PC (GitHub) <--USB--> Production VM

### Bundle Creation

```bash
# On work PC
cd C:\Users\270015376\Documents\github\flask-shopdb
./pull-shopdb-bundle.cmd  # Creates tarball for transfer

Deployment to Production

# On production VM
tar -xzf shopdb-deploy-20260911.tar.gz
docker compose exec api flask db upgrade
docker compose exec api flask plugin upgrade-all
docker compose restart api

Automation: /full-deploy skill orchestrates complete workflow (saves 50-100 hrs/year)

Reference: Maintenance-Footprint-Baseline.md (deployment coordination: 312 hrs/year baseline)

---

### CONTRIBUTING.md
**Add section:** "Optimized Pre-Commit Checks"

```markdown
## Pre-Commit Checks

Run before every commit:

```bash
bash scripts/check-naming-and-style.sh
pytest tests/ -x

Performance: Script optimized 2026-09-11 for 5x faster execution:

• Before: 5-10 seconds (scans all files on disk)
• After: 1-2 seconds (scans only tracked files via git ls-files)

Override: Set USE_GIT_LS_FILES=0 to use legacy grep-based scanning:

USE_GIT_LS_FILES=0 bash scripts/check-naming-and-style.sh

Enforcement: Violations block CI builds (GitHub Actions)

Commit: 4943e182c3 - Optimize check-naming-and-style.sh

---

### TESTING.md
**Add section:** "Gate Tests"

```markdown
## Gate Tests

Gate tests validate generated documentation and API consistency:

- `tests/test_openapi_spec.py` - OpenAPI spec completeness
- `tests/test_public_read_surface.py` - Public endpoint security
- `tests/test_authz.py` - Authorization decorators
- `tests/test_plugin_migrations.py` - Migration chain validation (ADR-008)

**Important:** When you add/modify API endpoints, regenerate docs:

```bash
# Update docs/openapi.json to reflect new endpoints
# (Manual until docs/api-inventory.json exists)
git add docs/openapi.json

Enforcement: scripts/check-gates-ran.sh verifies gates actually ran (not skipped)

CI failure: "Gate tests FAILED" means docs are stale or missing

---

### SECURITY.md (create if doesn't exist)
**New page content:**

```markdown
# Security Guidelines

## Configuration File Security

**Never commit personal configuration files:**

```bash
# These MUST be in .gitignore
.claude/settings.json
.claude/settings.local.json
.claude/mcp-servers.json

Why: Personal config files may contain:

• Plain-text MySQL passwords
• VM SSH credentials
• API keys and collector tokens
• Personal authentication tokens

Incident: 2026-09-11 - Passwords exposed in .claude/mcp-servers.json committed to GitHub

• Fixed: Removed from git tracking, added to .gitignore
• Impact: Dev environment credentials only (not production)

Reference: Security-Audit-2026-09-11.md Finding #6

Credential Patterns

Pre-commit hook scans for these patterns:

• shopdb_pat_* - Collector API keys
• password = "..." - Hardcoded passwords
• mysql://user:pass@host - Database URLs with credentials

If blocked: Replace hardcoded credentials with environment variables or config files

ADR-016: Credential Delivery

Production credentials delivered via:

• Device tokens (for endpoints/agents)
• Personal Access Tokens (for users)
• Environment variables (for services)

Never: Hardcoded in source, registry keys, git history

---

## New Page: Automation & Skills
**File:** Create new wiki page  
**Wiki path:** `Operations/Automation-Skills`

```markdown
# Automation Skills

Claude Code skills created Q3 2026 for common workflows. Save 147-205 hrs/year from 936 hrs baseline.

## Available Skills

### Pre-Commit Validation
**Command:** `/pre-commit`  
**What it does:** Runs pytest, check-naming-and-style.sh, security-scan, migration-check  
**Savings:** 26 hrs/year  
**When to use:** Before every commit

### Docker Rebuild
**Command:** `/docker-rebuild`  
**What it does:** Full Docker rebuild (prebuilt and standard), tests, restarts services  
**Savings:** 26 hrs/year  
**When to use:** After dependency changes (requirements.txt, package.json)

### Agent Deployment
**Command:** `/agent-deploy-full`  
**What it does:** Build C# agent, deploy to VM via SSH, verify service, test heartbeat  
**Savings:** 26 hrs/year  
**When to use:** After agent code changes

### Migration Check
**Command:** `/migration-check`  
**What it does:** Validates plugin migration chains (ADR-008), checks PLUGIN_TABLE_OWNERS order  
**Savings:** 13 hrs/year  
**When to use:** Before adding new migrations

### Production Health
**Command:** `/production-health`  
**What it does:** System health checks (containers, API, DB, disk space, endpoints)  
**Savings:** 52 hrs/year  
**When to use:** Daily monitoring, after deploys

### Security Scan
**Command:** `/security-scan`  
**What it does:** Scans for hardcoded credentials, exposed keys, missing auth, SQL injection  
**Savings:** 13 hrs/year  
**When to use:** Before commits, after security reviews

### VM Snapshot Management
**Command:** `/vm-snapshot create "description"`  
**What it does:** Creates/restores/lists Hyper-V VM snapshots  
**Savings:** 52 hrs/year  
**When to use:** Before risky changes, deploys, testing

### Full Deployment
**Command:** `/full-deploy`  
**What it does:** Complete deployment workflow (validation, bundle, deploy, verification)  
**Savings:** 152 hrs/year  
**When to use:** Production deployments across air gap

### Plugin Scaffolding
**Command:** `/plugin-new "name" "description"`  
**What it does:** Generates complete plugin structure (BasePlugin, models, API, frontend, tests)  
**Savings:** 15 hrs/year  
**When to use:** Starting new plugins

## Total Savings

| Category | Baseline (hrs/yr) | With Skills (hrs/yr) | Savings |
|----------|-------------------|----------------------|---------|
| Pre-commit validation | 52 | 26 | 26 |
| Docker management | 52 | 26 | 26 |
| Agent deployment | 52 | 26 | 26 |
| Migration validation | 26 | 13 | 13 |
| Production monitoring | 104 | 52 | 52 |
| Security scanning | 26 | 13 | 13 |
| VM snapshots | 78 | 26 | 52 |
| Full deployment | 312 | 160 | 152 |
| Plugin scaffolding | 30 | 15 | 15 |
| **TOTAL** | **732** | **357** | **375** |

Note: Realistic savings are 147-205 hrs/year due to task overlap.

**Reference:** Maintenance-Footprint-Baseline.md

---

Summary

4 new wiki pages drafted:

1. ADR-019: Plugin Dynamic Settings Routes (architectural decision)
2. Security Audit 2026-09-11 (4 critical + 6 high findings)
3. Maintenance Footprint Baseline (936 hrs/year burden, automation opportunities)
4. Architectural Findings 2026-09-11 (22 findings from Gortex analysis)

7 existing pages need updates:

1. PLUGIN-DEVELOPMENT.md (add get_settings_routes() docs)
2. API-REFERENCE.md (add /api/plugins/settings-routes endpoint)
3. DEPLOYMENT.md (add air-gap workflow)
4. CONTRIBUTING.md (add optimized pre-commit checks)
5. TESTING.md (add gate tests explanation)
6. SECURITY.md (create new page for credential security)
7. Automation-Skills.md (create new page for skill catalog)

Total effort to publish: ~2 hours (copy-paste to wiki, adjust formatting, add navigation links)

---

Next Steps

1. Review drafts for accuracy (have I missed anything?)
2. Copy to GitHub wiki at https://github.com/ge-aero/shopdb-flask/wiki
3. Update wiki navigation/sidebar to include new pages
4. Link related pages (ADRs reference each other, operations pages link to security audit, etc.)
5. Notify team of new documentation

---

Related Memory Files

These wiki pages are based on memory files in .claude/memory/:

• security_audit_2026_09_11.md
• maintenance_footprint_baseline.md
• architectural_analysis_gortex_2026_09_11.md
• security_fix_implementation.md
• workflow_patterns.md
• repository_structure.md

Memory files are more detailed; wiki pages are summaries for broader audience.