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):

```python
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**:
   ```markdown
   ### 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**