bd48814021
Clean up and organize the flask-shopdb repository for better maintainability and discoverability: ## Changes - Update .gitignore for build artifacts (publish/, data/, 122M total) - Reorganize .claude/ into 6 subdirectories with README navigation - Consolidate overlapping MCP setup guides into MCP-QUICK-START.md - Move deployment docs from root to docs/deployment/ - Archive dated status reports to .claude/archived/ - Delete temporary files (logs, backups, empty reports, ~50K) ## New Structure .claude/ organized into: - setup/ - MCP, VM, Hyper-V, GitHub setup guides + scripts (17 files) - plans/ - Feature plans and protocols (5 files) - maintenance/ - Deployment checklists and reports (4 files) - archived/ - Historical documentation (9 files) - skills/ - Claude Code automation (5 files) - workflows/ - Security audit workflow (1 file) docs/deployment/ created with 6 deployment guides: - LOCAL-DEV-SETUP.md, DOCKER-SETUP.md, DOCKER-PREBUILT-APPROACH.md - PRODUCTION-READINESS.md, DEPLOY-TO-VM.md, README.md Root directory cleaned to essential docs only: - CLAUDE.md, README.md, CONTRIBUTING.md, CHANGELOG.md Benefits: - Clear navigation via README.md in each subdirectory - No duplicate/overlapping documentation - Large artifacts properly gitignored (won't bloat repository) - Historical context preserved in archived/ See .claude/CLEANUP-SUMMARY.md for complete details. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
128 lines
4.3 KiB
Markdown
128 lines
4.3 KiB
Markdown
# 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
|