Merge pull request #153 from sheepdestroyer/docs-complete-repository-documentation

Docs complete repository documentation

Author: sheepdestroyer

README.md

@@ -4,107 +4,92 @@ A simple, self-hosted RSS/Atom feed aggregator inspired by Netvibes & iGoogle, d
 
 ## Features
 
-*   Organize grids of feeds into customizable tabs, like Netvibes / iGoogle
-*   Import/Export tabs and feeds as OPML files (tested with exports from Netvibes).
-*   Add feeds via URL.
-*   Delete feeds.
-*   Create, rename, and delete tabs.
-*   Automatic background fetching of feed updates.
-*   Real-time UI updates when feeds are refreshed in the background, powered by Server-Sent Events (SSE).
-*   Mark items as read.
-*   Displays unread counts per feed and per tab.
-*   Basic persistence using a database.
+*   **Feed Management**: Add, delete, and edit RSS/Atom feeds.
+*   **Tabbed Organization**: Organize feeds into customizable tabs, similar to Netvibes and iGoogle.
+*   **OPML Support**: Import and export your feeds and tabs as OPML files.
+*   **Background Updates**: Automatically fetches feed updates in the background.
+*   **Real-Time UI**: The user interface updates in real-time when feeds are refreshed, thanks to Server-Sent Events (SSE).
+*   **Unread Tracking**: Mark items as read and see unread counts for each feed and tab.
+*   **Persistence**: Your data is saved in a persistent database.
+
+## Project Structure
+
+*   `.github/workflows/`: Contains GitHub Actions workflows for automated testing.
+*   `backend/`: The Python Flask backend.
+    *   `app.py`: The main Flask application file, containing API endpoints and application logic.
+    *   `feed_service.py`: Handles fetching, parsing, and processing of RSS/Atom feeds.
+    *   `models.py`: Defines the database schema using SQLAlchemy.
+    *   `test_app.py`, `test_feed.py`: Pytest tests for the backend.
+*   `frontend/`: The vanilla JavaScript frontend.
+    *   `index.html`: The main HTML file.
+    *   `script.js`: The main JavaScript file, containing all frontend logic.
+    *   `style.css`: The stylesheet for the application.
+*   `pod/`: Contains files for deploying the application with Podman.
+    *   `quadlet/`: Contains Quadlet files for managing the application with systemd.
+*   `scripts/`: Contains helper scripts for deployment and development.
 
 ## Production Deployment (Podman Pod with systemd using Quadlet)
 
 This section describes how to deploy SheepVibes using a Podman Pod managed by systemd user services, leveraging Quadlet for easier unit file management.
 
 ### Prerequisites
 
-- `podman` and `curl` installed (the deployment script will check for these).
-- Git (optional, if you prefer to clone the repository).
-- A modern version of Podman that includes Quadlet support.
+*   `podman` and `curl` installed.
+*   A modern version of Podman that includes Quadlet support.
+*   Git (optional, if you prefer to clone the repository).
 
 ### Setup Instructions
 
 1.  **Obtain the Deployment Script**:
-
-    For the stable version, always refer to the `main` branch:
     ```bash
-    # Stable version from main:
     curl -O https://raw.githubusercontent.com/sheepdestroyer/sheepvibes/main/scripts/deploy_pod.sh
     ```
 
 2.  **Make the Script Executable and Run It**:
-    Navigate to where you downloaded the script (or the repository root if cloned).
-    The script will fetch the necessary Quadlet unit files (e.g., `sheepvibespod.pod`, `sheepvibes-app.container`, `sheepvibes-db.volume`, etc.) from the `pod/quadlet/` directory in the GitHub repository (from the `main` branch, unless modified) and copy them to `~/.config/containers/systemd/`. Volume management is defined within these Quadlet files.
-
+    The script will download the necessary Quadlet files to `~/.config/containers/systemd/`.
     ```bash
-    chmod +x deploy_pod.sh # Or scripts/deploy_pod.sh if cloned
-    ./deploy_pod.sh      # Or scripts/deploy_pod.sh if cloned
+    chmod +x deploy_pod.sh
+    ./deploy_pod.sh
     ```
-    The script will check for dependencies, guide you through the process, and inform you of the next steps.
 
 3.  **Manage the Service**:
     After running the deployment script, you will be instructed to:
-    -   Reload systemd to recognize the new Quadlet files and generate systemd services:
+    -   Reload systemd to recognize the new Quadlet files:
         ```bash
         systemctl --user daemon-reload
         ```
-    -   Start the main pod service (which in turn starts all containers and creates volumes):
+    -   Start the main pod service:
         ```bash
         systemctl --user start sheepvibespod-pod.service
         ```
-    -   Check the status of the pod and its components:
+    -   Check the status of the pod:
         ```bash
         systemctl --user status sheepvibespod-pod.service
-        systemctl --user status sheepvibes-app.service
-        systemctl --user status sheepvibes-redis.service
-        # You can also check the status of volume services (they are Type=oneshot)
-        systemctl --user status sheepvibes-db-volume.service
-        systemctl --user status sheepvibes-redis-data-volume.service
         ```
-    -   View logs for the entire pod (follow):
+    -   View logs for the entire pod:
         ```bash
         journalctl --user -u sheepvibespod-pod.service -f
         ```
-    -   View logs for a specific container (e.g., `sheepvibes-app`):
-        ```bash
-        journalctl --user -u sheepvibespod-pod.service -t sheepvibes-app
-        # Or for more detailed logs of just the app container's service:
-        journalctl --user -u sheepvibes-app.service -f
-        ```
-    The `sheepvibes-redis` container runs within the same pod and is managed as part of `sheepvibespod-pod.service`. Network communication between the app and Redis occurs over `localhost` within the pod. Application data and Redis data are stored in Podman-managed volumes (e.g., `systemd-sheepvibes-db` and `systemd-sheepvibes-redis-data` by default), defined via `.volume` Quadlet files.
 
 4.  **Enable Auto-start (Optional)**:
-    The `pod/quadlet/sheepvibespod.pod` file includes an `[Install]` section with `WantedBy=default.target`. This means that after you run `systemctl --user daemon-reload` (as instructed by the `deploy_pod.sh` script), the main pod service (`sheepvibespod-pod.service`) is automatically configured to start when your user session begins.
-
-    No separate `systemctl --user enable sheepvibespod-pod.service` command is needed, and attempting to run it on the generated service will result in an error.
-
-    To verify auto-start, you can log out and log back in. The service should start automatically.
-
-    *Note on system boot*: For user services to start automatically when the system boots (i.e., without requiring an interactive login for that user), you may need to enable lingering for your user. This typically requires root privileges:
+    The `pod/quadlet/sheepvibespod.pod` file includes an `[Install]` section that enables the service to start automatically with your user session. For the service to start at boot (without requiring a login), you may need to enable lingering for your user:
     ```bash
     sudo loginctl enable-linger $(whoami)
     ```
 
 ### Accessing the Application
 
-Once started, the application will be accessible at `http://127.0.0.1:5000` by default. This is configured by the `PublishPort` setting in the `[Pod]` section of the `pod/quadlet/sheepvibespod.pod` file. If you need to access it from other machines, you might need to:
-1.  Adjust firewall settings on your server.
-2.  Modify the `PublishPort` setting in the `pod/quadlet/sheepvibespod.pod` file (e.g., change to `0.0.0.0:5000:5000`).
-    - If you modify it *before* running `deploy_pod.sh` (e.g., in a cloned repository), the script will use your modified version if it's fetching from your local clone or a specific branch.
-    - If you modify it *after* deployment by editing `~/.config/containers/systemd/sheepvibespod.pod`, you'll need to run `systemctl --user daemon-reload && systemctl --user restart sheepvibespod-pod.service`.
+Once started, the application will be accessible at `http://127.0.0.1:5000` by default. To access the application from other machines, you may need to modify the `PublishPort` setting in `~/.config/containers/systemd/sheepvibespod.pod` (e.g., to `0.0.0.0:5000:5000`) and then run `systemctl --user daemon-reload && systemctl --user restart sheepvibespod-pod.service`.
 
 ## Local Development
 
-This section describes how to set up SheepVibes for local development and testing. This typically involves cloning the repository to get all source files and the `Containerfile`.
+This section describes how to set up SheepVibes for local development.
 
 ### Prerequisites
 
-- Podman installed.
-- Git.
-- Python environment (optional, for direct backend/frontend work without containers).
+*   Podman
+*   Git
+*   Python 3 and `pip`
 
 ### Building the Container
 
@@ -115,16 +100,14 @@ This section describes how to set up SheepVibes for local development and testin
     ```
 
 2.  **Build the Image**:
-    Build the application image using the `Containerfile`:
     ```bash
     podman build -t localhost/sheepvibes-app -f Containerfile .
     ```
-    Alternatively, use the provided script:
+    Or use the provided script:
     ```bash
-    # Make sure it's executable first: chmod +x scripts/rebuild_container.sh
     ./scripts/rebuild_container.sh
     ```
-    After rebuilding the image, if you are using systemd for production, you must restart the service to use the new image: `systemctl --user restart sheepvibespod-pod.service` (this will recreate containers with the updated image if their `Pull` policy allows or if the image tag changed and Quadlet detects it). Podman typically restarts containers with the newest image version if the image name/tag in the `.container` file is `:latest` and the image is updated locally.
+    After rebuilding the image, if you are using systemd for production, you must restart the service to use the new image: `systemctl --user restart sheepvibespod-pod.service`.
 
 ### Running Locally with Podman
 
@@ -139,12 +122,8 @@ This section describes how to set up SheepVibes for local development and testin
     ```
 
 3.  **Run the Application Container**:
-    Create a local directory for the database:
     ```bash
     mkdir -p ./dev_data
-    ```
-    Run the application container, linking it to Redis and mounting the local data directory:
-    ```bash
     podman run -d --name sheepvibes-app-dev \
         --network sheepvibes-dev-network \
         -p 127.0.0.1:5001:5000 \
@@ -157,55 +136,36 @@ This section describes how to set up SheepVibes for local development and testin
         -e FLASK_RUN_HOST=0.0.0.0 \
         localhost/sheepvibes-app
     ```
-    You can then access the app at `http://127.0.0.1:5001`. Logs can be viewed with `podman logs sheepvibes-app-dev`.
-
-4.  **Using `run_dev.sh` (Alternative)**:
-    The `scripts/run_dev.sh` script provides a way to manage the local development containers. Review and modify it as needed for your local setup.
-    *(Note: You might need to update `scripts/run_dev.sh` if it's outdated or doesn't match the above setup. The script primarily focuses on running the backend directly without containers for faster iteration).*
+    The app will be accessible at `http://127.0.0.1:5001`.
 
 ### Direct Backend/Frontend Development
 
-This section is for developers who want to work on the Python backend or JavaScript frontend directly, without running the full application in Podman.
-
-1.  **Prerequisites:**
-    *   Ensure you have Python 3, `pip`, and a running Redis server (e.g., `podman run -d --name sheepvibes-redis-direct -p 127.0.0.1:6379:6379 redis:alpine`).
+1.  **Prerequisites**:
+    *   A running Redis server.
 
-2.  **Set up Backend Virtual Environment (requires cloning the repo):**
+2.  **Set up Backend Virtual Environment**:
     *   Navigate to the `backend` directory: `cd sheepvibes/backend`
     *   Create a virtual environment: `python -m venv venv`
-    *   Activate it: `source venv/bin/activate` (or `venv\Scripts\activate` on Windows)
+    *   Activate it: `source venv/bin/activate`
     *   Install dependencies: `pip install -r requirements.txt && pip install -r requirements-dev.txt`
 
-3.  **Run the Development Server (Flask Backend - requires cloning the repo):**
-    The `scripts/run_dev.sh` script can start the Flask backend server directly.
-    Ensure `CACHE_REDIS_URL` is set, e.g. `export CACHE_REDIS_URL=redis://localhost:6379/0`
+3.  **Run the Development Server**:
+    The `scripts/run_dev.sh` script can start the Flask backend server.
     ```bash
-    # from the repository root (e.g., cd sheepvibes)
     ./scripts/run_dev.sh
     ```
-    This will typically start the backend on `http://127.0.0.1:5000` (or as configured). The frontend is served statically by Flask in this mode.
 
 ## Configuration (Environment Variables)
 
-You can configure the application by passing environment variables.
-- When deploying with systemd using Quadlet (via `deploy_pod.sh`), the script downloads a set of default Quadlet files (e.g., `sheepvibes-app.container`, `sheepvibespod.pod`) from `pod/quadlet/`. To customize environment variables for the application:
-    1. Modify the `Environment=` lines within the `pod/quadlet/sheepvibes-app.container` file (or your local copy at `~/.config/containers/systemd/sheepvibes-app.container` after deployment).
-    2. After modification, run `systemctl --user daemon-reload && systemctl --user restart sheepvibespod-pod.service`.
-- When using `podman run` directly, use the `-e` flag.
-- When running the backend directly, set them in your shell environment.
-
-*   `DATABASE_PATH`: The full path *inside the container* (or on the host if running directly) where the SQLite database file should be stored. Defaults to `/app/data/sheepvibes.db` (container) or `backend/sheepvibes.db` (direct script). This path is relative to the volume mount specified in `sheepvibes-app.container`.
-*   `UPDATE_INTERVAL_MINUTES`: The interval (in minutes) at which the application checks feeds for updates. Defaults to `15`.
-*   `CACHE_REDIS_URL`: The connection URL for the Redis server.
-    *   Pod default (from `sheepvibes-app.container`): `redis://localhost:6379/0` (since Redis is in the same pod).
-    *   `podman run` dev example: `redis://sheepvibes-redis-dev:6379/0`
-    *   Direct script: `redis://localhost:6379/0` (if Redis is on host)
-*   `FLASK_APP`: Path to the Flask application. Defaults to `backend.app`.
-*   `PYTHONPATH`: Python module search path. Defaults to `/app` in container.
-*   `FLASK_RUN_HOST`: Host for Flask development server. Defaults to `0.0.0.0` to be accessible.
+*   `DATABASE_PATH`: The path to the SQLite database file.
+*   `UPDATE_INTERVAL_MINUTES`: The interval in minutes for checking for feed updates.
+*   `CACHE_REDIS_URL`: The URL for the Redis server.
+*   `FLASK_APP`: The path to the Flask application.
+*   `PYTHONPATH`: The Python module search path.
+*   `FLASK_RUN_HOST`: The host for the Flask development server.
 
 ## Contributing
-(Contributions are welcome. Please open an issue or PR.)
+Contributions are welcome. Please open an issue or pull request.
 
 ## License
-(This project is under a GNU General Public License v3.0 License)
+This project is licensed under the GNU General Public License v3.0.

TODO.md

@@ -93,7 +93,7 @@ This document outlines the steps to build the SheepVibes RSS aggregator.
     *   [x] Minimize frontend re-renders.
 *   [x] **Documentation:**
     *   [x] Write `README.md` covering setup instructions (building/running with Podman), configuration, and basic usage.
-    *   [x] Add comments to the code.
+    *   [x] Add comments to the code (JSDoc for frontend, Google Style for backend).
 *   [x] **Testing:**
     *   [x] Add basic unit tests for backend logic (feed parsing, database interactions).
     *   [x] Add basic unit tests for backend logic (API endpoints).
@@ -109,8 +109,8 @@ This document outlines the steps to build the SheepVibes RSS aggregator.
 
 ## Future Considerations
 
+*   [x] Import/Export OPML feed lists.
 *   [ ] Widget resizing/reordering (drag and drop).
-*   [ ] Import/Export OPML feed lists.
 *   [ ] Different widget view types (e.g., list vs. expanded).
 *   [ ] User authentication.
 *   [ ] Keyword filtering/highlighting within feeds.