Flesh out PLAN.md with two-architecture implementation detail

archeious commented

2026-04-17 19:19:11 -06:00

Owner

Doc-only change. Expands PLAN.md to specify both viable architectures (A: OTEL-native via Prometheus; B: ccusage-sourced with JSONL tail for the tach) to implementation-ready detail. Hardware path nailed down: X27.168 steppers, SwitecX25 Arduino library, ESP32 wiring.

Refs #1

Summary

Architecture A: full Docker Compose stack, Claude Code env config, PromQL, Python daemon sketch.
Architecture B: ccusage subprocess + watchdog JSONL tail, Python daemon sketch.
Hardware: X27.168 + SwitecX25, ESP32 pin map, ULN2003A driver notes, enclosure.
Six-phase delivery plan, recommendation (A), metrics brainstorm for later phases.

Test plan

Read through PLAN.md top to bottom; flag anything under-specified.
Verify the PromQL queries look right against a Prometheus instance the code will eventually hit.
Decide A vs B before opening Phase A issue.

🤖 Generated with Claude Code

Doc-only change. Expands PLAN.md to specify both viable architectures (A: OTEL-native via Prometheus; B: ccusage-sourced with JSONL tail for the tach) to implementation-ready detail. Hardware path nailed down: X27.168 steppers, SwitecX25 Arduino library, ESP32 wiring. Refs #1 ## Summary - Architecture A: full Docker Compose stack, Claude Code env config, PromQL, Python daemon sketch. - Architecture B: ccusage subprocess + watchdog JSONL tail, Python daemon sketch. - Hardware: X27.168 + SwitecX25, ESP32 pin map, ULN2003A driver notes, enclosure. - Six-phase delivery plan, recommendation (A), metrics brainstorm for later phases. ## Test plan - [ ] Read through PLAN.md top to bottom; flag anything under-specified. - [ ] Verify the PromQL queries look right against a Prometheus instance the code will eventually hit. - [ ] Decide A vs B before opening Phase A issue. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

archeious added 1 commit 2026-04-17 19:19:12 -06:00

Flesh out PLAN.md with two-architecture implementation detail 08eaa63300

Expand the planning document to implementation-ready detail. Both
viable data paths are specified independently so either can ship:

- Architecture A (OTEL-native): full docker-compose stack mirroring
  Anthropic's claude-code-monitoring-guide (otel-collector on 4317
  / 4318 / 8889, Prometheus on 9090, Grafana on 3000), Claude Code
  env vars, PromQL queries for each gauge, Python daemon sketch
  that queries Prometheus and serves /usage.

- Architecture B (ccusage-sourced): subprocess invocation of
  ccusage CLI for 5h blocks and 7d daily aggregates, watchdog
  JSONL tail for sub-second tach responsiveness, Python daemon
  sketch with a 60s RateBus ring buffer.

Hardware specified: X27.168 stepper motors driven by the Arduino
SwitecX25 library on ESP32 (Arduino C++ since no MicroPython port
exists), concrete GPIO pin assignments, ULN2003A driver notes,
annunciator LED wiring, enclosure notes.

Also captured: metric schema from Claude Code's OTEL docs,
prior-art review (ccusage / Claude-Code-Usage-Monitor / Grafana
Labs dashboards 25052 and 24993 / Anthropic's monitoring guide),
six-phase delivery plan, comparison table of A vs B, recommendation
(A for homelab-as-enterprise framing), and a metrics brainstorm
for later phases.

README updated to summarise both architectures and point at the
expanded plan.

Refs #1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

archeious added 1 commit 2026-04-17 19:31:09 -06:00

Add monitor-dash render to README; prepare wiki layout fdab957b55

- Move uploaded renders into docs/images/ (tracked).
- Insert the Monitor Dash render at the top of README.md as the
  headline image of the project.
- Rewrite README body to point at the forgejo wiki (six pages now
  live) as the canonical documentation surface, with PLAN.md
  staying as working notes.
- Gitignore docs/wiki/ so the wiki git checkout does not bleed
  into the main repo.

Refs #1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

archeious referenced this pull request from a commit

2026-04-17 21:07:39 -06:00

chore: add CLAUDE.md for session 1

archeious added 1 commit 2026-04-17 21:07:39 -06:00

chore: add CLAUDE.md for session 1 1bfe151baf

Repo-level CLAUDE.md captures current project state (pre-Phase-A,
architecture decision open, PR #2 in flight), project conventions,
where things live, and the session 1 log pointing at the wiki
retrospective.

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin feat/1-flesh-out-plan:feat/1-flesh-out-plan

git checkout feat/1-flesh-out-plan

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git checkout main

git merge --no-ff feat/1-flesh-out-plan

git checkout feat/1-flesh-out-plan

git rebase main

git checkout main

git merge --ff-only feat/1-flesh-out-plan

git checkout feat/1-flesh-out-plan

git rebase main

git checkout main

git merge --no-ff feat/1-flesh-out-plan

git checkout main

git merge --squash feat/1-flesh-out-plan

git checkout main

git merge --ff-only feat/1-flesh-out-plan

git checkout main

git merge feat/1-flesh-out-plan

git push origin main

Flesh out PLAN.md with two-architecture implementation detail #2

Summary

Test plan

Checkout

Merge