Add documentation for node tag import feature

README.md:
- Add "Node Tags" section with comprehensive documentation
- Document CLI usage: meshcore-hub collector import-tags
- Document Docker Compose usage: docker compose --profile import-tags
- Document JSON format with field descriptions
- Document import options (--no-create-nodes)
- Document data directory structure for Docker
- Document tag management via REST API (CRUD operations)

AGENTS.md:
- Add tag_import.py to project structure
- Update example/data structure with collector/web subdirectories
- Update data directory structure documentation
This commit is contained in:
Claude
2025-12-03 18:32:50 +00:00
parent cbaf4f451c
commit c56e15a5f8
2 changed files with 106 additions and 1 deletions
+7 -1
View File
@@ -249,6 +249,7 @@ meshcore-hub/
│ ├── collector/
│ │ ├── cli.py
│ │ ├── subscriber.py # MQTT subscriber
│ │ ├── tag_import.py # Tag import from JSON
│ │ ├── handlers/ # Event handlers
│ │ └── webhook.py # Webhook dispatcher
│ ├── api/
@@ -278,8 +279,13 @@ meshcore-hub/
│ └── mosquitto.conf # MQTT broker configuration
├── example/
│ └── data/
── members.json # Example network members data
── collector/
│ │ └── tags.json # Example node tags data
│ └── web/
│ └── members.json # Example network members data
├── data/ # Runtime data (gitignored)
│ ├── collector/ # Collector data (tags.json)
│ └── web/ # Web data (members.json)
├── Dockerfile # Docker build configuration
├── docker-compose.yml # Docker Compose services (gitignored)
└── docker-compose.yml.example # Docker Compose template
+99
View File
@@ -231,6 +231,9 @@ meshcore-hub interface --mode sender --mock # Use mock device
# Collector component
meshcore-hub collector --database-url sqlite:///./data.db
# Import node tags from JSON file
meshcore-hub collector import-tags /path/to/tags.json
# API component
meshcore-hub api --host 0.0.0.0 --port 8000
@@ -243,6 +246,102 @@ meshcore-hub db downgrade # Rollback one migration
meshcore-hub db current # Show current revision
```
## Node Tags
Node tags allow you to attach custom metadata to nodes (e.g., location, role, owner). Tags are stored in the database and returned with node data via the API.
### Importing Tags from JSON
Tags can be bulk imported from a JSON file:
```bash
# Native CLI
meshcore-hub collector import-tags /path/to/tags.json
# With Docker Compose
docker compose --profile import-tags run --rm import-tags
```
### Tags JSON Format
```json
{
"tags": [
{
"public_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"key": "location",
"value": "San Francisco, CA",
"value_type": "string"
},
{
"public_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"key": "altitude",
"value": "150",
"value_type": "number"
}
]
}
```
| Field | Required | Description |
|-------|----------|-------------|
| `public_key` | Yes | 64-character hex public key of the node |
| `key` | Yes | Tag name (max 100 characters) |
| `value` | No | Tag value (stored as text) |
| `value_type` | No | Type hint: `string`, `number`, `boolean`, or `coordinate` (default: `string`) |
### Import Options
```bash
# Create nodes if they don't exist (default behavior)
meshcore-hub collector import-tags tags.json
# Skip tags for nodes that don't exist
meshcore-hub collector import-tags --no-create-nodes tags.json
```
### Data Directory Structure
For Docker deployments, organize your data files:
```
data/
├── collector/
│ └── tags.json # Node tags for import
└── web/
└── members.json # Network members list
```
Example files are provided in `example/data/`.
### Managing Tags via API
Tags can also be managed via the REST API:
```bash
# List tags for a node
curl http://localhost:8000/api/v1/nodes/{public_key}/tags
# Create a tag (requires admin key)
curl -X POST \
-H "Authorization: Bearer <API_ADMIN_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "location", "value": "Building A"}' \
http://localhost:8000/api/v1/nodes/{public_key}/tags
# Update a tag
curl -X PUT \
-H "Authorization: Bearer <API_ADMIN_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": "Building B"}' \
http://localhost:8000/api/v1/nodes/{public_key}/tags/location
# Delete a tag
curl -X DELETE \
-H "Authorization: Bearer <API_ADMIN_KEY>" \
http://localhost:8000/api/v1/nodes/{public_key}/tags/location
```
## API Documentation
When running, the API provides interactive documentation at: