sensorpajen/AGENTS.md

AGENTS.md

Purpose

This repository contains a small back-end application intended to run continuously on a Raspberry Pi. The current implementation uses:

• Python scripts for application logic
• Shell scripts to start/stop the application
• An .ini file for configuration

The goal is to modernize the system so it runs as a first-class Linux service, follows modern Python practices, and eliminates the .ini configuration file.

I also want to remove some legacy stuff which I no longer need. For example the startup.sh script refers to /home/pi/pirate_audio which I no longer use.

This document defines how agents should approach that work.

---

High-Level Goals

Agents working on this repository should aim to:

1. Convert the application into a proper system service
2. Replace shell-script orchestration with systemd
3. Remove the .ini configuration file
4. Use clear, explicit, and secure configuration mechanisms
5. Keep the solution lightweight and suitable for Raspberry Pi hardware
6. Avoid unnecessary frameworks or over-engineering

---

Target Runtime Environment

• Hardware: Raspberry Pi (ARM)
• OS: Raspberry Pi OS / Debian-based Linux
• Python: Python 3.10+ (use the system Python unless specified otherwise)
• Init system: systemd

---

Service Architecture Expectations

1. Application Structure

Agents should move toward a structure similar to:

app/
├── src/
│   └── my_service/
│       ├── __init__.py
│       ├── main.py
│       ├── config.py
│       └── ...
├── pyproject.toml
├── README.md
└── AGENTS.md

Key expectations:

• A single clear entry point (e.g. main.py)
• No logic embedded in shell scripts
• Importable Python modules, not ad-hoc scripts

---

2. Configuration (No .ini Files)

The .ini configuration file must be removed.

Agents should prefer one of the following, in order:

1. Environment variables (primary approach)
2. systemd service configuration (Environment= or EnvironmentFile=)
3. Hard-coded defaults only when values are truly static

Configuration Rules

• All configuration must be discoverable in one place (e.g. config.py)

• Each configuration value must:

  • Have a clear name
  • Have a documented default (if applicable)
  • Fail fast if required and missing

Example pattern (illustrative):

import os

SERVICE_PORT = int(os.environ.get("SERVICE_PORT", "8080"))

DEVICE_ID = os.environ.get("DEVICE_ID")
if DEVICE_ID is None:
    raise RuntimeError("DEVICE_ID must be set")

---

3. systemd Integration

Agents should replace shell scripts with a systemd service unit.

Expected characteristics:

• Runs as a dedicated system user (if appropriate)
• Restarts automatically on failure
• Logs to journalctl
• Does not daemonize itself (systemd handles this)

Example (conceptual):

[Unit]
Description=My Raspberry Pi Backend Service
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/python3 -m my_service.main
Restart=always
Environment=SERVICE_PORT=8080

[Install]
WantedBy=multi-user.target

Agents should not embed business logic in the service file.

---

4. Logging

• Use Python’s built-in logging module
• Log to stdout/stderr only (systemd captures logs)
• No custom log rotation or log files unless explicitly required

---

5. Packaging & Dependencies

Agents should:

• Use pyproject.toml for dependencies
• Avoid heavy frameworks unless clearly justified
• Prefer standard library solutions when possible

Virtual environments are optional but acceptable.

---

Migration Strategy

Agents should assume:

• Existing Python logic must be preserved unless refactoring is clearly beneficial
• Behavior should remain functionally equivalent
• Configuration values previously stored in .ini must be mapped to environment variables

If behavior changes, it must be documented.

---

Non-Goals

Agents should not:

• Introduce containers (Docker, Podman, etc.)
• Introduce cloud dependencies
• Add front-end components
• Rewrite the application in another language
• Add complex orchestration or message queues

---

Documentation Expectations

Any agent making changes must:

• Update README.md with:

  • How to configure the service
  • How to install and enable it
  • How to view logs

• Keep instructions Raspberry Pi–friendly and concise

---

Guiding Principles

• Simple over clever
• Explicit over implicit
• Fewer moving parts
• Easy to debug on a headless device
• Test-Driven Development (TDD): Always write tests before or alongside new features. Ensure the test suite passes before considering a task complete.

---

Development Workflow

1. Branching: All new features and significant changes must be developed in a dedicated feature branch (e.g., feature/tui-management).
2. Task Management:
   • Use Tasks.md to track active and future work.
   • When a task is finished, ask the user for confirmation before moving it.
   • Once confirmed, move the task details to COMPLETED_TASKS.md.
3. Roadmap: Keep ROADMAP.md updated as the source of truth for project phases.

---

Progress Tracking

When working on this project:

1. Update ROADMAP.md after each completed task

   • Change ✓ TODO to ✅ DONE for completed phases
   • Add actual completion dates
   • Document any deviations from the plan
   • Note issues encountered and solutions

2. Track incremental progress

   • Mark individual tasks within phases as completed
   • Add notes about implementation decisions
   • Document configuration values used (without sensitive data)

3. Keep ROADMAP.md as the source of truth

   • All significant changes should be reflected in the roadmap
   • Add new phases if needed
   • Update success criteria as understanding evolves

4. Example update format:

   ### Phase 1: Preparation & Cleanup ✅ DONE (2025-12-27)
   **Goal**: Reorganize repository without breaking existing functionality
   
   **Notes**: 
   - Decided to use JSON for sensors instead of TOML for easier parsing
   - Added debian/ directory for APT packaging
   
   #### Tasks:
   - ✅ Create new directory structure
   - ✅ Create pyproject.toml with dependencies
   - ✅ Remove DHT11 functionality
   ...
   

---

End of AGENTS.md