Software Requirements Specification (SRS)

# Software Requirements Specification (SRS)

## 1. Introduction
### 1.1 Purpose
Describe the requirements for a fully self-hosted Personal Kanban + GTD web application that unifies capture, clarification, automation, recurring tasks, and analytics without relying on third-party automation platforms.

### 1.2 Scope
The system provides a configurable Kanban board aligned with GTD principles, rich capture mechanisms (web, PWA, IMAP, browser extension), an automation/rules engine, recurring task scheduler, LeanKit-style analytics, and deployment tooling for user-owned infrastructure. The scope includes backend services (Node/Nest/BullMQ), frontend SPA/PWA, browser extension, workers, and DevOps artifacts.

### 1.3 Definitions & Acronyms
- **GTD**: Getting Things Done productivity framework.
- **WIP**: Work In Progress.
- **CFD**: Cumulative Flow Diagram.
- **RRULE**: Recurrence rule format from iCalendar.
- **PWA**: Progressive Web App.
- **TaskEvent**: Immutable record of task lifecycle changes.

### 1.4 References
- User-provided workflow description and LeanKit/GTD article summary.
- implementation-plan.md (project execution strategy).
- architect.mdc (architecture guidance).

## 2. System Overview
### 2.1 Product Perspective
The product is a standalone platform deployed on infrastructure owned by the user. It exposes web/PWA frontends, REST/GraphQL APIs, WebSocket channels, and optional browser/mobile capture integrations. No reliance on SaaS automation services is permitted; only standard protocols (HTTPS, IMAP, SMTP) are allowed.

### 2.2 User Classes & Characteristics
- **Primary user**: knowledge worker needing GTD-style organization and contextual execution.
- **Optional collaborators**: family/assistant participants (future multi-user support considered).
- **System operator**: person deploying/maintaining the stack (may be same as primary user).

### 2.3 Operating Environment
- Backend: Node 20+, NestJS 10+, BullMQ 4+, Postgres 14+, Redis 6+.
- Client: modern browsers supporting ES2022, Web Speech API (optional), service workers.
- Infrastructure: Docker/Kubernetes, HTTPS reverse proxy, IMAP/SMTP endpoints managed by user.

### 2.4 Assumptions & Dependencies
- Users can provision and secure their own servers, mailboxes, TLS certificates.
- Reliable connectivity between services (API, Redis, Postgres, IMAP, SMTP).
- Browser extension distribution handled by user (self-signed or store submission).
- Voice capture uses local browser APIs; no cloud speech services.

## 3. Functional Requirements
### 3.1 Board & Task Management
- Configurable columns/lanes with defaults (Input, Define Next Actions, Someday/Maybe, Waiting For, Won't Do, Done Immediately, context columns such as Email/Meetings/Phone/Read/Desk).
- Drag-and-drop task movement with WIP limit enforcement (warn/block modes).
- Task fields: title, description, context enum, tags (many-to-many), project, column, due date, checklist items, waiting-for text/contact, needs-breakdown flag, metadata JSON (URLs, email IDs), timestamps (`created_at`, `updated_at`, `completed_at`, `last_moved_at`).
- Project entity with description, desired outcome, status, and linked tasks; project filters in board view.
- Context filters, Waiting-on view, Someday/Maybe list, Inbox-only triage view.

### 3.2 Capture Mechanisms
- **Web/PWA quick add**: single input supporting free text + auto URL detection; optional Web Speech API capture with fallback.
- **Offline capture queue**: PWA stores unsent entries and syncs when online.
- **Browser extension**: WebExtension capturing tab title/URL, optional notes, sending signed request to capture endpoint.
- **Mobile widget/PWA shortcut**: minimal form hitting same API.
- **Email import**: IMAP poller fetches unseen messages, stores metadata/attachments (local/S3) and creates Input queue cards; handles dedupe via UID and marks processed mail via configurable action (flag, archive, delete).

### 3.3 Clarification Flow (GTD Wizard)
- Wizard retrieves next unprocessed Input card and guides through steps: actionable?, two-minute rule, define next action, choose context, assign project, specify waiting-for entity, toggle needs-breakdown, set due date.
- Quick actions: move to Done Immediately, Won't Do, Someday/Maybe, Waiting For, or relevant context lane.
- Keyboard shortcuts and timer metrics for throughput tracking.

### 3.4 Automation & Rules Engine
- Rule model: trigger + condition set + ordered actions stored as JSON with versioning and audit logs.
- Supported triggers: task created/moved/completed, column change, stale detection, scheduled time (cron/RRULE), email received, manual button, webhook capture event.
- Conditions: column, context, tags, project, due date windows, age (created or last moved), metadata values, stale flag.
- Actions: create task (optionally from template), update fields, move columns, apply tags, add checklist items, send notifications/email, mark related email as processed, enqueue custom webhooks, stop further rules.
- Execution via BullMQ processors with retries, dedupe keys, and dead-letter queues; rule run logs stored for audit.

### 3.5 Recurring Templates & Scheduler
- Template entity storing task payload, checklist, target column/context, WIP override, `rrule`/cron expression, timezone, skip/next-run metadata.
- Scheduler worker evaluates due templates, enqueues task creation jobs, records outcomes, handles skipped/missed occurrences, and adjusts for DST.
- Weekly Review template includes checklist, links to analytics/stale view, and optional email reminder.

### 3.6 Analytics & Review
- TaskEvent logging for every lifecycle change (create/move/update/complete/stale).
- Snapshot service aggregating column counts hourly/daily for CFD.
- Metrics: Cumulative Flow Diagram, lead time (creation→completion), cycle time (entering work column→done), throughput, WIP breach history, stale tasks list (>=7 days since last move), aging WIP chart.
- Weekly review dashboard summarizing stale work, Someday review list, Waiting-for items, WIP status, throughput trends, and checklist completion.

### 3.7 Notifications & Reminders
- Channels: in-app (WebSocket + push), email via user-controlled SMTP.
- Events: rule outputs, recurring task creation, weekly review reminder, stale task alert, IMAP failures, automation errors.
- Notification preferences per user (quiet hours, channel opt-in).

### 3.8 Security & Settings
- Authentication via session (web) and JWT (extensions/mobile) with refresh tokens; optional WebAuthn.
- CSRF protection for browser forms, rate limiting for capture endpoints, per-device API tokens.
- Settings for WIP limits, contexts, columns, stale thresholds, IMAP/SMTP credentials, automation toggles.

## 4. External Interface Requirements
### 4.1 User Interfaces
- Responsive SPA/PWA supporting dark/light themes, drag/drop board, wizard modal, analytics dashboards, capture bar on every page.
- Browser extension popup (minimal UI) and context-menu entry for quick capture.
- Weekly Review view combining metrics with actionable lists.

### 4.2 APIs
- REST/GraphQL endpoints for boards, columns, tasks, projects, tags, rules, templates, notifications, analytics.
- WebSocket namespace for live board updates and notification stream.
- Auth endpoints (login, refresh, token revoke).
- Capture webhooks with signed HMAC tokens.

### 4.3 Hardware & Software Interfaces
- IMAP client (e.g., Dovecot) via TLS, SMTP server via TLS with authentication.
- Optional object storage (S3-compatible) for email attachments.
- No third-party automation integrations allowed.

### 4.4 Communications Protocols
- HTTPS for all web APIs, WSS for real-time channels.
- IMAPS (993) and SMTPS (465/587) for email services.
- Redis protocol for BullMQ queues and pub/sub.

## 5. System Architecture
- **Frontend**: React + Vite (TypeScript) PWA, service worker for offline capture, state managed via Zustand/Redux, component library with accessibility support.
- **Backend API**: NestJS modular monolith exposing REST/GraphQL/WebSocket. Modules: Auth, Board, Task, Project, Tag, Rule, Template, Analytics, Notification, Integration.
- **Worker Service**: Nest microservice executing BullMQ queues (rules, scheduler, IMAP poller, analytics snapshotter, notification dispatcher).
- **Data Layer**: Prisma/TypeORM connecting to Postgres (JSONB for metadata), migrations tracked via schema versioning.
- **Eventing**: Transactional outbox table ensures TaskEvents published to Redis/BullMQ; WebSocket gateway subscribes to Redis channels per board.
- **Deployment**: Docker images for API, worker, web; Compose or Helm charts; Nginx/Caddy reverse proxy; OpenTelemetry collectors; Prometheus/Grafana stack.

## 6. Data Design
| Entity | Description | Key Fields |
| --- | --- | --- |
| `users` | Account + settings | id, email, name, timezone, notification prefs |
| `boards` | Kanban boards | id, owner_id, name, config JSON |
| `columns` | Lanes with WIP | id, board_id, name, type enum, wip_limit, order |
| `tasks` | Work items | id, board_id, column_id, title, description, context, project_id, waiting_for, due_at, needs_breakdown, metadata JSON, timestamps |
| `task_checklist_items` | Subtasks | id, task_id, text, done, order |
| `projects` | GTD projects | id, owner_id, name, outcome, status |
| `tags` / `task_tags` | Tag taxonomy | id, name, color |
| `task_events` | Lifecycle records | id, task_id, type, from_column, to_column, payload JSON, timestamp |
| `rules` | Automation definitions | id, board_id, name, enabled, trigger JSON, conditions JSON, actions JSON, priority |
| `rule_runs` | Audit logs | id, rule_id, event_id, status, started_at, finished_at, error |
| `recurring_templates` | Task templates | id, board_id, payload JSON, rrule, timezone, next_run_at, skip flags |
| `column_snapshots` | Analytics | id, board_id, column_id, timestamp, count |
| `notifications` | Messages | id, user_id, channel, payload, delivered_at |
| `integration_endpoints` | IMAP/SMTP/Webhook configs | id, type, credentials ref, settings |

Indexes: board/column combos, last_moved_at, stale flag, rule trigger fields, template schedules. Foreign keys with cascading deletes where appropriate.

## 7. Non-Functional Requirements
- **Performance**: API p95 < 300 ms for board operations; WebSocket update fan-out within 200 ms; BullMQ queue latency < 2 s under nominal load; IMAP polling cycle completes within configured interval.
- **Availability**: 99.5% uptime target for single-node deployment; graceful degradation (capture still available if analytics offline).
- **Reliability**: Transactional outbox ensures no lost events; retry/backoff for IMAP and SMTP interactions; automated backups nightly.
- **Security**: HTTPS, CSRF protection, input validation, RBAC-ready auth, encrypted secrets (libsodium), audit log retention (90+ days), OWASP best practices.
- **Scalability**: Horizontal scaling for API and worker containers; Redis + Postgres tuned with connection pooling; stateless API nodes with shared session store (Redis).
- **Maintainability**: Modular Nest architecture, shared DTO packages, lint/test CI, ADR tracking, feature flag support.
- **Usability**: WCAG 2.1 AA compliance target; keyboard-first wizard; drag/drop accessible via alternative controls; responsive layout for desktop/tablet/mobile.
- **Compliance/Privacy**: Data stored only on user infrastructure; configurable retention policies for email artifacts.

## 8. Operational Requirements
- **Deployment pipeline**: GitHub Actions (lint, unit, integration, e2e, docker build, deploy). Promotion requires manual approval + test evidence.
- **Monitoring**: Prometheus metrics (API latency, queue depth, IMAP errors), Grafana dashboards, alert rules (Slack/email) for critical events.
- **Backups**: Automated Postgres dumps + WAL, Redis snapshots, object storage replication for email bodies, documented restore drills.
- **Logging**: Structured JSON logs with correlation IDs; centralized log aggregation (Loki/ELK) for search.
- **Localization**: English default; architecture supports i18n for copy and date formats.

## 9. Appendices
### 9.1 Glossary
- **Clarification**: GTD step for deciding next action.
- **Stale task**: Task with `last_moved_at` older than configured threshold.
- **Rule run**: Execution instance of automation rule triggered by event/schedule.

### 9.2 Open Issues
- Confirm initial requirement for multi-user sharing vs single-user mode.
- Decide on storage target for raw email bodies (local disk or S3-compatible service).
- Determine analytics data retention duration.
- Validate timezone handling rules for recurring templates across DST changes.