# TaskFlow – Complete Documentation

This document covers TaskFlow from setup to daily use: features, installation, APIs, webhooks, and tutorials for admins and end users.

---

## Table of contents

1. [Overview & features](#1-overview--features)
2. [Installation](#2-installation)
3. [Configuration](#3-configuration)
4. [User roles](#4-user-roles)
5. [Tutorial: End users](#5-tutorial-end-users)
6. [Tutorial: Admins](#6-tutorial-admins)
7. [API reference](#7-api-reference)
8. [Webhooks](#8-webhooks)
9. [Slack integration](#9-slack-integration)
10. [Inbound email](#10-inbound-email)
11. [Deployment & operations](#11-deployment--operations)

---

## 1. Overview & features

TaskFlow is a task and project management application with workspaces, projects, task lists, and tasks. It supports notifications, reminders, Slack, inbound email, webhooks, time tracking, and reports.

### Core concepts

- **Workspace** – Top-level tenant. Users and projects belong to one workspace.
- **Project** – Contains task lists and tasks. Can be **private** (only you) or **shared** (with members).
- **Task list** – Column or section inside a project (e.g. “To Do”, “In Progress”, “Done”).
- **Task** – Single work item: title, description, status, priority, due date/time, assignees, tags, comments, attachments, dependencies, time entries.

### Main features

| Feature | Description |
|--------|-------------|
| **Dashboard** | Tasks due today, overdue, completed this week, recent activity, team overview (for supervisors). |
| **Projects & task lists** | Create/edit/archive/restore projects; add lists; reorder lists and tasks. |
| **Tasks** | Create, edit, move, duplicate, archive; status (todo, in_progress, review, done); priority (low, medium, high, urgent); due date/time; assignees (RACI-style: responsible, accountable, consulted, informed); tags; subtasks; dependencies. |
| **Comments & attachments** | Comments on tasks; file attachments with type/size limits. |
| **Notifications** | Assignment, reminders (1hr before, deadline, overdue), comment notifications; email, Slack DM, push (device tokens); optional pause per task. |
| **My tasks** | Tasks assigned to you; filter by project, status, due date. |
| **Search** | Full-text search over tasks (title, description); saved filters. |
| **Reports** | Team dashboard, completion, overdue trends, workload, projects summary, time tracking; optional CSV export. |
| **Templates** | Save a task as a template; apply to create new tasks; personal or shared with workspace. |
| **Time tracking** | Start/stop timer on tasks; view entries; today summary; project time summary. |
| **Webhooks** | Outgoing HTTP POST to your URL on task/project events; HMAC signature; delivery history. |
| **Slack** | OAuth connect; create/list/overdue/done via `/task` command; create from message (interactive); optional project channel. |
| **Inbound email** | Send email to project/workspace address to create tasks (e.g. Mailgun). |
| **API** | REST API v1 with token auth (Sanctum); projects, tasks, lists, comments, attachments, notifications, reports, webhooks, etc. |
| **Health check** | `GET /api/health` for status, DB, Redis, queue. |

---

## 2. Installation

### Requirements

- PHP 8.2+ (8.4 recommended), extensions: bcmath, ctype, curl, dom, fileinfo, json, mbstring, openssl, pdo_mysql, tokenizer, xml
- MySQL 8.0+ or MariaDB 10.6+
- Redis 6+ (sessions, cache, queues)
- Composer 2.x
- Node.js & npm (for frontend assets)

### Local development

```bash
# Clone and enter project
git clone <repo-url> taskflow && cd taskflow

# Install PHP dependencies
composer install

# Copy environment and generate key
cp .env.example .env
php artisan key:generate

# Configure .env: DB_*, REDIS_*, QUEUE_CONNECTION=redis, CACHE_STORE=redis, etc.

# Run migrations
php artisan migrate

# (Optional) Seed data
# php artisan db:seed

# Install frontend dependencies and build
npm install && npm run build

# Start queue workers (separate terminal) if using Redis queue
php artisan queue:work
```

Serve the app with Laravel Herd, `php artisan serve`, or your usual stack. Default Herd URL: `https://task-flow.test`.

### Production

See [Deployment & operations](#11-deployment--operations) and the `deploy/` folder: `deploy/README.md`, `deploy.sh`, `.env.production.example`, `deploy/nginx.example.conf`, `supervisord.conf.example`.

---

## 3. Configuration

### Environment (.env)

| Variable | Purpose |
|----------|---------|
| `APP_NAME`, `APP_ENV`, `APP_DEBUG`, `APP_URL` | Application identity and URL. |
| `DB_*` | Database connection. |
| `REDIS_*` | Redis for cache, session, queue. |
| `CACHE_STORE` | `redis` recommended in production. |
| `QUEUE_CONNECTION` | `redis` for async jobs. |
| `SESSION_DRIVER` | `redis` in production. |
| `MAIL_*` | SMTP (or mailgun, etc.) for notifications. |
| `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_SIGNING_SECRET`, `SLACK_REDIRECT_URI`, `SLACK_BOT_TOKEN` | Slack app (see [Slack integration](#9-slack-integration)). |
| `MAILGUN_WEBHOOK_SIGNING_KEY`, `INBOUND_EMAIL_PROVIDER` | Inbound email (e.g. Mailgun). |
| `FAILED_JOBS_NOTIFY_EMAIL` | Email to notify when a queue job fails after retries. |

### Scheduler

Reminders and scheduled tasks run via the Laravel scheduler. Add to crontab:

```cron
* * * * * cd /path/to/taskflow && php artisan schedule:run >> /dev/null 2>&1
```

---

## 4. User roles

| Role | Capabilities |
|------|----------------|
| **Owner** | Full access; manage users; Slack sync; webhooks; can assign supervisor. |
| **Admin** | Same as owner for user management, webhooks, Slack sync; can manage project members. |
| **Member** | Use projects/tasks they have access to; no user management or webhook settings. |

Visibility:

- **Private project** – Only the creator sees it (and tasks inside).
- **Shared project** – Creator + added members (with role admin/member) see it. Project admins can add/remove members.

---

## 5. Tutorial: End users

### Sign up and log in

1. Open the app URL (e.g. `https://task-flow.test`).
2. **Register**: name, email, password. You are placed in a workspace (first user is owner).
3. **Log in**: email + password. Optionally use “Log in with Slack” if the workspace has Slack connected.

### Dashboard

- After login you see the **Dashboard**: tasks due today, overdue, counts (completed this week, total active), recent activity, and (if you have direct reports) a team overview.
- Click a task to open the project and task detail.

### Projects and tasks

1. **Projects** – From the nav, open **Projects**. Create a project (name, optional description, color, visibility: private or shared).
2. **Open a project** – You see task lists and tasks. Switch view: list / board / calendar if available.
3. **Create a task** – Add a task in a list: title, optional description, due date/time, priority, assignees (in shared projects). You can add tags and assign yourself or others.
4. **Edit a task** – Open the task, change title, description, status, priority, due date, list, assignees, or add comments/attachments.
5. **Move tasks** – Drag between lists or use move action.
6. **Status** – todo → in_progress → review → done. Marking done sets `completed_at` and can trigger notifications/webhooks.

### Notifications

- **Notifications** in the nav: assignment, reminders (1hr, deadline, overdue), comment mentions.
- Open a notification to go to the task; mark as read or “Read all”.
- In task detail you can **pause reminders** for that task (e.g. 1 hour) so you are not reminded until after the pause.

### My tasks

- **My tasks** shows tasks assigned to you. Filter by project, status, due date as needed.

### Search and filters

- **Search** – Use the search page or API to find tasks by text. You can save filters for quick reuse.

### Reports

- **Reports** – Team view (for supervisors: direct reports’ counts and tasks), completion, overdue trends, workload, projects summary, time. Use date range and optionally export CSV via API.

### Profile and preferences

- **Settings → Profile**: update name, email, password; notification preferences (channels, digest).

### Time tracking

- On a task you can **start** a timer; **stop** it from the task or from “running” time entry. View time entries on the task and use **Time summary** (today) or project time summary in API/reports.

### Templates

- **Settings → Templates**: create a template from an existing task or from scratch; edit; duplicate; share with workspace or keep personal. **Apply** a template to create a new task from it (web or API).

---

## 6. Tutorial: Admins

### User management (owner/admin)

1. **Settings → Users** – List workspace users; invite by email (they set password via “Forgot password”); edit user (role, supervisor, Slack link).
2. **Slack sync** – If Slack is connected, run **Sync from Slack** to create/update users from the Slack workspace (new users are created deactivated; link Slack IDs so they can use “Log in with Slack” and `/task`).

### Webhooks

1. **Settings → Webhooks** – Add a webhook: name, URL, and events to subscribe to.
2. On create you receive a **secret** once; use it to verify the `X-TaskFlow-Signature` header (HMAC-SHA256 of body).
3. Events: `task.created`, `task.updated`, `task.completed`, `task.deleted`, `task.assigned`, `task.overdue`, `task.comment.added`, `project.created`, `project.updated`.
4. Each delivery is queued and retried; view **Deliveries** per webhook to see status and response.

### Templates

- Create and edit **templates**; set **Share with workspace** so all users can use them when creating tasks.

### Slack app setup (workspace admin)

1. Create a Slack app at api.slack.com; enable Bot User, OAuth (redirect to `APP_URL/auth/slack/callback`), Slash Command (`/task`), Event Subscriptions (if using events), Interactivity (if using “Create task” from messages).
2. Set `.env`: `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_SIGNING_SECRET`, `SLACK_REDIRECT_URI`. Optionally `SLACK_BOT_TOKEN` as default; workspaces can override with their own token after OAuth.
3. In TaskFlow, **connect Slack** (e.g. from profile or workspace settings) so the workspace has a bot token.
4. Users link their Slack identity via “Log in with Slack” or admin linking; then they can use `/task` and interactive create.

---

## 7. API reference

### Base URL and auth

- **Base URL**: `https://your-domain.com/api/v1` (or your app URL + `/api/v1`).
- **Authentication**: Bearer token (Sanctum). Obtain via `POST /api/v1/auth/login` with `email`, `password`, `device_name`; use the returned `token` in `Authorization: Bearer <token>`.
- **Rate limit**: 60 requests per minute per user (after login).

### Health (no auth)

- `GET /api/health` – Returns `{ "status": "ok"|"degraded", "db": "connected"|"disconnected", "redis": "connected"|"disconnected", "queue": "running"|"disconnected"|"unknown" }`.

### Auth

| Method | Path | Description |
|--------|------|-------------|
| POST | `/auth/login` | Login; body: `email`, `password`, `device_name`; returns `token`, `user`. |
| POST | `/auth/logout` | Invalidate current token. |
| GET | `/auth/me` | Current user with workspace. |

### Users (admin/owner for index/show/update)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/users` | List workspace users. |
| GET | `/users/{user}` | Show user. |
| PATCH | `/users/{user}` | Update user (role, supervisor, etc.). |
| PATCH | `/users/me/preferences` | Update own notification preferences. |

### Projects

| Method | Path | Description |
|--------|------|-------------|
| GET | `/projects` | List projects (optional `?archived=1`). |
| POST | `/projects` | Create; body: `name`, `description?`, `color?`, `visibility` (private\|shared). |
| GET | `/projects/{project}` | Show project (task lists, members). |
| PATCH | `/projects/{project}` | Update. |
| DELETE | `/projects/{project}` | Delete (not default project). |
| POST | `/projects/{project}/archive` | Archive. |
| POST | `/projects/{project}/restore` | Restore. |
| POST | `/projects/{project}/members` | Add member; body: `user_id`, `role` (admin\|member). |
| DELETE | `/projects/{project}/members/{user}` | Remove member. |
| GET | `/projects/{project}/lists` | Task lists. |
| POST | `/projects/{project}/lists` | Create list. |
| PATCH | `/projects/{project}/lists/reorder` | Reorder lists. |
| GET | `/projects/{project}/time-summary` | Time summary by task. |

### Task lists

| Method | Path | Description |
|--------|------|-------------|
| PATCH | `/lists/{list}` | Update list (name, etc.). |
| DELETE | `/lists/{list}` | Delete list. |

### Tasks

| Method | Path | Description |
|--------|------|-------------|
| GET | `/tasks` | List tasks (filter/sort by query params). |
| GET | `/tasks/my` | Tasks assigned to current user. |
| GET | `/tasks/calendar` | Tasks for calendar view (date range). |
| POST | `/tasks` | Create; body: `task_list_id`, `title`, `status?`, `priority?`, `description?`, `due_date?`, `due_time?`, `is_private?`. |
| GET | `/tasks/{task}` | Show task; optional `?include=assignees,comments,attachments,...`. |
| PATCH | `/tasks/{task}` | Update. |
| PATCH | `/tasks/{task}/status` | Set status. |
| DELETE | `/tasks/{task}` | Delete. |
| POST | `/tasks/{task}/archive` | Archive. |
| POST | `/tasks/{task}/duplicate` | Duplicate. |
| POST | `/tasks/{task}/assign` | Assign; body: `user_id`, `role` (responsible\|accountable\|consulted\|informed). |
| DELETE | `/tasks/{task}/assign/{user}` | Unassign. |
| GET/POST | `/tasks/{task}/dependencies` | List or add dependency. |
| DELETE | `/tasks/{task}/dependencies/{dependsOnTask}` | Remove dependency. |
| GET/POST | `/tasks/{task}/comments` | List or add comment. |
| GET/POST | `/tasks/{task}/attachments` | List or upload attachment. |
| GET | `/tasks/{task}/attachments/{attachment}/download` | Download attachment. |
| DELETE | `/comments/{comment}`, `/attachments/{attachment}` | Delete comment/attachment. |
| GET | `/tasks/{task}/activities` | Activity log. |
| GET/POST | `/tasks/{task}/time` | List time entries or start/stop. |
| GET/POST/DELETE | `/tasks/{task}/notifications/pause` | Get/pause/resume reminder pause. |
| POST | `/tasks/bulk` | Bulk update tasks. |
| PATCH | `/tasks/reorder` | Reorder tasks. |

### Time

| Method | Path | Description |
|--------|------|-------------|
| GET | `/time/running` | Current running time entry. |
| GET | `/time/summary/today` | Today’s time summary. |
| PATCH | `/time-entries/{timeEntry}/stop` | Stop entry. |
| DELETE | `/time-entries/{timeEntry}` | Delete entry. |

### Notifications

| Method | Path | Description |
|--------|------|-------------|
| GET | `/notifications` | Paginated list; optional `?read=0|1`, `?type=assignment|reminder|comment`. |
| GET | `/notifications/unread-count` | Unread count. |
| PATCH | `/notifications/{notification}` | Mark read. |
| POST | `/notifications/read-all` | Mark all read. |

### Search and filters

| Method | Path | Description |
|--------|------|-------------|
| GET | `/search` | Full-text search; query params for filters. |
| GET/POST/DELETE | `/saved-filters` | List, create, delete saved filter. |

### Templates

| Method | Path | Description |
|--------|------|-------------|
| GET | `/templates` | List templates. |
| POST | `/templates` | Create template. |
| GET | `/templates/{template}` | Show. |
| PATCH | `/templates/{template}` | Update. |
| DELETE | `/templates/{template}` | Delete. |
| POST | `/templates/{template}/apply` | Create task from template; body can include `task_list_id`, `project_id`, etc. |

### Reports

| Method | Path | Description |
|--------|------|-------------|
| GET | `/reports/{type}` | Report; `type`: `team`, `completion`, `overdue_trends`, `workload`, `projects`, `time`. Query: `from`, `to` (dates); `format=csv` for CSV. |

### Webhooks

| Method | Path | Description |
|--------|------|-------------|
| GET | `/webhooks` | List webhooks. |
| POST | `/webhooks` | Create; body: `name`, `url`, `events` (array). Returns `secret` once. |
| GET | `/webhooks/{webhook}` | Show. |
| PATCH | `/webhooks/{webhook}` | Update. |
| DELETE | `/webhooks/{webhook}` | Delete. |
| GET | `/webhooks/{webhook}/deliveries` | Delivery history. |

### Slack

| Method | Path | Description |
|--------|------|-------------|
| GET | `/slack/channels` | List Slack channels (for linking to project). |

### Devices (push)

| Method | Path | Description |
|--------|------|-------------|
| GET/POST/DELETE | `/devices` | List, register, remove device tokens for push. |

Responses: success usually `200` with `data`; create `201`; delete `204`. Errors: `401` Unauthenticated, `403` Forbidden, `404` Not found, `422` validation errors with `message` and `errors`.

---

## 8. Webhooks

### Subscribed events

You can subscribe to any subset of:

- `task.created`
- `task.updated`
- `task.completed`
- `task.deleted`
- `task.assigned`
- `task.overdue`
- `task.comment.added`
- `project.created`
- `project.updated`

### Payload and signature

- Each delivery is a **POST** to your webhook URL.
- **Headers**: `Content-Type: application/json`, `X-TaskFlow-Event: <event>`, `X-TaskFlow-Signature: sha256=<hmac>`.
- **Body**: JSON. For task events, common keys include task `id`, `title`, `status`, `priority`, `due_date`, `project_id`, assignees, etc. For project events, project fields.
- **Signature**: HMAC-SHA256 of the raw request body using your webhook **secret**. Verify with: `hash_hmac('sha256', $body, $secret)` and compare to the header value after `sha256=`.

### Retries and deliveries

- Failed deliveries are retried (configurable backoff). You can view delivery status and response per webhook in the app or via `GET /api/v1/webhooks/{webhook}/deliveries`.

---

## 9. Slack integration

### OAuth

- Users open “Log in with Slack” or workspace connects Slack; they authorize the app. TaskFlow stores the workspace’s bot token and can link Slack user IDs to TaskFlow users.

### Slash command: `/task`

- **Create**: `/task Buy milk @user due:tomorrow priority:high #ProjectName` – creates a task, optionally assigns, sets due date and project.
- **List**: `/task list` – tasks due today.
- **Overdue**: `/task overdue` – overdue tasks.
- **Done**: `/task done <task-id>` – mark task done.

### Interactive (Create task from message)

- If the app is configured with Interactivity, users can use a “Create task” action from a message; a modal opens to set title, description, list, assignee, due date, priority; submit creates the task in TaskFlow.

### Webhook endpoints (your server)

- **Events**: `POST /webhooks/slack/events` – URL verification and event handling (e.g. link unfurl, app_mention).
- **Commands**: `POST /webhooks/slack/commands` – slash command payloads; TaskFlow queues a job and responds via `response_url`.
- **Interactive**: `POST /webhooks/slack/interactive` – modal/submission payloads.

All Slack webhook routes are protected by `slack.signature` middleware (Slack signing secret).

---

## 10. Inbound email

- Configure your mail provider (e.g. Mailgun) to POST incoming messages to `POST /webhooks/inbound-email`.
- Recipient address can be workspace- or project-specific (e.g. `tasks-xxxx@your-domain.com`). TaskFlow parses the recipient to find the project/workspace and creates a task (subject/title, body/description, optional assignees from To/Cc).
- Size and rate limits apply; signature verification is required for Mailgun (see config and `MAILGUN_WEBHOOK_SIGNING_KEY`).

---

## 11. Deployment & operations

- **Server requirements**: PHP 8.2+, MySQL 8.0+, Redis 6+, Supervisor, Composer. See `deploy/README.md`.
- **Deploy script**: Run `./deploy.sh` (git pull, composer install --no-dev, migrate, config/route/view cache, queue:restart).
- **Crontab**: `* * * * * cd /path/to/taskflow && php artisan schedule:run >> /dev/null 2>&1`.
- **Queue workers**: Use `supervisord.conf.example` to run workers for queues `default`, `notifications`, `slack`, `email`.
- **Health**: `GET /api/health` for monitoring/load balancers.
- **Env**: Use `.env.production.example` as a checklist; never commit secrets.

For full deployment details, see **deploy/README.md**, **deploy/nginx.example.conf**, and **.env.production.example** in the repository root.