mirror/TimeTracker
1
0
Fork 0
mirror of https://github.com/DRYTRIX/TimeTracker.git synced 2026-04-27 07:50:29 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
d715cbacaa2190af0bc34a661269882783bce3c8
TimeTracker/REQUIREMENTS.md
T
Dries Peeters c92f9e196b V1.0.0 version push
2025-08-16 21:49:43 +02:00

14 KiB
Raw Blame History

Raspberry Pi Time Tracker — Software Requirements Document (SRD)

Version: 1.0 Date: 2025-08-15 Owner: (to be assigned)

1. Purpose & Scope

This SRD defines requirements for a Python application that primarily runs on a Raspberry Pi (RPI) using Docker, with a web-based frontend. The application tracks time across multiple projects with two tracking modes: manual entry and automatic timers that persist even if the browser is closed. The system supports per-user tracking with simple username-only login (no passwords) and provides project overviews, reporting, and per-entry annotations. No external REST API is required.

In Scope

  • Project management (name, client, brief description, billing information)
  • Per-user time tracking
  • Manual time entry (start/end date & time + project)
  • Automatic timers that continue running server-side after browser close
  • Project-level overviews of time spent
  • Ability to add extra information (notes/metadata) per time entry
  • Web-based UI (sleek, modern, and user-friendly)
  • Execution on Raspberry Pi via Docker
  • Local data storage and backups

Out of Scope (for v1)

  • Public internet exposure (LAN only)
  • External integrations (e.g., third-party invoicing, calendars)
  • Advanced permissions/roles beyond simple user identification
  • Mobile apps (web frontend should be responsive)
  • External REST API endpoints

2. Stakeholders & Users

  • End Users: Team members who log time per project.
  • Project Managers / Admins: Configure projects, view summaries, export reports.
  • IT/Ops: Deploy and maintain the Dockerized application on RPI.

3. Definitions & Glossary

  • Automatic Timer: A server-side, long-lived timer associated with a user and project that continues running even if the browser is closed.
  • Entry Notes/Metadata: Additional text fields or tags recorded with each time entry.
  • Billing Information: Basic fields such as billing rate, billable flag, PO/Cost center, or invoicing reference stored on the project.

4. System Overview

A Python backend (Flask recommended) runs inside Docker on a Raspberry Pi. The frontend is a server-rendered web UI with light interactive components and optional WebSocket events for live timers. Data persists locally (SQLite by default) with optional scheduled backups.

5. Functional Requirements

5.1 Authentication & User Identity

  1. Username-only Login:

    • Users enter a username to start a session; no password.
    • If username does not exist, offer to create it (admin-configurable setting).
    • Persist session via secure cookies.

  2. Access Model:

    • All logged-in users can create and edit their own time entries.
    • Admin users can manage projects, view all reports, and edit any entry.
    • Admin assignment via config or first user bootstrap.

5.2 Project Management

  1. Create/Read/Update/Archive Projects with fields:

    • Project Name (required)
    • Client (required)
    • Brief Description (optional)
    • Billing Information (see 5.2.2)
    • Status: Active/Archived

  2. Billing Information Fields (configurable subset):

    • Billable (Yes/No)
    • Hourly Rate (currency-aware)
    • Billing Reference (e.g., PO number)
    • Default Time Rounding (e.g., 1/5/15 minutes) (optional)

5.3 Manual Time Entry

  1. Create Manual Entry:

    • Required: Project, Start DateTime, End DateTime
    • Optional: Notes/Description (free text), Tags
    • Validation: End must be after Start; no overlaps check (configurable) with warning.

  2. Edit/Delete Entry: Users can edit or delete their own entries; Admins can edit any.

  3. Bulk Operations: Optional bulk edit for tags or project reassignment.

5.4 Automatic Timer Tracking

  1. Start Timer: User selects project and clicks Start.
  2. Server-Side Persistence: Timer continues running on the server even if the browser closes, device sleeps, or network drops.
  3. Stop Timer: User clicks Stop from any browser session or device; server finalizes entry (start->stop).
  4. Resilience: If the RPI restarts, active timers are restored using last known start time and a flag indicating “active”.
  5. Single Active Timer per User: Enforced; starting a new timer stops the previous one (configurable).
  6. Idle/AFK (optional v1.1): After N minutes of inactivity, prompt on next visit to confirm whether to subtract idle time.

5.5 Time Entry Annotations & Metadata

  • Notes Field: Rich text (plain text in v1, markdown in v1.1) per entry.
  • Tags: Freeform comma-separated tags; auto-suggest from existing tags.
  • Edit History (optional): Keep non-destructive audit trail for edits.

5.6 Reporting & Overview

  1. Project Overview:

    • Total time spent, grouped by user and by time period (day/week/month).
    • Filters: date range, user, tags, billable/non-billable.
    • Summaries: total hours, billable hours, estimated cost (rate × hours).

  2. User Overview:

    • Personal dashboard of own entries and totals.

  3. Entry List & Detail:

    • Paginated list with search, sort by date/project/duration.

  4. Exports:

    • CSV export for entries and summaries.

5.7 Notifications & Feedback

  • Inline validations, toasts for success/errors.
  • Live timer display (mm:ss) with WebSocket/SSE updates.

5.8 Administration

  • User list (usernames), role assignment (User/Admin).
  • Project archival/unarchive.
  • Configuration page (see 6.4) with authentication mode, rounding rules, timezone, currency.

6. Non-Functional Requirements

6.1 Platform & Runtime

  • Target Hardware: Raspberry Pi 4 (2GB+) recommended.
  • OS: Raspberry Pi OS (64-bit) or compatible Linux.
  • Containerization: Docker + docker-compose.
  • Python: 3.11+.

6.2 Performance

  • Support 10–25 concurrent users on LAN with sub-200 ms page actions.
  • Timer accuracy within ±1 second over 24 hours.

6.3 Reliability & Resilience

  • Automatic restart with restart: unless-stopped in Compose.
  • Graceful shutdown; in-flight timers persisted.
  • Periodic health checks and liveness endpoints (internal only).

6.4 Configurability

  • .env/config UI for: timezone (default Europe/Brussels), currency, default rounding, allow self-register, single-active-timer, idle timeout, export delimiter.

6.5 Security

  • LAN-only by default; bind to private IP.
  • Reverse proxy optional (Caddy/nginx) for TLS on LAN.
  • Username-only login; display clear banner that this is an internal tool.
  • CSRF protection disabled for simplified development; secure cookies; session timeout.
  • Role-based checks server-side.

6.6 Privacy & Data Retention

  • Store minimal PII (username only).
  • Retain entries indefinitely unless purged. Admin-configurable retention and backup.

6.7 Localization & Timezones

  • System default timezone configurable; all storage in UTC; UI displays local time.
  • Handle DST transitions; prevent overlapping/invalid times via UI validation.

6.8 Accessibility

  • WCAG 2.1 AA-aligned basics: keyboard navigation, color-contrast, focus states.

7. Architecture & Design

7.1 High-Level Components

  • Web App (Flask): Server-rendered templates (Jinja2) + HTMX/Alpine.js for interactivity.
  • Background Scheduler: APScheduler (or asyncio task) for periodic jobs (backups, health checks).
  • Real-Time Layer: WebSocket or Server-Sent Events for live timer updates.
  • Storage: SQLite with WAL mode; upgrade path to PostgreSQL.
  • Reverse Proxy (optional): Caddy/nginx container for TLS and static asset caching.

7.2 Data Model (Initial Schema)

users

  • id (PK)
  • username (unique, required)
  • role (enum: user, admin)
  • created_at

projects

  • id (PK)
  • name (required)
  • client (required)
  • description (text)
  • billable (bool)
  • hourly_rate (decimal, nullable)
  • billing_ref (text, nullable)
  • status (enum: active, archived)
  • created_at, updated_at

time_entries

  • id (PK)
  • user_id (FK → users)
  • project_id (FK → projects)
  • start_utc (datetime)
  • end_utc (datetime, nullable when active)
  • duration_seconds (int, computed on finalize)
  • notes (text)
  • tags (text)
  • source (enum: manual, auto)
  • edited_at

settings

  • id (singleton)
  • timezone, currency, rounding_minutes, single_active_timer, allow_self_register, idle_timeout_minutes

Indexes on (user_id, start_utc), (project_id, start_utc), and active entries (end_utc IS NULL).

7.3 Timer Persistence Logic

  • On Start: create time_entries row with end_utc=NULL and source=auto.
  • Heartbeat optional; not required for persistence.
  • On Stop: set end_utc, compute duration_seconds applying rounding rules.
  • On Server Restart: query all end_utc IS NULL and treat as still running since start_utc.

7.4 UI/UX Guidelines

  • Clean, modern layout with responsive design.

  • Primary views:

    1. Dashboard: Active timer status, quick Start/Stop, recent entries.
    2. Projects: List, filter, create/edit, archive.
    3. Log Time: Manual entry form.
    4. Reports: Project and user overviews with filters and CSV export.
    5. Admin: Users, settings.

  • Components: sticky header timer, toasts, modal dialogs, date/time picker, tag chips.

8. Deployment & Operations

8.1 Docker Compose (concept)

  • app (Flask + Gunicorn)
  • db (optional Postgres; otherwise SQLite volume in app)
  • proxy (optional Caddy/nginx)
  • Volumes for /data (DB, exports, backups).

8.2 Environment Variables

  • TZ, CURRENCY, ROUNDING_MINUTES, ALLOW_SELF_REGISTER, SINGLE_ACTIVE_TIMER, IDLE_TIMEOUT_MINUTES, ADMIN_USERNAMES.

8.3 Backup & Restore

  • Nightly SQLite copy to /backups/YYYY-MM-DD/ with retention policy.
  • Manual on-demand export (zip: DB + CSVs of key tables).

8.4 Monitoring

  • Health endpoint /_health (no auth) for local check.
  • Logs to stdout; optional file rotation.

9. Security Considerations

  • Username-only login is weak; mitigate by LAN isolation, optional reverse proxy auth, and kiosk usage.
  • CSRF protection disabled; use SameSite cookies; disable framing.
  • Rate-limit login attempts by IP to prevent session abuse.

10. Compliance & Legal

  • Internal tool; ensure local employment/time-tracking rules if used formally (outside v1 scope).

11. Acceptance Criteria (Sample)

  1. Users can create projects with client and billing fields.
  2. Users can log manual entries with start & end times and notes.
  3. Users can start a timer, close the browser, reopen, and see the timer still running.
  4. Only one active timer per user (by default).
  5. Project overview shows total hours per user for a chosen date range.
  6. CSV export contains correct rows and computed durations.
  7. System restarts do not lose active timers or historical entries.
  8. Admin can archive a project; archived projects cannot be chosen for new entries.
  9. UI renders well on desktop and mobile and passes basic keyboard navigation.

12. Test Cases (Illustrative)

  • TC-01: Create project with required fields → Project listed as Active.
  • TC-02: Manual entry with end before start → Validation error displayed.
  • TC-03: Start timer, close browser, wait 2 minutes, reopen, stop → Duration ≥ 120s.
  • TC-04: Start timer A, then start timer B → Timer A auto-stops (if configured).
  • TC-05: Edit entry notes and tags → Changes persist and appear in reports.
  • TC-06: Archive project, attempt to log time → Not selectable in new entry form.
  • TC-07: CSV export for project/date range → Matches on-screen totals.
  • TC-08: RPI reboot → Active timers restored, dashboard reflects running state.
  • TC-09: CSRF protection disabled - no CSRF validation required.

13. UI Wireframe Descriptions (Textual)

  • Login: Username input, “Continue” button, disclaimer about internal use.
  • Dashboard: Header with current user + active timer (project name, elapsed). Large Start/Stop button, quick project selector, recent entries table with inline edit.
  • Projects: Card list with name, client, billable badge, actions (Edit, Archive).
  • Log Time: Form with project dropdown, start/end pickers, notes, tags.
  • Reports: Filters row (date range, user, project, tags), totals cards, table, export button.
  • Admin: Users list with role toggles, settings form.

14. Future Enhancements (Backlog)

  • Idle detection and retroactive adjustments.
  • Mobile PWA installability and offline caching for UI.
  • Calendar and Kanban views; week grid editor.
  • Rate cards by client; multi-currency.
  • LDAP/SSO or reverse-proxy auth (e.g., Authelia) for stronger security.
  • REST API (if needed) or WebDAV/ICS export.
  • PDF report templates and invoice drafts.

15. Constraints & Assumptions

  • LAN-only deployment; minimal threat model.
  • No external REST API required.
  • SQLite is sufficient for initial scale; PostgreSQL available if needed.

16. Appendix: Example docker-compose.yml (Skeleton)

services:
  app:
    image: timetracker:latest
    build: .
    environment:
      - TZ=Europe/Brussels
      - ROUNDING_MINUTES=1
      - SINGLE_ACTIVE_TIMER=true
      - ALLOW_SELF_REGISTER=true
      - ADMIN_USERNAMES=admin
    ports:
      - "8080:8080"
    volumes:
      - app_data:/data
    restart: unless-stopped

  # Optional reverse proxy (TLS on LAN)
  proxy:
    image: caddy:latest
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - app
    restart: unless-stopped

volumes:
  app_data:
  caddy_data:
  caddy_config:

17. Appendix: Data Dictionary (Selected Fields)

  • projects.hourly_rate: Decimal(9,2), nullable; interpreted in settings.currency.
  • time_entries.tags: CSV string; UI presents chips; stored raw for simplicity.
  • time_entries.duration_seconds: Calculated as round_to(duration, rounding_minutes) when finalized.

End of Document

Reference in New Issue View Git Blame Copy Permalink