Nexus PM — Documentation

Getting Started

Overview

Nexus PM is a modular, multi-tenant, API-first project-management platform. Every business object is scoped to a workspace (the tenant). The Filament admin panel and the Sanctum mobile API share the same domain layer.

Multi-tenant: one shared database, every row carries a workspace_id, auto-scoped.
Two delivery surfaces: Filament web panel at /admin and a versioned REST API at /api/v1.
Role-based access control with per-workspace roles (owner, admin, manager, member, viewer).
Realtime via Reverb, full-text search via Scout, background jobs + scheduler.

Getting Started

API Conventions

All API requests use a Sanctum bearer token and a standard response envelope.

Auth header: Authorization: Bearer {token}.
Active workspace: send X-Workspace: {id_or_slug} (falls back to the user's current workspace).
Envelope: { success, data, meta?, message? }; errors: { success:false, message, errors? }.
Status codes: 401 unauthenticated · 403 missing permission · 404 not found (also for out-of-workspace ids) · 422 validation · 429 rate limited.
Pagination via meta: { current_page, last_page, per_page, total }.
Rate limits: 120 req/min per user; 10 req/min per IP on auth endpoints.

Method	Endpoint	Description
GET	`/ping`	Public health probe

Phase 1 — Foundation

Authentication

Token-based auth for the mobile app plus the Filament session guard for the web panel.

Register bootstraps a user + their first workspace.
Login issues a Sanctum token.
/me returns roles + permissions in the active workspace.

Method	Endpoint	Description
POST	`/auth/register`	Create user + first workspace, return token
POST	`/auth/login`	Issue a token for valid credentials
POST	`/auth/logout`	Revoke the current token
GET	`/auth/me`	Profile + roles + permissions

Models

User

Phase 1 — Foundation

Workspaces & Tenancy

A workspace is the tenant. Isolation is enforced by a global WorkspaceScope that fails closed when there is no active workspace, plus auto-filled workspace_id on create.

CurrentWorkspace context singleton.
ResolveWorkspace middleware (API) + SyncFilamentTenant (panel).
Inserted before route-model binding so bound records stay tenant-safe.

Method	Endpoint	Description
GET	`/workspaces`	List the user's workspaces
POST	`/workspaces/switch`	Set the active workspace

Models

WorkspaceWorkspaceMember

Phase 1 — Foundation

RBAC — Roles & Permissions

spatie-permission with the teams feature keyed on workspace_id, so a user can be an admin in one workspace and a viewer in another. 56 permissions across a single catalog.

Roles: owner, admin, manager, member, viewer.
Permissions are global; role assignments are per-workspace.
WorkspaceProvisioner creates roles + memberships on workspace creation.

Permissions

project.*task.*milestone.*sprint.*member.*invoice.*timesheet.*document.*comment.*report.viewautomation.*

Phase 1 — Foundation

Members, Teams & Invitations

Per-workspace membership with an email invitation flow and lightweight Teams (groups of users).

Invite by email (token), accept (email-match), resend, revoke.
Existing users are notified in-app + email; new emails get an email invite.
Teams group users within a workspace.

Method	Endpoint	Description
GET	`/members`	List workspace members + pending invites
POST	`/members/invite`	Invite an email with a role
POST	`/members/{id}/resend`	Resend an invitation
POST	`/invitations/{token}/accept`	Accept an invitation (joins + assigns role)
DELETE	`/members/{id}`	Remove a member / revoke invite

Permissions

member.viewAnymember.invitemember.updatemember.remove

Models

WorkspaceMemberTeam

Phase 1 — Foundation

Audit Log

Every model change is recorded via spatie-activitylog, stamped with the workspace for tenant-safe querying. Viewable in the panel under Settings → Audit Log.

Auditable trait on key models.
workspace_id stamped via an Activity::creating hook.
Filterable by event (created/updated/deleted).

Phase 2 — Core PM

Projects

The container for tasks. Each project has a ticket prefix (e.g. MAL) and atomic, row-locked ticket numbering (MAL-1, MAL-2…).

Method	Endpoint	Description
GET	`/projects`	List (filters: status, q)
POST	`/projects`	Create
GET	`/projects/{slug}`	Show
PATCH	`/projects/{slug}`	Update
DELETE	`/projects/{slug}`	Delete
GET	`/projects/{slug}/budget`	Budget snapshot

Permissions

project.viewAnyproject.viewproject.createproject.updateproject.delete

Models

Project

Phase 2 — Core PM

Tasks & Subtasks

The central work item: status, priority, type, assignee, estimates, story points, dates, and self-referential subtasks. A quality gate blocks "done" until approved when required.

Statuses: backlog, todo, in_progress, in_review, done, cancelled.
Auto ticket numbering, completed_at automation.
Filters: project_id, status, priority, assignee_id, sprint_id, milestone_id, top_level, q.

Method	Endpoint	Description
GET	`/tasks`	List (rich filters)
POST	`/tasks`	Create
GET	`/tasks/{id}`	Show (incl. custom fields)
PATCH	`/tasks/{id}`	Update / move on board
DELETE	`/tasks/{id}`	Delete
GET	`/tasks/export`	CSV export
POST	`/tasks/import`	CSV import

Permissions

task.viewAnytask.viewtask.createtask.updatetask.deletetask.assigntask.approve

Models

Task

Phase 2 — Core PM

Milestones & Sprints

Group tasks toward a target date (milestones) or an agile cadence (sprints, with status planned/active/completed).

Method	Endpoint	Description
GET	`/milestones`	List (filter: project_id, status)
POST	`/milestones`	Create
PATCH	`/milestones/{id}`	Update (status → completed stamps completed_at)
DELETE	`/milestones/{id}`	Delete
GET	`/sprints`	List
POST	`/sprints`	Create
PATCH	`/sprints/{id}`	Update
DELETE	`/sprints/{id}`	Delete

Permissions

milestone.*sprint.*

Models

MilestoneSprint

Phase 2 — Core PM

Task Dependencies & Checklists

Predecessor/successor relationships (blocks, blocked_by, relates_to, duplicates, precedes) with cycle detection, plus per-task checklists.

Cycle detection (DFS over blocking edges) prevents loops.
Checklist items track who completed them.
Dependencies are drawn on the Gantt chart.

Method	Endpoint	Description
GET	`/tasks/{id}/dependencies`	List dependencies + dependents
POST	`/tasks/{id}/dependencies`	Add a dependency
DELETE	`/tasks/{id}/dependencies/{depId}`	Remove
POST	`/tasks/{id}/checklist`	Add checklist item
PATCH	`/checklist-items/{id}`	Toggle / edit
DELETE	`/checklist-items/{id}`	Remove

Models

TaskDependencyChecklistItem

Phase 2 — Core PM

Tags & Custom Fields

Labels for tasks, and typed dynamic fields (text, number, select, multiselect, date, checkbox, url, user) scoped to a project or the whole workspace.

Custom field values are validated by type and surfaced in GET /tasks/{id}.
Fields can be project-specific or workspace-wide.

Method	Endpoint	Description
GET	`/tags`	List
POST	`/tags`	Create
GET	`/custom-fields`	List (workspace + project fields)
POST	`/custom-fields`	Define a field
PUT	`/tasks/{id}/custom-fields`	Set values on a task

Models

TagCustomFieldCustomFieldValue

Phase 3 — Views

Board · List · Calendar · Gantt · Roadmap

Five ways to look at the same tasks, all in the Filament panel.

Kanban Board — drag-drop across status columns (SortableJS), permission-gated moves.
List/Table — the Tasks resource with grouping (status/priority/project/assignee/sprint/milestone), filters, bulk actions.
Calendar — tasks on their due date, month navigation, project filter.
Gantt — task bars by start→due with a today marker and dependency connectors (the priority-gap view).
Roadmap — milestone swimlanes across a month timeline with progress bars.

Phase 4 — Collaboration

Comments & Mentions

Polymorphic, threaded comments on tasks, projects and documents. Mention users and teams with @[Name](user:ID).

Threaded replies, soft deletes.
Mentions notify users (teams expand to members).
Authors edit their own; managers moderate others.

Method	Endpoint	Description
GET	`/tasks/{id}/comments`	List root comments + replies
POST	`/tasks/{id}/comments`	Post a comment / reply
PATCH	`/comments/{id}`	Edit
DELETE	`/comments/{id}`	Delete

Models

Comment

Phase 4 — Collaboration

Notifications

Database + broadcast + email channels. The panel shows a notification bell; the mobile app receives push.

Triggers: mention, assignment, new comment, timesheet/approval decisions, invitations, reminders.
A listener mirrors every database notification to push and (for key ones) email.

Phase 4 — Collaboration

Attachments

File uploads on tasks and comments via spatie-medialibrary (S3-ready).

Method	Endpoint	Description
GET	`/tasks/{id}/attachments`	List
POST	`/tasks/{id}/attachments`	Upload (multipart file, ≤20MB)
POST	`/comments/{id}/attachments`	Attach to a comment
DELETE	`/attachments/{id}`	Delete

Phase 4 — Collaboration

Activity Feed & Documents

A workspace activity stream and a nested documents/wiki (markdown).

Method	Endpoint	Description
GET	`/activity`	Global feed
GET	`/tasks/{id}/activity`	Per-task feed
GET	`/projects/{slug}/activity`	Per-project feed (incl. its tasks)
GET	`/documents`	List (?tree=1 for nested)
POST	`/documents`	Create
POST	`/documents/{id}/duplicate`	Duplicate (doc template)

Models

Document

Phase 4 — Collaboration

Realtime (Reverb)

Live comment events on workspace-namespaced private channels + a presence channel. Authorize at POST /broadcasting/auth.

Channels: workspace.{id}, workspace.{id}.task.{taskId}, presence.
Default BROADCAST_CONNECTION=log; set reverb + run the server to go live.

Phase 5 — Planning & Tracking

Time Tracking & Timesheetspriority gap

Timers and manual time logs that roll into weekly timesheets with a submit → approve/reject workflow.

One running timer per user; entries file into Monday-anchored weekly timesheets.
Approvers gated by timesheet.approve; decisions notify the owner.

Method	Endpoint	Description
POST	`/tasks/{id}/timer/start`	Start a timer
POST	`/timer/stop`	Stop the running timer
POST	`/tasks/{id}/time-entries`	Log time manually
GET	`/timesheets`	List
POST	`/timesheets/{id}/submit`	Submit
POST	`/timesheets/{id}/approve`	Approve
POST	`/timesheets/{id}/reject`	Reject

Models

TimeEntryTimesheet

Phase 5 — Planning & Tracking

Recurring Tasks & Reminders

Rule-based recurring task generation (daily/weekly/monthly) and per-task reminders, both dispatched by the scheduler.

pm:generate-recurring-tasks (daily) catches up missed runs.
pm:dispatch-reminders (every 15 min) sends due reminders.

Method	Endpoint	Description
POST	`/tasks/{id}/reminders`	Set a reminder
GET	`/reminders`	List (?upcoming=1)
DELETE	`/reminders/{id}`	Remove

Models

RecurringTaskRuleReminder

Phase 5 — Planning & Tracking

Approval Workflow / Quality Gates

Require sign-off before a task can be marked done. Request → approve/reject with notifications.

Method	Endpoint	Description
POST	`/tasks/{id}/approval/request`	Request approval
POST	`/approvals/{id}/approve`	Approve
POST	`/approvals/{id}/reject`	Reject

Models

Approval

Phase 5 — Planning & Tracking

Automations / Pipelines

Rule-based "when X, do Y" engine fired on task events, with a re-entrancy guard so a rule's own edits can't loop.

Triggers: created, status_changed, priority_changed, assigned.
Conditions (=, !=, in, not_in); actions: set status/priority, assign, add tag, add comment, notify.
Managed via the Automations Filament resource.

Models

AutomationRule

Phase 6 — Insight & Ops

Dashboards & Reports

Dashboard widgets (stats, tasks-by-status chart, my tasks, recent activity) and report endpoints.

Method	Endpoint	Description
GET	`/reports/overview`	Open/overdue/done counts + by-status
GET	`/reports/workload`	Open work per assignee
GET	`/reports/velocity`	Committed vs completed points/sprint
GET	`/sprints/{id}/burndown`	Sprint burndown series
GET	`/reports/standup`	Standup summary

Phase 6 — Insight & Ops

Global Search

Full-text search across tasks, projects and documents (Laravel Scout, database driver), tenant-scoped. A search bar is also available in the panel top bar.

Method	Endpoint	Description
GET	`/search`	Search (?q=) → { tasks, projects, documents }

Phase 6 — Insight & Ops

Billing / Invoicing & Budgetspriority gap

Client-facing invoices generated from billable time (no double-billing), with tax, status transitions and PDF export — plus per-project budget tracking.

Per-workspace numbering (INV-0001).
Generate from a project's unbilled billable time in a date range.
Project budget = logged hours × rate vs budget_amount.

Method	Endpoint	Description
GET	`/invoices`	List
POST	`/invoices`	Create (manual, with items)
POST	`/invoices/generate`	Generate from time
POST	`/invoices/{id}/transition`	sent / paid / void
GET	`/invoices/{id}/pdf`	Download PDF

Permissions

invoice.viewAnyinvoice.viewinvoice.createinvoice.updateinvoice.delete

Models

InvoiceInvoiceItem

Phase 6 — Insight & Ops

Integrations & Webhooks

Outbound, HMAC-signed webhooks fired on task events, and an inbound git webhook that links commits to tickets.

Outbound deliveries are queued + signed (X-Nexus-Signature).
Inbound: POST /integrations/git/{token} parses commit messages for refs like PROJ-123 and adds a linking comment.

Method	Endpoint	Description
GET	`/webhook-endpoints`	List endpoints
POST	`/webhook-endpoints`	Create (returns secret once)
POST	`/integrations/git/{token}`	Inbound git webhook (public, token-authed)

Models

WebhookEndpoint

Phase 6 — Insight & Ops

Templates & Import/Export

Task and project templates that instantiate into a project, plus CSV task import/export.

Method	Endpoint	Description
POST	`/task-templates/{id}/instantiate`	Create tasks from a template
POST	`/project-templates/{id}/instantiate`	Spin up a project from a blueprint
GET	`/tasks/export`	CSV export
POST	`/tasks/import`	CSV import

Models

TaskTemplateProjectTemplate

Phase 7 — Mobile

Mobile Enablement

API hardening, push notifications, offline delta-sync and focused mobile endpoints. The native Flutter/RN app is a separate client (see MOBILE_API.md).

Push: register device tokens (FCM); database notifications mirror to push.
Offline sync: delta pull with tombstones + a mutation-queue push (client_id → server id).
Quick views: My Tasks (today buckets) + Quick Capture.

Method	Endpoint	Description
POST	`/devices`	Register a push token
GET	`/sync`	Delta pull (?since=cursor) + tombstones
POST	`/sync`	Push offline mutations
GET	`/my-tasks`	Today / overdue / upcoming buckets
POST	`/quick-capture`	Fast task capture (auto Inbox)

Models

DeviceToken

Nexus PM documentation

Overview

API Conventions

Authentication

Workspaces & Tenancy

RBAC — Roles & Permissions

Members, Teams & Invitations

Audit Log

Projects

Tasks & Subtasks

Milestones & Sprints

Task Dependencies & Checklists

Tags & Custom Fields

Board · List · Calendar · Gantt · Roadmap

Comments & Mentions

Notifications

Attachments

Activity Feed & Documents

Realtime (Reverb)

Time Tracking & Timesheetspriority gap

Recurring Tasks & Reminders

Approval Workflow / Quality Gates

Automations / Pipelines

Dashboards & Reports

Global Search

Billing / Invoicing & Budgetspriority gap

Integrations & Webhooks

Templates & Import/Export

Mobile Enablement