DHA Core — Codebase Review

Repo: NightKnight64/dha-core
Reviewed: 2026-04-25
Location: /home/hoffmann_admin/dha-core-legacy
Size: 10 Python files, 716 lines total
State: Archived / deprecated — superseded by family-assistant and hoffdesk-agents

1. Architecture

DHA Core is an abstract service mesh framework — not a shipping family assistant. It defines a plugin architecture where modules implement a DHA_Module ABC, are registered via Service_Manifest.yaml, and executed by an Orchestrator with an in-process BackgroundScheduler. There's an EventBus for pub/sub between modules and a YAML-based identity/role system.

Component Map (716 total lines)

                        ┌─────────────────────────┐
                        │    Service_Manifest.yaml  │  (4 services)
                        └─────────┬───────────────┘
                                  │
                        ┌─────────▼───────────────┐
                        │   Orchestrator.py (161)  │  ── YAML loader
                        │                          │  ── Dynamic import + init
                        │                          │  ── APScheduler loop
                        └─────────┬───────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
  ┌───────▼───────┐     ┌────────▼───────┐     ┌─────────▼──────┐
  │ Persistence   │     │ Identity       │     │ CalendarSync   │
  │ Module (105)  │     │ Module (95)    │     │ Module (98)    │
  │ - SQLite      │     │ - household.yaml│    │ - Adapter      │
  │ - state save  │     │ - RBAC         │     │   Pattern      │
  └───────┬───────┘     └────────┬───────┘     └─────────┬──────┘
          │                       │                       │
          │             ┌─────────▼───────┐     ┌─────────▼──────┐
          │             │  Notification  │     │  GoogleAdapter │
          │             │  Module (44)   │     │  (simulated)   │
          │             │  - EventBus    │     └────────────────┘
          │             │    subscriber  │
          │             └─────────┬───────┘
          │                       │
          └───────────────────────┘
                    EventBus (12 lines)

  Supporting infrastructure:
  ├── DHA_Module.py (22)  ── Abstract Base Class
  ├── event_bus.py (38)   ── Pub/Sub (in-memory)
  ├── debug_smore.py (28) ── Debug launcher
  └── smore_test.py (100) ── Integration test / demo

Architecture Assessment ✅ Good abstraction, poor implementation

The abstract framework is well-conceived:
- Plugin pattern via ABC + YAML manifest → genuinely extensible
- EventBus provides loose coupling
- Adapter pattern for calendar providers (though only Google is implemented and it's mocked)
- background.Scheduler for recurring tasks

But it's all scaffolding and no building:
- The Google adapter returns hardcoded mock data
- The Notification module just prints to terminal
- The Identity module loads from YAML but never checks permissions in a real request
- No real API endpoints, no Telegram/webhook integration
- Service_Manifest.yaml is in .gitignore (intentionally omitted for deployment)

2. Code Quality

What's Good

• Clean abstract interface. DHA_Module with initialize(), check_status(), execute_task() is a solid contract.
• EventBus is minimal and correct. 38 lines, no external deps, works.
• smore_test.py is a working integration test. It spins up the orchestrator, initializes all four modules, runs a loop — genuine end-to-end smoke test (albeit with mocked adapters).
• __pycache__ is gitignored. Small win, but consistent.

What's Not

• Google adapter returns hardcoded fake data. The comment says "Simulated API call" — this is a stub, not production code. The api_key config parameter is accepted but never used.
• No actual HTTP/API layer. No FastAPI, no Flask, no webhook. DHA Core can't receive or send anything — it's a local-only scheduler with print() statements as output.
• sys.path.append in every module. All four modules have the exact same boilerplate: sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))). Should be a one-line setup.py / PYTHONPATH fix.
• household.yaml includes Maggie the dog as a standard role user. Cute, but the RBAC layer has a canine member with preferences.notifications: false — which is correct, but it's an indication the design is playful rather than production.
• smore_test.py has time.sleep(4) polling. The scheduler should call back; blocking sleeps are not how you test an event loop.
• No error recovery. If a module fails to initialize, the orchestrator logs it but continues. No circuit breaker, no retry, no alert.
• The PersistenceModule saves JSON state but nothing reads it. It's write-only storage.

3. Feature Completeness vs What It Should Have Been

4. Relationship to Family Assistant

DHA Core was the prototype that taught you the patterns that became Family Assistant. Specifically:

• Learned: Abstract module frameworks (DHA_Module) add complexity without value for a single-app deployment. Family Assistant doesn't use it — it's a flat Python package.
• Learned: Hardcoded adapter patterns (GoogleAdapter) are worse than YAML-driven config. Family Assistant uses config.py with env vars and family.yaml.
• Learned: In-process EventBus is overengineered for a notification system that just needs HTTP. Family Assistant uses direct Telegram API calls.
• Learned: The plugin manifest adds deployment friction without the benefit of hot-plugging. Family Assistant is a pip-installable package.

The calendar_sync module in DHA Core (98 lines, mocked) became the 660-line radicale-driven calendar_sync.py in Family Assistant. The identity module (95 lines, YAML-only) became the config.py family.yaml loader (369 lines with env, caching, dynamic grading). The notification module (44 lines, print()) became hermes.py (602 lines, Telegram Bot API).

DHA Core is best understood as a "proof of concept" that you evolved past. The architecture decisions (service mesh, abstract modules, EventBus) are the right patterns for a multi-service distributed system, but for a single-machine family assistant they were overengineering.

5. Portability: 5/10

• Requirements: PyYAML==6.0.3 (+ Python stdlib). That's it.
• No external deps: No FastAPI, no httpx, no Ollama, no CalDAV libraries, no databases beyond SQLite.
• BUT: It doesn't do anything useful without external services. The Google adapter is stubbed. There's no webhook to receive events. The notification module doesn't connect to anything.
• Verdict: Portable by virtue of being incomplete. Running it gives you a scheduler that prints to stdout.

6. Assessment Summary

Historical Significance

This was the original blueprint — the architecture you sketched before you wrote a single line of Family Assistant. The fact that it evolved into a 10k-line working system that processes real email, syncs to a real calendar, and runs on your hardware is genuinely impressive. The DHA Core framework (Service_Manifest, DHA_Module ABC, EventBus) was the right starting point, and Family Assistant is the right destination.

Recommendation: Delete the dha-core GitHub repo or archive it with a clear README note that says "Historical prototype — superseded by NightKnight64/family-assistant." The abstract framework is interesting but misleading as a starting point for anyone who finds it.

Family Assistant (Standalone) — Codebase Review

Repo: NightKnight64/family-assistant
Reviewed: 2026-04-25
Location: /home/hoffmann_admin/.openclaw/workspace/scripts (+ cloned in hoffdesk-agents/services/family_assistant)
Size: ~10,385 lines across 24 Python modules + 7 prompt files + pyproject.toml
State: Production. Serving real traffic via Cloudflare webhook on hook.hoffdesk.com.

Note: This is the same codebase reviewed in-depth in hoffdesk-agents-review.md. The key findings are summarized here with a focus on differences from the mono-repo copy.

Key Finding: Near-Identical to hoffdesk-agents Version

The standalone family-assistant repo and the version embedded in hoffdesk-agents/services/family_assistant are essentially the same code:
- 22 of 24 Python files are byte-for-byte identical
- hermes.py differs (standalone: 602 lines, mono-repo: 666 lines — likely OpenClaw integration hooks)
- pipeline.py differs by 1 byte (trivial)
- Same prompts, same tests, same structure

However, the standalone repo has important artifacts that the mono-repo doesn't:
- systemd/ directory with actual service files (family-assistant-webhook.service, hoffdesk-webhook.service, radicale.service)
- WEBHOOK_DEPLOY.md — deployment docs for the Cloudflare Worker
- email_worker.js — the Cloudflare Email Worker that routes mail to the webhook
- LICENSE (MIT) — the mono-repo doesn't have one
- backup_hoffdesk.sh — backup script
- .env file (real credentials — still live)
- Legacy wrappers (family_calendar.py, fetch_unread.py)

Critical Finding: .env is Committed-Adjacent

The .env file in the standalone repo (/home/hoffmann_admin/.openclaw/workspace/scripts/.env) contains:
- GMAIL_APP_PASSWORD (live Gmail password)
- GOOGLE_PLACES_API_KEY (live)
- CALDAV_PASSWORD (Radicale credentials)
- TELEGRAM_BOT_TOKEN (live bot token)
- WEBHOOK_SECRET (live webhook shared secret)
- OLLAMA_EMBED_URL (hardcoded to Gaming PC Tailscale IP)
- OPENAI_API_KEY (if configured)

It's gitignored, but it lives inside the tracked project tree. The hoffdesk-agents version has the same .env in services/.env. If you ever clone with --include-untracked, force-push a branch that includes it, or accidentally stage it with git add ., those credentials are in git history permanently.

Recommendation: Rotate all six credentials, then move .env to ~/.openclaw/secrets/family-assistant.env. Update the systemd EnvironmentFile paths accordingly.

Family Assistant vs DHA Core: The Evolution

The evolution is clear: DHA Core taught you the patterns. Family Assistant built the product. Both have near-zero test coverage and sys.path/import quirks, but Family Assistant actually ships real value.

Key Findings Summary

Critical (fix immediately)

1. Rotate all credentials in .env and move the file to ~/.openclaw/secrets/
2. appointment_retry.txt is empty (0 lines) — the LLM retry path sends a blank prompt
3. Gaming PC hardcoded as the only embedding + vision host — if it's off, the Brain and document scanning break silently

High Priority

4. No tests for 23/24 modules — any refactoring is blind
5. Pipeline has ~500 lines of duplicated code (IMAP path vs webhook path)
6. hermes.py has dual notification paths (direct Telegram API + OpenClaw subprocess) — potential for duplicate sends
7. Family assistant standalone has a cleaner .gitignore with family.yaml, maintenance.yaml, chroma_db/, locations/, and auth_circuit_breaker.json ignored — the mono-repo version should adopt these patterns

What's Actually Great

• config.py is production-quality: centralized, cached, dynamic family context injection
• rrule_builder.py prevents LLM hallucination on recurrence rules (deterministic Python → RFC 5545)
• Circuit breaker on IMAP auth failures prevents notification spam during outages
• Shadow filtering (rejection_engine.py) events are demoted, not deleted — user sees what was filtered
• Prompt-as-Code pattern — prompts in text files, not Python. Easy to iterate without touching code.
• Hybrid Retrieval (calendar + ChromaDB) is the smartest architectural decision in the codebase