shopdb-flask/.claude/INDEX.md

ShopDB Index - Load Only What You Need

Quick pointers to avoid reading entire wiki or codebase.

When Working On...

Plugin development:

• Read: CLAUDE.md (overview)
• Grep: class BasePlugin in shopdb/api/__init__.py
• Reference: ../shopdb-flask.wiki/ADR-001-asset-as-platform-contract.md

Database migrations:

• Read: ../shopdb-flask.wiki/ADR-008-plugin-migration-ownership.md
• Grep: PLUGIN_TABLE_OWNERS for dependency order
• Pattern: plugins/{name}/migrations/versions/*.py

Site-specific config:

• Read: ../shopdb-flask.wiki/ADR-015-site-specific-configuration.md
• Locations: shopdb/core/settings/, shopdb/core/seed/, scripts/site_imports/

Kiosk/device auth:

• Read: ../shopdb-flask.wiki/ADR-016-credential-delivery.md
• Grep: requires_device_token

Deployment/branches:

• Read: ../shopdb-flask.wiki/ADR-004-deployment-topology.md
• Scripts: ~/Documents/github/*.cmd

Frontend plugin panels:

• Read: ../shopdb-flask.wiki/ADR-010-frontend-plugin-hooks.md
• Pattern: plugins/{name}/frontend/views/*.vue

Testing:

• Read: tests/conftest.py for fixtures
• Pattern: tests/test_plugins/test_{plugin}_{feature}.py

Plugin Map (20 plugins)

Core asset types:

• computers, endpoints, printers, machines, measuringtools, network, tools

Workflows:

• printedparts, usb, slides, notifications

Integrations:

• warranty, geenforce, guides, knowledgebase

Admin:

• employees, backups

Key Files

• shopdb/api/__init__.py - Stable import surface (75 lines)
• shopdb/config.py - App configuration
• shopdb/core/models/asset.py - Base asset model
• docker-compose.yml - Dev stack definition
• scripts/check-naming-and-style.sh - Pre-commit hook

Git Branches

Current repo state:

• wj (checked out) - Prod branch for WJ shop floor
• main - Public GitHub mirror, deploys nowhere
• origin/wilm - Upstream changes from benjamin.baker (86 commits ahead)
• origin/dev-be - Historical dev branch

Branch workflow (ADR-004):

• wj -> prod deployment (WJ site)
• dev -> ops deployment (monitoring/pilot sites, on gitea only)
• main -> GitHub public mirror only (no deployments)
• wilm -> fetch from GitHub, review, merge to wj or dev

On this work PC:

• Has GitHub credentials (ge-aero/shopdb-flask)
• Fetch wilm: ~/Documents/github/fetch-wilm-branch.cmd
• Bundle to dev PC: ~/Documents/github/pull-shopdb-bundle.cmd

Common Paths

• Plugin code: plugins/{name}/
• Core models: shopdb/core/models/
• Core API: shopdb/core/api/
• Frontend core: frontend/src/
• Tests: tests/test_plugins/
• Migrations: migrations/ (core) + plugins/{name}/migrations/
• Scripts: scripts/
• Docs: ../shopdb-flask.wiki/

Avoid Reading These Unless Needed

• docs/openapi.json (489 lines, generated)
• frontend/dist/ (build output)
• node_modules/, venv/, .pytest_cache/
• agent/ (C# endpoint agent, 10k+ lines)
• Full wiki (68 files) - use index above

Token-Efficient Patterns

1. Grep before Read: Find the exact file/function first
2. Read with limit: Use offset/limit for large files
3. Reference by path: Cite file:line instead of quoting code
4. Use memory: Store repeated patterns in memory files
5. Wiki on-demand: Only read specific ADRs when relevant

One-Line ADR Summaries

• ADR-001: Asset is the platform primitive for all equipment
• ADR-004: Three air-gapped environments, bundle workflow
• ADR-006: Endpoint agent sends telemetry, receives commands
• ADR-007: Semantic versioning, GitHub releases
• ADR-008: Each plugin owns its migration chain, no conflicts
• ADR-009: Frontend plugins gate on backend features
• ADR-010: Plugins register Vue components via manifest
• ADR-013: Lean builds include only needed plugins
• ADR-015: Site literals go in settings/seed/site_imports only
• ADR-016: Kiosks use device tokens, not user sessions

.claude/ Directory Structure

• INDEX.md (this file) - Quick reference for code navigation
• QUICK-REFERENCE.md - Common commands and shortcuts
• setup/ - Setup guides (MCP, VM, Hyper-V, GitHub integration)
• plans/ - Feature plans and protocols (SAML, tool engagement, security)
• maintenance/ - Operational checklists and reports
• archived/ - Superseded documentation
• skills/, workflows/ - Claude Code automation
• settings.json, mcp-servers.json - Configuration