251 lines
6.3 KiB
Markdown
251 lines
6.3 KiB
Markdown
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**
|