Projects

Projects in the Polycrate API: a dedicated ManagedObject for onboardings, offboardings and ongoing workstreams, with project kinds, notes, time tracking, reports, embedded notes and RBAC.

Projects

A Project is a standalone ManagedObject in Polycrate used to model time-bound or ongoing undertakings — such as customer projects, onboardings, offboardings or internal workstreams. Projects aggregate activity, carry their own embedded notes field and are the target for time tracking via Notes of kind comment.

Project Kinds

Every project carries a kind field that classifies its lifecycle:

Kind Meaning
onboarding Introduction of a customer or team. A defined end is expected.
offboarding Completion / handover. Typically short and focused.
ongoing Ongoing workstream without a defined end (e.g. "Managed Services customer XYZ")

The kind field primarily affects the presentation (badges, list sorting) and the default dashboards. Beyond that there are no hard semantic guarantees.

Typical Fields

Field Purpose
name / display_name Project name
kind see above
organization / workspace Context — a project always belongs to an organization
start_date / end_date Period (optional)
budget_hours Optional upper limit of hours for reports
embedded_note Pinned project note (kind=object-note), e.g. with kickoff notes
state Aggregated state (OK/WARNING/CRITICAL)

Notes on a Project

Notes attach to a project via the FK Note.project. Practically relevant:

  • Todos end up as the task list on the project.
  • Comments with time_tracked_hours form the project's time booking log.
  • Meeting notes document appointments around the project — including the Vydeo meeting link.
  • Post-mortems can be attached to the project timeline when an incident affected the project.

For details on how this works (kinds, fields, RBAC) see Notes.

Time Tracking & Reports

The time booking feature lives in notes, not directly in the project. A project does, however, aggregate automatically:

  • total_tracked_hours — sum of all comment notes with an FK to this project.
  • Time series — sums per day / week / month for tables and charts.
  • Budget consumption — if budget_hours is set, consumption is shown as a percentage and a warning is triggered when 80 % / 100 % are exceeded.

Aggregated reports are available via the API as dedicated endpoints (e.g. /api/v1/project/{id}/report/) and can be addressed as metric functions for dashboards.

Embedded Note

Every project can carry a pinned note of kind object-note (see Notes → Embedded Object Notes). It is shown prominently at the top of the detail view and serves as a living document:

  • Project context, stakeholders, target picture
  • Important dates
  • Open risks

The embedded note is unique per project.

Typical Lifecycle

┌──────────┐    ┌──────────────┐    ┌────────────┐    ┌────────────┐
│  Create  │───▶│ Active phase │───▶│ Completion │───▶│  Archived  │
│  (kind:  │    │   Notes,     │    │  (end_date │    │ (read-only │
│ onboard/ │    │  Comments,   │    │    set)    │    │ via RBAC)  │
│ ongoing) │    │  Timetrack.  │    │            │    │            │
└──────────┘    └──────────────┘    └────────────┘    └────────────┘

In every phase, notes can be attached, updated and closed.

RBAC & Visibility

Projects follow the generic RBAC system:

  • Organization admins see and edit all projects of their organization.
  • Workspace members only see projects on which they have explicit read permission.
  • Time reports are authorized separately — a user may be able to access the project but not the aggregated hours.

API Endpoints (brief)

  • GET /api/v1/project/ — list/filter
  • POST /api/v1/project/ — create
  • GET /api/v1/project/{id}/report/ — aggregated time report

The project API follows the usual DRF router schema (basename=project, see User Management & RBAC).

Related Topics