Move project documentation into docs
Add ARCHITECTURE.md with a Mermaid component interaction diagram and short descriptions of the main runtime flows. Move CHANGELOG.md and ROADMAP.md under docs/ so project documentation lives in one place, and update README links plus the project layout description.
This commit is contained in:
mixeme
@@ -0,0 +1,71 @@
|
||||
# PySentry Architecture
|
||||
|
||||
This document shows the current component interaction model. PySentry is still a
|
||||
single desktop process: the GUI, scheduler, storage, and command runner live in
|
||||
one application and communicate through Go function calls and shared in-memory
|
||||
job state.
|
||||
|
||||
## Component Diagram
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
user["Desktop user"]
|
||||
gui["src/gui\nFyne windows, tabs, dialogs"]
|
||||
store["src/core Store\nYAML config and jobs"]
|
||||
scheduler["src/core Scheduler\n@every and cron timing"]
|
||||
runner["src/core Runner\nshell command execution"]
|
||||
autostart["src/core Autostart\nWindows Run / Linux desktop startup"]
|
||||
config["pysentry.yaml\napplication settings"]
|
||||
jobs["jobs.yaml\njob definitions"]
|
||||
logs["logs_dir\nper-run command output logs"]
|
||||
shell["Platform shell\ncmd.exe /C or sh -c"]
|
||||
|
||||
user -->|"edits jobs, settings, runs commands"| gui
|
||||
gui -->|"OpenStore, SaveConfig, SaveJobs"| store
|
||||
store -->|"read/write"| config
|
||||
store -->|"read/write"| jobs
|
||||
|
||||
gui -->|"Start, Pause, RunNow, RefreshSchedule"| scheduler
|
||||
scheduler -->|"SaveJobs after state changes"| store
|
||||
scheduler -->|"RunJob(trigger)"| runner
|
||||
runner -->|"execute command"| shell
|
||||
runner -->|"write stdout/stderr log"| logs
|
||||
runner -->|"RunRecord with status, duration, log path"| scheduler
|
||||
scheduler -->|"onChange RunRecord"| gui
|
||||
gui -->|"display History, command output, job state"| user
|
||||
|
||||
gui -->|"SetAutostart, AutostartStatus"| autostart
|
||||
autostart -->|"use executable path from resolved Paths"| config
|
||||
```
|
||||
|
||||
## Main Flows
|
||||
|
||||
1. Startup:
|
||||
The executable starts `cmd/pysentry`, which calls the GUI package. The GUI
|
||||
opens the store, loads `pysentry.yaml` and `jobs.yaml`, creates the main tabs,
|
||||
then starts the scheduler with the loaded job slice.
|
||||
|
||||
2. Editing settings or jobs:
|
||||
The GUI updates the in-memory job/config state and asks `Store` to write YAML
|
||||
back to disk. Job definitions stay in one `jobs.yaml`; runtime command output
|
||||
is not stored there.
|
||||
|
||||
3. Scheduled run:
|
||||
`Scheduler` checks due jobs on a one-second ticker. When a job is due, it marks
|
||||
the job as running, saves state, and starts `Runner` asynchronously.
|
||||
|
||||
4. Manual run:
|
||||
`Run now` calls the same scheduler path as scheduled execution, but the
|
||||
resulting history record uses the `Manual` trigger.
|
||||
|
||||
5. Command execution:
|
||||
`Runner` executes the command through the platform shell, captures stdout and
|
||||
stderr, writes one timestamped `.log` file, and returns a `RunRecord`.
|
||||
|
||||
6. History update:
|
||||
The scheduler receives the `RunRecord`, updates the matching job, saves YAML,
|
||||
runs log cleanup, and calls the GUI callback so the `History` tab refreshes.
|
||||
|
||||
7. Autostart:
|
||||
The Settings tab calls the platform autostart implementation. Windows uses the
|
||||
current user's Run registry key. Linux uses a desktop-session startup entry.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Changelog
|
||||
|
||||
All notable PySentry changes are recorded in this file.
|
||||
|
||||
## 0.2.1 - 2026-06-15
|
||||
|
||||
- Fixed Docker release scripts so container builds keep Go in `PATH`.
|
||||
- Disabled Go VCS stamping for Docker release builds to avoid failures when `.git` metadata is unavailable inside the container.
|
||||
- Made Docker release builds write `dist/` artifacts with the current user's UID/GID instead of root ownership.
|
||||
- Added `ROADMAP.md` with planned delivery formats and packaging priorities.
|
||||
- Cleaned `.gitignore` for the current Go/Fyne project and kept the local `_gsdata_/` rule.
|
||||
- Added README links to official Go/Fyne sites and source repositories useful for dependency mirroring.
|
||||
- Documented Windows dependency installation steps for Go and MSYS2 UCRT64 GCC.
|
||||
|
||||
## 0.2.0 - 2026-06-15
|
||||
|
||||
- Added working autostart support with status diagnostics in Settings.
|
||||
- Switched Linux autostart to XDG Autostart `.desktop` files and clean up the legacy user systemd unit.
|
||||
- Fixed Windows autostart status detection by parsing `HKCU Run` values and comparing executable paths reliably.
|
||||
- Added background job execution so the GUI does not block while commands run.
|
||||
- Suppressed Windows console windows for scheduled and manual command runs.
|
||||
- Added application version display in the window title, Settings, and build artifact names.
|
||||
- Moved release artifact commands from `Dockerfile` into `scripts/build-release-linux.sh` with interactive target selection.
|
||||
- Added release build targets for Linux amd64, Linux arm64, and Windows amd64.
|
||||
- Added README dependency installation notes and official Go/Fyne links.
|
||||
|
||||
## 0.1.0 - 2026-06-14
|
||||
|
||||
- Added the initial Fyne desktop GUI.
|
||||
- Added YAML settings and single-file YAML job storage.
|
||||
- Added `@every` and standard 5-field cron schedules.
|
||||
- Added manual and scheduled command runs with per-run log files.
|
||||
- Added job folders, history, global pause, and Windows tray support.
|
||||
- Added Windows and Linux build helpers.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Roadmap
|
||||
|
||||
This file tracks planned PySentry work that is larger than a single bug fix.
|
||||
|
||||
## Project Rename
|
||||
|
||||
Plan a rename from PySentry to GoSentry.
|
||||
|
||||
Rename checklist:
|
||||
|
||||
- Decide the final repository path and Go module path.
|
||||
- Update application name, window title, tray menu, and desktop integration text.
|
||||
- Update app ID and autostart entry names.
|
||||
- Rename build artifacts from `pysentry-*` to `gosentry-*`.
|
||||
- Decide whether runtime files should stay backward-compatible with existing
|
||||
`pysentry.yaml`, `jobs.yaml`, and log directories or migrate to new names.
|
||||
- Update README, CHANGELOG, ROADMAP, build scripts, Docker image names, and
|
||||
package metadata.
|
||||
- Consider a transition note for users with existing PySentry configuration.
|
||||
|
||||
## Post-Field-Test Cleanup
|
||||
|
||||
After real-world use confirms the main workflows, clean up temporary
|
||||
stabilization code and development scaffolding.
|
||||
|
||||
Cleanup checklist:
|
||||
|
||||
- Review and remove debug-oriented diagnostics that are no longer useful.
|
||||
- Remove excessive defensive checks once behavior is proven and covered by the
|
||||
right tests.
|
||||
- Remove obsolete compatibility cleanup, such as old autostart migration code,
|
||||
after the transition window is over.
|
||||
- Delete stale generated files and old build artifacts from local/release flows.
|
||||
- Revisit tests and remove ones that only lock in temporary implementation
|
||||
details instead of real user-facing behavior.
|
||||
- Simplify README notes that were useful during early setup but are too noisy
|
||||
for normal users.
|
||||
- Recheck `.gitignore`, Docker scripts, and packaging scripts for rules or
|
||||
branches that only supported early experiments.
|
||||
|
||||
## Delivery And Packaging
|
||||
|
||||
Keep a single portable binary as the baseline delivery format. It is simple to
|
||||
test, easy to copy between machines, and matches the current storage model where
|
||||
runtime YAML files live next to the executable by default.
|
||||
|
||||
Planned delivery variants:
|
||||
|
||||
- Windows portable `.zip` with `pysentry.exe`, `README.md`, and `CHANGELOG.md`.
|
||||
- Linux portable `.tar.gz` archives for `linux-amd64` and `linux-arm64`.
|
||||
- Debian/Ubuntu `.deb` package once the Linux runtime paths are settled.
|
||||
- Windows installer later, likely Inno Setup first and MSI/WiX only if needed.
|
||||
- AppImage as a possible Linux GUI-friendly format after the core workflow is stable.
|
||||
- Flatpak only after the desktop integration story is clearer.
|
||||
- winget manifest after stable public Windows releases exist.
|
||||
|
||||
Packaging design note:
|
||||
|
||||
- Portable builds can keep settings and jobs next to the executable.
|
||||
- Installer/package builds should move runtime data to per-user locations:
|
||||
`%APPDATA%\PySentry` on Windows, and XDG directories such as
|
||||
`~/.config/pysentry` and `~/.local/share/pysentry` on Linux.
|
||||
|
||||
Initial priority:
|
||||
|
||||
1. Windows portable `.zip`.
|
||||
2. Linux portable `.tar.gz` for amd64 and arm64.
|
||||
3. Debian/Ubuntu `.deb`.
|
||||
4. Windows installer.
|
||||
Reference in New Issue
Block a user