Skip to main content

Notes And Today Spec

Purpose​

Define the product shape for two new org-surface additions before implementation starts:

  • Notes: a shell-level note utility for internal agency note capture and retrieval
  • Today: a personal operator workspace for the logged-in agency user

This document exists to settle naming, route ownership, navigation placement, scope boundaries, and first-pass data shape before backend or UI work starts.

The goal is not to add another vague "productivity" area. The goal is to give agency operators a better place to hold personal context and daily follow-through without polluting overview, time, clients, or Drive.

Product Decisions​

1. Notes is a shell utility, not a sidebar workspace​

Notes should follow the same navigation pattern as Calendar:

  • no sidebar nav item
  • shell top-bar launcher
  • floating-dock create action
  • dedicated full route for deeper note work

Rationale:

  • notes are useful across many jobs, but they are not a primary collection workspace like clients, projects, or invoices
  • keeping Notes out of the sidebar prevents the main nav from turning into a mixed bag of durable workspaces and lightweight utilities
  • the user explicitly wants Notes to live in the top bar like Calendar

2. Today is a sidebar workspace, not a top-bar utility​

Today should live in the org sidebar Home group as a real route.

Implemented placement:

  • Home: Today, Overview, Analytics
  • Today is the default post-login and completed-flow destination for every active organization role
  • intentional deep links remain authoritative

Rationale:

  • Today is a full-page operating surface, not a lightweight launcher or popover
  • it represents a durable daily destination for the logged-in user
  • it should own a real route, loading state, and future personalization behavior
  • top-bar utilities should stay focused on cross-route tools like calendar, notes, active timer, and notifications
  • a shared role-neutral home avoids a second landing-rule system; existing capability, client-focus, personal/team-scope, and action guards adapt its contents to the viewer

3. Overview and Today have different jobs​

Overview remains the org-level operations snapshot.

Today becomes the logged-in user's role-neutral daily execution layer.

They must not collapse into one page.

Overview answers:

  • what is happening across the agency
  • which clients, projects, billing states, or collaboration items need attention

Today answers:

  • what genuinely needs my response
  • what is committed for my local calendar date
  • what active or pinned work can I continue

4. Notes is internal-first and separate from client-visible docs​

Initial Notes work must stay internal to the org surface.

That means:

  • notes are not Drive docs
  • notes are not portal-visible content
  • notes may link to a client account or project for context, but they remain internal records

This follows the existing product rule that client-visible docs must stay separate from internal notes.

Surface Ownership​

Notes​

Job​

Capture and retrieve internal notes quickly from anywhere in the org workspace.

Initial use cases​

  • personal scratch notes for the logged-in user
  • internal notes linked to a client account
  • internal notes linked to a project
  • personal starred notes used as working memory during the day

Decision rule: notes vs updates​

Notes are internal working memory.

That means:

  • a note linked to a project is still a note, not a project activity record
  • a note linked to a client is still an internal relationship record, not a shared collaboration doc
  • project updates remain the formal project-progress record when something should become part of the project's official story
  • if internal note content should become client-visible or timeline-worthy later, create a projectUpdate from that content instead of reclassifying the note itself

This keeps internal capture fast while preserving one clear source of truth for client-visible project progress.

Not in the first slice​

  • portal-visible notes
  • shared client collaboration notes
  • threaded note comments
  • long-form polished docs meant for client review
  • knowledge-base or wiki behavior
  • top-bar launcher button beside Calendar
  • launcher popover for starred and recent notes
  • full route at appRoutes.org.notes()
  • quick-action dock action for Add note
  • no sidebar entry

Route shape​

  • notes

UI shape​

The route should feel closer to a compact internal notebook than a document manager.

Recommended first-pass layout:

  • left rail or top filter for note scope: All, Personal, Clients, Projects, Pinned
  • dense note list with title or first line, linked context, updated time, and pin state
  • note editor panel or focused detail panel
  • fast create flow from the launcher and dock

Empty states​

  • no notes yet
  • no pinned notes
  • no notes for this client or project filter

Relationship to other surfaces​

  • from a client or project detail page, internal notes should eventually embed as a local section, but that is not required in the first slice
  • Drive remains the home for shared artifacts and client-facing docs

Today​

Job​

Give the logged-in agency user a calm execution surface for the current workday.

Initial use cases​

  • act on operational records owned by the viewer or an available shared queue
  • review overdue and due-today tasks
  • see reminders and agenda commitments for the viewer's local date
  • resume the active timer, pinned notes, and remaining open tasks
  • switch explicitly to team operational work or all accessible tasks
  • sidebar route in Home
  • no top-bar launcher in the first slice
  • not a dock action in the first slice

Route shape​

  • today

UI shape​

Today should be a dense operating page, not a motivational dashboard.

Implemented sections:

  • Needs you: actionable operational records assigned to the viewer or available in an unassigned shared queue
  • Today: overdue and due-today tasks, due reminders, and calendar commitments on the viewer's local date
  • Continue: active timer, pinned notes, and every remaining open task

Tasks are deterministically partitioned between Today and Continue. Today does not create a numeric cross-signal priority score or claim there is one universally correct next move. Full team, task, reminder, calendar, note, and operational queues remain available.

What it is not​

  • not a second org dashboard
  • not a project task system
  • not a team chat feed
  • not a CRM follow-up center

Relationship to Overview​

  • Overview is agency-operational
  • Today is viewer-oriented but supports explicit team scopes

If both pages start showing the same cards, the boundary is wrong.

Data Model Direction​

The first implementation should use backend-backed data, not local browser storage.

Calendar's current manual-event storage is local-only and is acceptable for a lightweight utility prototype, but it is not the right foundation for linked internal notes or a personal operating surface that should survive devices and sessions.

Notes first-pass entities​

Recommended core table:

  • notes

Recommended note fields:

  • organizationId
  • authorUserId
  • scope: personal | client | project
  • title
  • body
  • bodyPreview
  • clientAccountId?
  • projectId?
  • isPinned
  • pinnedAt?
  • archivedAt?
  • createdAt
  • updatedAt

Important rules:

  • personal notes must not require a client or project link
  • client notes must link to a clientAccount
  • project notes must link to a project and should also persist the resolved clientAccountId
  • scope describes the note's anchor, not a second content type
  • a project note is not a substitute for projectUpdates
  • initial visibility is internal-only to the author unless and until a deliberate shared-note model is added
  • title should be stored even for quick-capture notes, but it may be derived from the first meaningful line of body content when the user does not provide one explicitly
  • bodyPreview should be stored as a derived scan field so launcher and list surfaces do not have to read full note bodies just to render summaries

Starred notes and topbar pins​

Starred and Pinned are separate user-local concepts.

That means:

  • isPinned and pinnedAt are retained storage names for the note-level Starred state; starring organizes a user's note collection
  • a shell Pinned record belongs to the durable topbar working set and is stored through workspace preferences
  • changing either state must not change the other
  • the Starred and Recent launcher sections expose an accessible topbar pin/unpin action without requiring navigation to the Notes page
  • Today may reuse the Starred note set, while the topbar renders only the independent shell working set

Future evolution​

If the product later needs more structure, evolve notes by adding explicit flows instead of blurring boundaries:

  • a shared-note model should be separate from the author-private first-slice note shape
  • a future "promote to update" flow should create a projectUpdate from a note snapshot instead of turning the note row into a mixed-purpose record
  • any client-visible note or document model should stay separate from internal notes

Today task projection​

Today reads accessible open projectTasks and presents them as a cross-project projection. It does not own a separate checklist table or duplicate task state.

Do not start with:

  • assignees
  • teams
  • comments
  • due-date automation
  • recurring tasks
  • workflow states beyond open vs done

Note-create UX​

The first Notes create flow should be body-first, not title-first.

Implementation guidance:

  • quick create from the launcher or dock should open a lightweight note draft immediately
  • the user may type body content first
  • title becomes optional input, not a gate
  • save logic should derive a title when needed so list surfaces remain scannable
  • creation from the dedicated Notes route should insert a selected draft row and open it in the route's existing editor, following the same interaction model as Apple Notes instead of opening a modal
  • the route draft should inherit active client or project context, remain local while incomplete, become one durable record after meaningful content exists, and expose record-only actions only after that promotion
  • embedded client, project, timer, topbar, and quick-capture entry points should keep the compact composer

This keeps Notes fast enough to behave like working memory instead of a mini document-management form.

Note persistence contract​

All note editing surfaces use the same durable autosave behavior:

  • the Notes route, topbar quick editor, and shared compose dialog persist a valid note after a short editing pause
  • close, minimize, note switch, and unmount flush the latest valid draft
  • routine Save buttons are not part of the Notes interaction model
  • new valid drafts automatically become durable records without closing the editor; later edits update that same record
  • incomplete drafts may use scoped local recovery, but local recovery must not be presented as completed server persistence
  • title, plain text, canonical HTML, canonical editor JSON, scope, and linked client or project context all participate in dirty detection
  • server updates carry the last observed revision and reject stale writers; conflicts must be visible instead of silently overwriting newer content
  • backend updates skip no-op writes

Autosave feedback should remain quiet during normal operation. Show transient Saving and Saved status only where useful, and use the normal user-facing error path when durable persistence fails. Explicit follow-through actions such as linking a note to the active timer remain deliberate actions; they are not Save substitutes.

Execution Reference​

The route-by-route implementation map lives in:

Backend Ownership​

Recommended Convex modules:

  • packages/backend/convex/org/notes.ts
  • packages/backend/convex/org/today.ts

Recommended queries and mutations for the first slice:

Notes​

  • list recent notes for current user
  • list notes by scope
  • create note
  • update note
  • archive note
  • toggle pin

Today​

  • get today workspace payload for current user
  • list accessible open project tasks with client and project context

App Ownership​

Recommended app route and shell surfaces:

  • apps/app/src/app/[locale]/org/(dashboard)/notes/page.tsx
  • apps/app/src/app/[locale]/org/(dashboard)/today/page.tsx

Recommended shell additions:

  • notes launcher in org top bar beside calendar
  • notes create action in the quick-action dock
  • sidebar nav entry for Today

Recommended locale additions:

  • organization.notes.*
  • organization.today.*

Org top bar​

Desired shell utility set after this work:

  • Calendar
  • Notes
  • active timer
  • notifications

Org sidebar​

Recommended Home group after this work:

  • Today
  • Overview
  • Analytics

No other sidebar grouping changes are required for this feature.

Scope Boundaries​

In scope for the first build wave​

  • backend-backed internal notes
  • personal notes
  • client-linked notes
  • project-linked notes
  • top-bar Notes launcher
  • Notes full route
  • dock Add note action
  • sidebar Today route
  • Today composition using notes, project-task context, timer context, and calendar context

Explicitly out of scope for the first build wave​

  • client-visible or portal-visible notes
  • team-shared notes and granular visibility controls
  • project-wide task management
  • reminders, due dates, recurrence, or snooze logic
  • collaborative rich text editing
  • Slack-style internal communication threads
  • AI summary or suggestion features

Sequencing​

This is a post-baton expansion.

Do not start implementation until the current org and portal client-work baton is in a stable enough place to absorb a new operator layer without turning into a half-finished side track.

Recommended rollout order:

  1. Notes foundation
  2. Today surface
  3. shared-note and portal-safe visibility decisions
  4. client and project detail embeds

Open Questions To Keep Small​

These should be answered during implementation planning, not expanded into a second product-discovery track.

  1. Should notes allow untitled quick capture with body-first editing, or require a short title on create?
  2. Should Starred notes remain global for the user, or gain a separate Today-specific organization model later?

Acceptance Bar​

The feature direction is correct when these statements are true:

  • a user can open Notes from anywhere in the org shell without adding another sidebar workspace
  • a user can create and retrieve internal notes that survive devices and sessions
  • a user can keep personal follow-through in Today without mixing it into client records or time-entry notes
  • Overview still reads like the agency's operating dashboard rather than a personal task page
  • Drive docs and portal-visible artifacts remain separate from internal notes