# 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