# Architectural Findings - September 11, 2026 > **Read with the date on it.** This is a point-in-time audit, kept as the > record of what was found and what it turned out to be, not as current > guidance. One thing it says repeatedly is no longer true: it was written when > this line carried no ADRs, and the full ADR set now lives beside it in > [docs/adr](../adr/README.md). Where this page says a decision record is > missing or lives elsewhere, look there first. **Scope:** Full codebase analysis via Gortex semantic code intelligence **Original severity claim:** 22 findings (6 critical, 6 high, 10 medium) **Status:** RE-CHECKED against the deployment branch at 35d4fcd41 on 2026-09-18. Most of the original findings do not survive a read of the code. This page keeps them, with the verdict and the evidence, so nobody acts on a claim that was never true. ## How to read this page (added 2026-09-18) The September 11 analysis was written from semantic queries, not from reading the files it names. Eight of its claims cite code that does not exist on this branch: a `machines` plugin that imports `computers`, a migration that spells a column `last_reported_date`, a ServiceNow plugin, `MACHINE_TYPES = ['Lathe', 'Mill', 'CNC']`, a hardcoded `['Bldg 300', 'Bldg 400']`, Vuex, an absent CSP header, an unhandled `requests.post`. Each of those was grepped for on 2026-09-18 and returns nothing. Every finding below now carries one of four verdicts: - **REFUTED** - the cited code does not exist, or the opposite is in the tree. - **STALE** - it was true once; the tree has since fixed it. - **HOLDS (narrowed)** - something real is there, but smaller or different than the original text claims. - **UNVERIFIED** - cannot be settled from this repository. Effort and priority numbers in the original text were estimates with no stated basis. They are left where they sit for findings that still hold and struck where the finding does not. ## Critical Findings (P0) ### 1. Circular Dependencies Between Plugins **Verdict: REFUTED as stated. HOLDS (narrowed) as a deferred-import coupling.** **Original claim:** `computers` imports `machines` and `machines` imports `computers`; import errors at runtime if plugins load in the wrong order; 25+ violations. **What the code shows (2026-09-18):** - `grep -rn "^from plugins\." plugins/ --include=*.py` returns **nothing**. There is not one module-level cross-plugin import in the tree, so there is no load-order failure mode and no import cycle at import time. - `grep -rn "from plugins.computers" plugins/machines/` returns **nothing**. The `machines` plugin does not reference `computers` at all, so the cycle the finding is built on does not exist. - 52 cross-plugin imports do exist, and every one of them is inside a function body, resolved on call. `plugins/computers/plugin.py:414` and `:1166` reach `plugins.machines.models` that way; `plugins/endpoints/api/routes.py:235` and fourteen more reach `plugins.computers.models`. **What is actually there:** a mutual reference pair between `computers` and `endpoints`, both deferred: - `plugins/computers/api/policy_routes.py:44` imports `plugins.endpoints.commands.elevated_permission_for`, unguarded. - `plugins/endpoints/commands.py:477` imports `plugins.computers.services.policyresolver.effective_policy_for`, wrapped in `try/except` that falls back to the base allowlist (`commands.py:475-481`). So one side of that pair degrades when its partner is absent and the other raises. The same asymmetry appears at `plugins/endpoints/api/agentauth.py:118`, where `resolve_hostname` imports `plugins.computers.models.Computer` with no guard: an endpoints-without- computers site fails there rather than returning "unknown hostname". **What to do instead of the original remediation:** nothing about load order. The open question is narrower and worth one pass: decide whether a deferred cross-plugin import must be guarded, and guard the unguarded ones. A linter rule banning `plugins.*` imports outright would break the working policy and enrollment paths listed above, which are the product's actual design. ### 2. Undeclared Import Dependencies **Verdict: REFUTED.** **Original claim:** 18 plugins import `shopdb.core.models`, 12 import `shopdb.core.utils`, 7 import `shopdb.core.services`. **What the code shows:** `grep -rn "from shopdb\.\(core\|utils\|extensions\|services\)" plugins/ --include=*.py` returns **0 hits**. Not one plugin deep-imports core. The only `shopdb.*` import in `plugins/` outside `shopdb.api` is `shopdb.plugins.alembic_template` from migration `env.py` files, which is the shared Alembic runner ADR-008 sanctions. ADR-001's rule that `shopdb.api` is the only core surface a plugin may import is being kept. The thing that is NOT enforced is raw SQL against core tables: see finding 3a below. ### 2a. Raw SQL against core tables from a plugin (added 2026-09-18) **Verdict: HOLDS (new, narrow).** `plugins/computers/plugin.py:2080-2091` runs `db.session.execute(db.text(...))` joining core `assets`, `assetrelationships` and `assettypes` inside the `flask computers retype` CLI command. `Asset`, `AssetType`, `AssetRelationship` and `RelationshipType` are all exported from `shopdb.api` (`shopdb/api/__init__.py:47-48`, `:424`, `:438-439`), so no missing export excuses it, and `plugins/endpoints/api/routes.py:3981-3986` is the same pattern already corrected for `BusinessUnit`. The contract note at `shopdb/__init__.py:135-142` names the reason: a raw query is coupling to the core schema that no contract bump can catch. Blast radius: one admin CLI command, no serving route. Import rule not literally broken. Worth fixing because it is the kind of thing that gets copied. ### 3. Schema Drift: Models vs Migrations **Verdict: REFUTED as stated. HOLDS (narrowed) to one column.** **Original claim:** `Computer.lastreporteddate` in the model but `last_reported_date` in the migration; `Printer.driver` with no migration; `AssetRelationship.label` in a migration but not the model; 14 tables affected. **What the code shows:** - `grep -rn "last_reported_date" --include=*.py .` returns **nothing**. The model spells it `lastreporteddate` (`plugins/computers/models/computer.py:85`) and so does every migration. - `grep -rPn "sa\.Column\(\s*'[a-z]+_[a-z_]+'" plugins/*/migrations/versions/*.py migrations/versions/*.py` returns **nothing**. There is no snake_case column name in any migration in the tree. - There is no `shopdb/models/` directory to hold the claimed `AssetRelationship.label`; core models live under `shopdb/core/`. **The one real instance:** `plugins/notifications/models/notification.py:158` declares `alertscope = db.Column(db.JSON, nullable=True)` while the migration that creates it, `plugins/notifications/migrations/versions/0006_add_fleet_alerts.py:45`, creates `sa.Column('alertscope', sa.Text, nullable=True)` and its own docstring at line 8 calls it "the alertscope TEXT field (JSON string)". Commit f484be8a3 fixed the two neighbouring columns to agree with 0006 and left this one. Nothing breaks on MySQL 8 - the SQLAlchemy JSON type serialises into TEXT and reads back - and consumers already normalise both shapes (`plugins/endpoints/api/routes.py:4011-4020`). The cost is that the model is not a true description of the deployed column, which is what autogenerate reads. **Related gap that is real:** the naming gate cannot see migrations at all. `scripts/check-naming-and-style.sh:236` greps `^\s+[a-z]+_[a-z_]+\s*=\s*db\.Column`, which only matches a model attribute assignment; migrations write `sa.Column('name', ...)` with the name as a positional string. That is how the shipped build of `plugins/endpoints/migrations/versions/0021_client_certificates.py` created `client_cert_fingerprint`, `cert_issued_at` and `cert_expires_at` and passed the gate (`git show 5cd533239:plugins/endpoints/migrations/versions/0021_client_certificates.py`, lines 20-28). The tree is conformant today, because 0021 and 0022 are now no-ops and 0023 renamed the survivor; the gate simply would not notice the next one. ### 4. Single Points of Failure **Verdict: UNVERIFIED from this repository, and partly STALE.** Replication, load balancing and orchestration are properties of the reference site deployment, not of this tree, so nothing here can confirm or deny them. Two parts of the original text are wrong about what the repo ships: - Restart policy is configured, not absent: `docker-compose.yml:24`, `:104` and `:120` set `restart: unless-stopped`, and three services carry `healthcheck:` blocks (`:38`, `:112`, `:219`). - Backups are no longer "manual mysqldump weekly, stored on the same server". See finding 4a. The underlying point - one database, one app host, air gap limits the options - is a statement about the site, and belongs in a deployment document rather than a code findings page. The 200+ hour estimate has no basis in anything measured. ### 4a. Backups (added 2026-09-18, correcting the original text) **Verdict: STALE. The repo ships a backup system.** `scripts/backup/` contains `backup.sh`, `restore.sh`, `status.sh`, `watch.sh`, `simulate-restore.sh` and `test-restore-datarev.sh`. Retention is enforced by restic (`scripts/backup/backup.sh:134-141`: `--keep-daily 5 --keep-weekly 4 --keep-monthly 6 --prune`), destinations include SMB and S3 as well as local (`scripts/backup/README.md`), each set carries `manifest.json` with schema revisions for compatibility checking, and restore runs from the Settings > Backups UI with a schema compatibility check. A restore-simulation harness is in the tree. ### 5. Plugin Migration Chain Validation Gaps **Verdict: STALE as written, and the credited fix is the wrong artifact.** Validation is in the test suite, in this repository, and has been for longer than the `/migration-check` skill: `tests/test_plugin_migrations.py` holds nine tests covering owners-versus-models, chain shape, no-op anchors and idempotency, and pins each chain's head in `EXPECTED_HEAD_REVISION` (`tests/test_plugin_migrations.py:125`). `tests/test_plugins/test_endpoints_credentials_migration.py` runs the 0020-0023 chain twice from both a legacy and a fresh schema, plus downgrade and re-upgrade. The endpoints chain today is 24 revisions with one root and one head and no dangling `down_revision`. The branch example in the original text (`003_add_policies.py` with `down_revision=001`) is invented; no such file exists under `plugins/computers/migrations/versions/`, which holds 6 revisions. **The real gap, which the original text missed:** no test asserts that a plugin chain touches only the tables it owns. `plugins/endpoints/migrations/versions/0023_endpoint_credentials.py` declares `plugin_name = 'endpoints'` (line 33) and then runs `op.drop_index(..., table_name='assets')` at line 73 and `op.drop_column('assets', column)` at line 76 against the core `assets` table, cleaning up after the shipped 0021 which had added those columns from the same plugin chain. `assets` is not, and cannot be, in `PLUGIN_TABLE_OWNERS['endpoints']` (`shopdb/plugins/alembic_template.py:57-63`), so the metadata ownership filter never saw it. Every step is guarded on the live schema and the forward direction is clean, so nothing is broken; nothing stops the next one either. ### 6. Implicit Database Connection Sharing **Verdict: REFUTED as a blanket claim.** Savepoints are in use where concurrency actually bites: `plugins/endpoints/plugin.py:1318`, `:1387` and `:1692` all wrap work in `with db.session.begin_nested():`, and the application-delta path reconciles a unique-constraint collision inside that savepoint rather than sinking the check-in. The original text's example - a printers rollback silently discarding a computers write in the same request - is not backed by any cited call site, and none was found. A per-plugin transaction policy is still not written down anywhere. That is a documentation item for PLUGIN-DEVELOPMENT.md, not a critical data-integrity finding. ## High Priority Findings (P1) ### 7. Frontend Plugin Import Violations **Verdict: STALE. Enforced and passing.** `scripts/check-naming-and-style.sh` runs "Checking for cross-plugin / escaping imports in plugin frontends" and the whole script exits 0 on this branch. The established pattern is a core component consumed through the `@/` alias: 97 plugin frontend files already import that way, and the kiosk allowlist editor added in this range follows it (`frontend/src/components/NetworkAllowlistPicker.vue`, consumed at `plugins/usb/frontend/views/USBSettings.vue:108` and `plugins/printedparts/frontend/views/PrintedPartsSettings.vue:164`). ### 8. Hardcoded Site Literals in Plugins **Verdict: REFUTED as stated. HOLDS (narrowed) as a gate coverage gap.** `grep -rn "MACHINE_TYPES" . --include=*.py` and `grep -rn "Bldg 300\|Bldg 400" . --include=*.py` both return **nothing**. The ADR-015 block in `scripts/check-naming-and-style.sh:392-462` runs and passes, and a control pattern over the same directories returns 1995 lines, so the pipeline is not vacuous. **The narrowed finding:** the ADR-015 scan is scoped at `scripts/check-naming-and-style.sh:436-440` to `plugins/ shopdb/ scripts/ deploy/ frontend/src/ tools/` with `--include` on `.py/.vue/.js/.ps1/.psm1/.sh/.iss/.json/.html`. `agent/` is not in that list and `.cs` is not an included extension, so roughly 2,500 lines of C# added in this range - `AgentCredentials.cs`, `AgentHttpFactory.cs`, `EnrollmentService.cs`, `AgentPipeServer.cs`, `ProtectedFileSystem.cs`, `StrictModePreamble.cs`, plus `agent/appsettings.json` - ship to a sister site unscanned. Re-running the assembled site patterns by hand over `agent/` (excluding bin/obj) finds one hit, prose in `agent/ShopDbEndpointAgent/ShopDbEndpointAgent.csproj:108`, which ADR-015 permits. The tree is clean; the gate would not notice if it stopped being clean. Note this is a gap in ADR-015's own stated scope, not a breach of it: the 2026-08-14 amendment names those six directories. ### 9. Missing Error Handling on External Calls **Verdict: REFUTED.** The plugins the finding names do not exist. `ls plugins/` gives: applications, backups, computers, employees, endpoints, geenforce, guides, knowledgebase, machines, measuringtools, network, notifications, printedparts, printers, slides, tools, usb, warranty. There is no ServiceNow plugin, no LDAP sync plugin and no email plugin; mail is core (`shopdb/utils/mailer.py`). Every outbound HTTP call in the tree carries a timeout and an exception handler: - `plugins/warranty/services/providers.py:129` and `:157` - `timeout=HTTP_TIMEOUT`, `except requests.RequestException` raising `WarrantyLookupError`. - `plugins/printers/services/zabbix_service.py:95` and `:126` - `timeout=self.REACHABLE_TIMEOUT` / `self.API_TIMEOUT`, caught. - `shopdb/utils/mailer.py:238` - `timeout=10`, caught, returns `(False, error)` and never raises. ### 10-12. Additional High Findings The original text deferred these to a memory file rather than citing code: "inconsistent permission checking across plugins", "plugin state leakage via module-level globals", "missing database connection pool tuning". The third is REFUTED. The pool is sized on purpose and env-driven: `shopdb/config.py:20-22` (`DB_POOL_SIZE` 10, `DB_MAX_OVERFLOW`, `DB_POOL_TIMEOUT` 5) and `:48-72`, with the reasoning for the non-default `pool_timeout` written in place, and `docker-compose.yml:172-193` documents the `workers x (pool_size + max_overflow)` arithmetic against MySQL's `max_connections`. The other two were not re-checked, because neither cites a file. They should be restated with a file:line or dropped. ## Medium Priority Findings (P2) ### 13. No Rate Limiting on API Endpoints **Verdict: HOLDS (narrowed). Login is limited; two kiosk surfaces are not.** Login rate limiting exists and is not "planned Q1 2027": `shopdb/core/api/auth.py:35` `_login_ratelimited()`, keyed per host at `:52`, applied at `:80`, with `tests/test_core/test_auth_ratelimit.py` over it. Enrollment has its own limiter (`plugins/endpoints/api/ratelimit.py`, 300 per 60 seconds per IP applied at `plugins/endpoints/api/enrollment.py:306`). What has none: the USB kiosk routes. `grep` for `limiter` or `ratelimit` across `plugins/usb/` returns nothing, while `plugins/usb/api/selfhosted.py:346-371` resolves a posted badge to an employee name and returns it. That is an unauthenticated, unthrottled badge-to-name lookup for any caller inside the configured kiosk CIDRs. Both limiter counters live in per-process `SimpleCache` (`plugins/endpoints/api/ratelimit.py:10-11`), so at the shipped four gunicorn workers the effective budget is four times the configured maximum. ### 14. Frontend State Management Inconsistencies **Verdict: REFUTED.** `grep -rn "vuex" frontend/src/` returns **nothing**, and `frontend/package.json:28` declares `"pinia": "^2.1.0"`. There is no Vuex-versus-Pinia split to standardise. ### 15. No API Versioning **Verdict: HOLDS.** `grep -rn "api/v1" shopdb/ --include=*.py` returns nothing; every route is mounted under `/api/`. This is a v1.0 decision, not a defect, and ADR-002 already carries the versioning story for the plugin contract. The 60-hour estimate has no stated basis. ### 16-22. Additional Medium Findings Re-checked on 2026-09-18: - **No content security policy headers: REFUTED as stated.** `shopdb/__init__.py:340` sets `Content-Security-Policy: frame-ancestors 'self'` on every response, plus `X-Content-Type-Options`, `X-Frame-Options` and `Referrer-Policy` at `:334-337`; uploads carry a stricter `default-src 'none'; sandbox` (`shopdb/utils/uploads.py:13`), pinned by `tests/test_core/test_security_headers.py`. The accurate, narrower statement is that there is no `script-src` policy, and the code says so in place and says why. - **Missing health check endpoints: REFUTED.** `shopdb/core/api/dashboard.py:318` is `GET /api/dashboard/health`. - **Database connection pool too small: REFUTED.** See 10-12 above. - **No request ID tracing: HOLDS.** No request-id plumbing was found in `shopdb/__init__.py`. - **No structured logging format: not re-checked.** - **Plugin discovery relies on a filesystem scan: HOLDS, by design.** ADR-003 decides filesystem discovery under `plugins/`. "Slow" was never measured. - **Frontend bundle size 2.1MB: UNVERIFIED.** No build was run for this page. ## Remediation Priority (revised 2026-09-18) | Finding | Verdict | What is actually left to do | |---------|---------|------------------------------| | Circular plugin dependencies | REFUTED / narrowed | Decide whether deferred cross-plugin imports must be guarded; guard `agentauth.py:118` and `policy_routes.py:44` | | Undeclared core imports | REFUTED | Nothing | | Schema drift | REFUTED / narrowed | Align `notification.py:158` with migration 0006; teach the naming gate to read `sa.Column('...')` | | Plugin chain touches core tables | HOLDS (new) | Add a test that a plugin chain writes only owned tables | | Migration chain validation | STALE | Nothing; `tests/test_plugin_migrations.py` is the gate | | Implicit DB session sharing | REFUTED | Document the transaction pattern in PLUGIN-DEVELOPMENT.md | | Frontend plugin imports | STALE | Nothing; gate passes | | Site literals in plugins | REFUTED / narrowed | Extend the ADR-015 scan to `agent/` and `.cs` | | Missing external-call error handling | REFUTED | Nothing | | Rate limiting | HOLDS (narrowed) | Throttle the USB kiosk badge lookup; decide whether per-process counters are acceptable at 4 workers | | Vuex/Pinia split | REFUTED | Nothing | | API versioning | HOLDS | v1.0 decision | | Single points of failure | UNVERIFIED | Belongs in a deployment document | ## Testing Performed (2026-09-18 re-check) ```bash # Every claim above was checked with a grep or a read on the deployment branch at 35d4fcd41. grep -rn "^from plugins\." plugins/ --include=*.py # 0 hits grep -rn "from shopdb\.\(core\|utils\|extensions\|services\)" \ plugins/ --include=*.py # 0 hits grep -rPn "sa\.Column\(\s*'[a-z]+_[a-z_]+'" \ plugins/*/migrations/versions/*.py migrations/versions/*.py # 0 hits grep -rn "MACHINE_TYPES\|Bldg 300\|Bldg 400" . --include=*.py # 0 hits grep -rn "vuex" frontend/src/ # 0 hits grep -rn "api/v1" shopdb/ --include=*.py # 0 hits bash scripts/check-naming-and-style.sh # exit 0 ``` No test suite was run for this re-check; every verdict above is static. ## References - ADR-001: Asset as Platform Contract (plugin isolation model) - ADR-003: Plugin Distribution (filesystem discovery) - ADR-008: Plugin Migration Ownership (linear chains, PLUGIN_TABLE_OWNERS) - ADR-013: Plugin Catalog and Lean Builds (frontend isolation) - ADR-015: Site-Specific Configuration (no literals in code) - ADR-Conformance-2026-09-18.md: the ADR-by-ADR result of the 2026-09-18 review, including the fact that the ADR set is not in this repository