Add project documentation: AGENTS.md and ROADMAP.md
- AGENTS.md: Guidelines for AI agents working on this project - ROADMAP.md: Complete migration plan from tmux/cron to systemd - Configuration strategy using relative paths - APT package creation plan (Phase 8) - Progress tracking instructions
This commit is contained in:
238
AGENTS.md
Normal file
238
AGENTS.md
Normal file
@@ -0,0 +1,238 @@
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## 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**
|
||||
Reference in New Issue
Block a user