Notes

Polycrate uses a unified Note model with a discriminating kind field for infos, todos, comments with time tracking, post-mortems, provider status, news, embedded object notes and meeting notes, including their relation to projects, DataSources, RBAC and API endpoints.

Notes

Polycrate uses a unified Note model for all kinds of textual contributions: hints, todos, comments, meeting minutes, post-mortems, provider status messages and more. The whole system is based on one table with a discriminating field kind that determines what the note represents and which additional fields are relevant.

Notes are thus the shared store for "everything you can pin to an object or project".

Note kinds at a glance

Kind Purpose Additional features
info Neutral info message —
warning Hint/warning —
todo Task with done status is_done, due_date
reminder Reminder with due date due_date, notification
comment Comment/work log — the only kind with time tracking time_tracked_hours, project
post-mortem Incident review Links to downtimes, maintenance events
provider-status Imported provider status message (typically via DataSource) source_url, provider FK
news RSS/feed import or manual news source_url
object-note "Pinboard note" attached to a ManagedObject EmbeddedNoteMixin
meeting Meeting minutes with Vydeo integration Vydeo meeting link, participant list

All notes have in common:

  • Title, body (Markdown)
  • Author: who created it
  • created_at / updated_at
  • organization / workspace: the context
  • labels: free tags for filtering and search
  • attachments: files (S3) can be attached

Extensions per kind

Comments & time tracking

Only notes with kind=comment carry the field time_tracked_hours. A "comment note" is thus also a time booking entry — e.g. "2h ticket processing for customer XYZ".

  • time_tracked_hours is a decimal field.
  • Optional FK project — this books the hours to a Project.
  • Report endpoints aggregate the sum per user/project/time range.

Todos

A note with kind=todo carries:

  • is_done: bool
  • due_date: date (optional)

In the UI, open todos appear in a dedicated todo list and are exported as a metric with the completion rate per workspace (see Prometheus Metrics).

Post-mortems

Formally, a post-mortem is just a note with kind=post-mortem. Convention:

  • Title carries the incident name.
  • Body follows the internal post-mortem template (timeline, root cause, follow-ups).
  • Labels link to incident IDs and affected systems.

Via object-note attachments or direct links, the causal Downtimes and Maintenances can be referenced.

Meeting notes + Vydeo

Notes with kind=meeting get a Vydeo integration:

  • When creating a meeting note, a Vydeo meeting room is (optionally) created.
  • The note stores the meeting link.
  • Participants are modeled via a many-to-many relation to user objects.
  • A sync task keeps participant lists and attendance data consistent between Polycrate and Vydeo.

A meeting note is thus invitation, minutes and archive at the same time — all in one place.

Embedded object notes

Every ManagedObject (K8s cluster, S3 bucket, LoadBalancer, host, …) can carry a pinned note (kind=object-note) via EmbeddedNoteMixin. It appears at the top of the detail view and serves as a running log:

  • "This cluster runs until Q2/27, then migration to aycloud."
  • "Last firmware upgrade on 2026-01-12; next one in 6 months at the latest."

The embedded note is unique per object and is displayed in the UI as a prominent info box.

Provider status & news

The two kinds provider-status and news are typically created automatically from a DataSource:

  • An RSS feed of a provider status page is placed on a DataSource with provider_entity — generated notes get kind=provider-status and a back-reference to the Provider.
  • General news feeds (without provider assignment) create notes with kind=news.

The datasource FK on the note allows tracing which feed an entry originated from.

Relation to projects and DataSources

                ┌─────────────┐
                │   Project   │
                └──────┬──────┘
                       │ FK: project
                       │
   ┌──────────────────▶│
   │                   │
┌──┴──┐   FK:       ┌──┴──┐  generic FK  ┌─────────────────┐
│Note │─────────────│Note │─────────────▶│  ManagedObject  │
│todo │             │comm │              │ (per Embedded/  │
└─────┘             │ ent │              │  object-note)   │
                    └──┬──┘              └─────────────────┘
                       ▲
                       │ FK: datasource
                       │
                ┌──────┴──────┐
                │ DataSource  │
                │ (rss/api)   │
                └─────────────┘
  • Notes can be attached to a project — this creates a natural pinboard per project where todos, comments and post-mortems are gathered.
  • Notes can be generated by a DataSource — then the note carries a datasource FK and we know it did not originate from a user.
  • Notes can be pinned to any ManagedObject — directly (via object-note) or indirectly via the generic ManagedObject reference.

RBAC

Notes follow the general RBAC system:

  • Anyone with read permissions on the organization/workspace sees all associated notes.
  • Anyone with write permissions can create, edit and delete notes.
  • The author of a note always has at least read/write permissions on their own note.
  • Notes of kind provider-status and news are read-only for non-superusers, because their source is a DataSource.

API endpoints (brief)

  • GET /api/v1/notes/ — filtered by workspace, kind, project, author, label etc.
  • POST /api/v1/notes/ — create a note (including kind-specific fields).
  • For meetings: a sub-endpoint creates or updates the Vydeo meeting room.
  • Time reports: aggregated endpoints summarize time_tracked_hours on comments.

Related topics