mirror of
https://github.com/ipnet-mesh/meshcore-hub.git
synced 2026-03-28 17:42:56 +01:00
104 lines
3.8 KiB
YAML
104 lines
3.8 KiB
YAML
# MeshCore Hub — codebase orientation map
|
|
# See: https://github.com/anthropics/agentmap
|
|
|
|
meta:
|
|
project: meshcore-hub
|
|
version: 1
|
|
updated: "2026-02-27"
|
|
stack:
|
|
- python 3.13
|
|
- fastapi
|
|
- sqlalchemy (async)
|
|
- paho-mqtt
|
|
- click
|
|
- lit-html SPA
|
|
- tailwind + daisyui
|
|
- sqlite
|
|
|
|
tasks:
|
|
install: "pip install -e '.[dev]'"
|
|
test: "pytest"
|
|
run: "meshcore-hub api --reload"
|
|
lint: "pre-commit run --all-files"
|
|
|
|
tree:
|
|
src/meshcore_hub/:
|
|
__main__.py: "Click CLI entry point, registers subcommands"
|
|
common/:
|
|
config.py: "pydantic-settings, all env vars [config]"
|
|
database.py: "async SQLAlchemy session management"
|
|
mqtt.py: "MQTT client helpers"
|
|
i18n.py: "translation loader, t() function"
|
|
models/:
|
|
base.py: "Base, UUIDMixin, TimestampMixin"
|
|
node.py: null
|
|
member.py: null
|
|
advertisement.py: null
|
|
message.py: null
|
|
telemetry.py: null
|
|
node_tag.py: null
|
|
schemas/:
|
|
events.py: "inbound MQTT event schemas"
|
|
commands.py: "outbound command schemas"
|
|
nodes.py: "API request/response schemas"
|
|
members.py: null
|
|
messages.py: null
|
|
interface/:
|
|
receiver.py: "reads device events, publishes to MQTT"
|
|
sender.py: "subscribes MQTT commands, writes to device"
|
|
device.py: "meshcore library wrapper"
|
|
mock_device.py: "fake device for testing"
|
|
collector/:
|
|
subscriber.py: "MQTT subscriber, routes events to handlers"
|
|
handlers/: "per-event-type DB persistence"
|
|
cleanup.py: "data retention and node cleanup"
|
|
webhook.py: "forward events to HTTP endpoints"
|
|
tag_import.py: "seed node tags from YAML"
|
|
member_import.py: "seed members from YAML"
|
|
api/:
|
|
app.py: "FastAPI app factory"
|
|
auth.py: "API key authentication"
|
|
dependencies.py: "DI for db session and auth"
|
|
metrics.py: "Prometheus /metrics endpoint"
|
|
routes/: "REST endpoints per resource"
|
|
web/:
|
|
app.py: "FastAPI app factory, SPA shell"
|
|
pages.py: "custom markdown page loader"
|
|
middleware.py: null
|
|
templates/:
|
|
spa.html: "single Jinja2 shell template"
|
|
static/js/spa/:
|
|
app.js: "SPA entry, route registration"
|
|
router.js: "History API client-side router"
|
|
api.js: "fetch wrapper for API calls"
|
|
components.js: "shared lit-html helpers, t() re-export"
|
|
icons.js: "SVG icon functions"
|
|
pages/: "lazy-loaded page modules"
|
|
alembic/: "DB migrations"
|
|
etc/:
|
|
prometheus/: "Prometheus scrape + alert rules"
|
|
alertmanager/: null
|
|
seed/: "YAML seed data (node_tags, members)"
|
|
tests/:
|
|
|
|
key_symbols:
|
|
- src/meshcore_hub/__main__.py::cli — Click root group [entry-point]
|
|
- src/meshcore_hub/common/config.py::CommonSettings — shared env config base
|
|
- src/meshcore_hub/common/database.py::DatabaseManager — async session factory
|
|
- src/meshcore_hub/common/models/base.py::Base — declarative base for all models
|
|
- src/meshcore_hub/api/app.py::create_app — API FastAPI factory
|
|
- src/meshcore_hub/web/app.py::create_app — Web FastAPI factory
|
|
- src/meshcore_hub/api/auth.py::require_read — read-key auth dependency
|
|
- src/meshcore_hub/api/auth.py::require_admin — admin-key auth dependency
|
|
- src/meshcore_hub/collector/subscriber.py::MQTTSubscriber — event ingestion loop
|
|
- src/meshcore_hub/interface/receiver.py::Receiver — device→MQTT bridge
|
|
- src/meshcore_hub/interface/sender.py::Sender — MQTT→device bridge
|
|
|
|
conventions:
|
|
- four Click subcommands: interface, collector, api, web
|
|
- "MQTT topic pattern: {prefix}/{pubkey}/event/{name} and .../command/{name}"
|
|
- env config via pydantic-settings, no manual os.environ
|
|
- web SPA: ES modules + lit-html, pages export async render()
|
|
- i18n via t() with JSON locale files in static/locales/
|
|
- node tags are freeform key-value pairs, standard keys in AGENTS.md
|