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
• Constraints as implemented: Model Catalog is the only hub that draws plugin tabs, the tabs are not deep-linkable, and the component is bound at build time

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().

Rules for declaring one

1. Declare hub: 'model-catalog' or declare nothing. Model Catalog is the only hub whose page registers plugin tabs. A route naming any other hub (asset-config, security, network, ...) is dropped by the API with an error in the log, because nothing would draw it. For a settings page that belongs elsewhere, own a full page in plugins/<name>/frontend/routes.js instead: it is statically registered and behaves like any other route.
2. Your frontend must be staged into the build. component is a path relative to frontend/src, so it must be the staged copy - .plugins-staged/<name>/views/X.vue, made by scripts/stage-frontend.mjs from plugins/<name>/frontend/views/X.vue. Enabling the plugin at runtime does not put the file in a bundle that was built without it; that needs a frontend rebuild.
3. Register the page in your routes.js too, and treat that as the real route. The hub's import of your component is not rewritten by Vite (no static file extension in the template), so it resolves under npm run dev and 404s in a production build. The tab is a convenience on top of a normal plugin route, not a way to ship a page. A gate test enforces this.
4. Do not link directly to your tab's URL. The hub registers the route when it mounts, so the URL only resolves for someone who reached it through the hub. A bookmark, a link in an email, or a refresh on the tab lands nowhere.

Benefits:

• Lean builds work (no hardcoded plugin imports)
• Plugins self-contain their UI extensions
• Enable/disable changes the tabs, for a plugin already in the build

Reference: ADR-019 Plugin Dynamic Settings Routes, section "Constraints as implemented"

---

### 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. A route naming a hub that does not draw plugin tabs is dropped, with an error in the server log naming the plugin and the hub.

**Auth:** `settings.view` (it names the enabled plugins, the hub layout and the internal component paths; no pre-login page calls it)

**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: ModelCatalogHub, to register plugin tabs. It is the only hub page that does; the others draw their own tabs only.

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.