Build Update (April 16, 2026)

This week I focused on documentation quality and operational clarity for heka-insights-agent.

The goal was simple: make docs match the code exactly, so contributors and operators can reason about behavior without reading every module first.

What I updated

• Rewrote docs/architecture.md from scratch


• Rewrote docs/configuration.md from scratch


• Expanded README.md with project context, setup, and environment guidance

Architecture documentation improvements

docs/architecture.md now documents:

• the actual runtime topology and control loop in src/main.py
  


• collector boundaries and behavior (CPUCollector, MemoryCollector, DiskCollector)


• logging subsystem behavior in src/logger/config.py
  


• current payload shapes emitted by collectors


• known gaps (no sender layer yet, no tests yet, no schema versioning yet)


• practical extension points for next phases

This gives a real “as-implemented” architecture baseline instead of aspirational text.

Configuration documentation improvements

docs/configuration.md now includes exact behavior for the two active runtime settings:

• LOG_LOCATION


• CPU_POLL_INTERVAL_SECONDS

It also documents:

• source/precedence rules


• defaults and validation behavior


• failure modes


• local setup and production recommendations

Important behavior clarified

Current config loading is split across two env files:

• root .env is used for LOG_LOCATION
  


• 
  src/.env is used for CPU_POLL_INTERVAL_SECONDS
  

That split is now explicitly documented to reduce startup/debug confusion.

Why this matters

For an agent project, docs are part of reliability.


Operators need to know what can fail at startup, where config is read from, and what telemetry shape to expect downstream.

This update makes onboarding and future refactors safer.

Next steps

• add transport/sender layer (backend adapters)


• add collector-focused tests


• consolidate config loading into a single source


• define schema/versioning strategy for emitted payloads

Repo: https://github.com/ronin1770/heka-insights-agent