Skip to main content

Product Decision Log

Purpose: durable decisions that shape product behavior, information architecture, and UI.
Status: active working record.
Rule: record the decision, rationale, implications, and explicit non-goals before creating implementation tickets.

Related baseline: agency-product-baseline-audit-2026-07-11.md.

Decision 001: Projects Are Optional, Lightweight Delivery Containers​

Date: 2026-07-11 Status: decided Applies to: org projects, client project detail, portal project views, and all project-related navigation and UI.

Decision​

Projects are an optional, high-level delivery-status and client-communication layer.

An agency can use projects when they make a client relationship clearer, but must be able to run clients, billing, contracts, Drive, links, time, and portal access without creating or maintaining projects. A project is not the mandatory container for agency work.

Projects should support lightweight tracking through status, ownership, dates, a concise summary, client-visible updates, optional time context, files, notes, and explicit related records. They must not evolve by default into a task manager, sprint tool, or administrative system that requires continual upkeep before agency work can happen.

Rationale​

The product should help agencies serve clients and complete work quickly. It must not reward spending time configuring internal process machinery or force every agency into one delivery method.

Different agencies will use retainers, ad hoc work, recurring services, one-off deliverables, external project tools, or no formal project process at all. The app should provide useful project visibility when wanted, while keeping the client account as the persistent operating anchor.

Product Implications​

  • Every project belongs to one client account.
  • A client account, invoice, subscription/retainer, contract, Drive item, file request, link, or portal grant must never require a project in order to exist.
  • Project context remains optional for time entries, contracts, commercial records, and Drive items.
  • Client views must remain complete without projects. The client account is the relationship home, not a project portfolio shell.
  • A project should communicate delivery state, not represent every internal task or conversation.
  • Project updates are the main controlled mechanism for communicating delivery progress to clients.
  • The portal should show only clear, client-safe project information and published delivery updates.

UI Implications​

The project detail overview should be a sparse operational summary, not a dashboard of every related record.

For an active project, adding an update is the primary header action. It opens the authored-update flow; publication remains deliberate so unfinished writing is not exposed.

The first visible screen should prioritize:

  1. Project name and status.
  2. Client relationship context.
  3. Owner and meaningful target date, when present.
  4. Latest client-visible update or a clear indication that none has been published.
  5. One context-appropriate next action, normally publishing an update, changing status, or adding a relevant item.

The following belong behind focused tabs or secondary sections, not in the default visual hierarchy unless they create a real exception:

  • internal notes;
  • time history and detailed rollups;
  • files and folders;
  • contract context;
  • full update history;
  • lifecycle metadata; and
  • secondary metrics that do not affect the next decision.

Explicit Non-Goals​

  • mandatory projects for client work;
  • a general-purpose task manager, arbitrary-depth task trees, boards, sprint planning, or dependency graphs;
  • a project setup process that must be completed before billing, file sharing, time logging, or portal access;
  • client exposure to internal task activity or private notes; and
  • dense default project pages designed to prove feature breadth rather than support a decision.

Future Trigger For Reconsideration​

Only add first-class milestones or deliverables if Stage 2 evidence shows a repeated, material gap that cannot be addressed by project updates, files, target dates, contracts, or links. The evidence should show that agencies need a small shared client-review artifact, not an internal task system.

2026-08-01 Dogfooding Addendum​

Owner dogfooding showed that one-level subtasks are needed to break a concrete task into finishable steps and that hiding invite-link copy actions behind overflow menus creates avoidable first-client friction. Projects therefore support one optional subtask level while retaining the non-goals above. A subtask is a lightweight inline checklist row inside its parent, not an independent work record: it has inline add, rename, completion, and delete actions; can be staged while creating the parent; does not open a separate task sheet or working tab; and does not generate project timeline events. The organization owns every parent task; accepted portal work requests become normal organization tasks. A request for a file, answer, approval, or other input stays attached to the task it blocks and can be completed from the portal. Updates form the project timeline: they may be authored independently or linked to parent tasks, and completing or reopening a parent task creates a small automatic entry. Project navigation exposes Overview, Tasks, Updates, Files, Time, Notes, and Billing directly instead of hiding project areas behind an overflow menu. The client overview leads with current projects and a direct Add update action instead of treating delivery as a cross-workspace metric. Sending an invite copies the exact emailed link when clipboard access is available, every pending invite retains a visible copy action, and copying must not invalidate the link already emailed to the client.

Follow-On Decisions​

  • Define the project overview's exact content and hierarchy.
  • Define which project actions are sufficiently common to remain visible in the header.
  • Define the client portal's project-specific information and actions.

Decision 002: Project Updates Are Immediate Client Communication​

Date: 2026-07-11 Status: decided Applies to: project overview, project update authoring, portal project views, notification delivery, and client-email policy.

Decision​

A project update is a short client-facing summary of progress, completed work, or the next step in delivery. It is an intentional communication event, not an internal task comment or a report that staff must write on a fixed schedule.

For active projects, the default project overview provides an inline plain-text composer. Publishing should be one action from that composer. Longer, formatted, draft, or historical updates belong in the dedicated Updates workspace.

Delivery Rule​

Publishing an update must:

  1. Make it visible in the permitted client portal context.
  2. Send an email notification to the relevant client contacts with a link to the project/update context.

The current implementation satisfies portal visibility. It does not yet send project-update emails; that is a required implementation follow-on before this workflow can be considered complete.

UI Implications​

  • The inline composer should ask only for the update body. A title is optional and belongs in the advanced authoring flow.
  • The composer should remain visible on active project overviews, without a dialog or an initial click.
  • The publish action must be visually primary and clearly client-facing.
  • The overview should show the latest published update as evidence of the current client communication state.
  • Internal notes remain separate and must not appear in the composer or client portal.

Explicit Non-Goals​

  • required weekly or monthly update cadences;
  • using updates as a replacement for tasks or internal chat;
  • exposing drafts to the client; or
  • sending emails for internal-only edits or status changes.

Open Implementation Policy​

Define which client contacts receive the email by default, how agencies can opt out or change recipients, and whether publishing an edited update sends another notification.

Decision 003: Client Visibility Uses One App-Wide Exposure Model​

Date: 2026-07-14 Status: decided Applies to: org projects, Drive, contracts, portal projections, and all client-facing publication/share controls

Related reference: client-visibility-model.md.

Decision​

The app uses one product vocabulary for exposure:

  1. Client visible
  2. Internal

This is the canonical product model even when underlying feature storage still uses older values such as shared or internal_only.

Projects are treated as client-facing delivery containers by default. Internal agency work should live in notes, time entries, and internal artifacts instead of hidden/internal projects.

Drive items and contracts may still be either client visible or internal, but they must use the same user-facing language as the rest of the app.

Rationale​

The existing implementation mixed multiple visibility concepts:

  • projects: client_visible versus internal_only
  • Drive/contracts: shared versus internal
  • UI copy that alternated between shared, client workspace, and client visible

That makes the operator stop and reinterpret the page instead of understanding exposure rules immediately.

The product's job is not to teach different visibility systems per feature. The job is to let an agency answer one simple question: is this for the client relationship surface, or is it internal?

Product Implications​

  • New projects should default to client-visible operation.
  • Publishing a project update is a client-facing act and should not conflict with the default project model.
  • Notes remain internal.
  • Time entries remain internal source records.
  • Drive and contracts keep exposure control, but their labels and UI treatment must map to the same app-wide model.
  • Commercial records such as invoices, subscriptions, and quotes follow their own lifecycles and portal policies; they are not another copy of the document-visibility toggle system.

UI Implications​

  • Equivalent controls should use the same vocabulary everywhere.
  • Prefer Client visible over shared when communicating exposure state to the operator.
  • Prefer Internal over internal only unless the distinction is materially important.
  • Do not bury client-facing publication behind a conflicting visibility state that the operator did not intentionally choose.

Explicit Non-Goals​

  • adding more visibility states;
  • making internal notes or time logs client-facing;
  • turning projects into private task-management containers; or
  • introducing feature-specific exposure terminology when one shared term is sufficient.

Decision 004: Custom-Domain Organizations Own Their Client Email Identity​

Date: 2026-07-29 Status: decided Applies to: custom domains, client-facing portal email, notification delivery, and white-label policy.

Decision​

An organization with the custom-domain entitlement may choose one sender address on its attached custom domain. aegi provisions that domain with the platform email provider and uses the address only after the provider verifies the required email DNS records.

The organization sender applies to client-facing portal communication. Authentication for the main app, organization staff notices, platform operations, and other aegi-owned communication continue to use the platform sender.

Delivery Rules​

  • Sender selection is entitlement-aware at delivery time.
  • The sender domain must still match the organization's active custom domain.
  • Provider verification must still be verified.
  • A removed, downgraded, unverified, or mismatched sender falls back to the platform sender before delivery begins.
  • A provider rejection after selecting the custom sender does not trigger a second send from the platform identity.
  • The organization's business email is the preferred reply-to address when present.

Product Implications​

  • Portal routing DNS and email-authentication DNS are distinct setup stages.
  • The Custom Domain settings surface owns both stages because they share one entitlement and one organization identity.
  • Removing the custom domain also removes its provider-side sending-domain configuration.
  • Delivery history and audit logs must identify sender configuration changes without exposing provider credentials.

Decision 005: Calendar Recurrence Is A Series With Bounded Projections​

Date: 2026-08-06 Status: decided Applies to: manual org calendar events, Calendar views, Today agenda, and calendar quick views.

Decision​

A recurring manual event is stored as one series rule rather than as an unbounded set of copied events. The rule supports daily, weekly, monthly, and yearly frequencies, an interval, selected weekdays for weekly schedules, and never/date/count endings.

Calendar surfaces expand occurrences only for the date window they need. Occurrences retain a stable link to the owning series. Removing one occurrence records a dated exception rather than mutating or deleting the series, and editing one occurrence records a dated override while the rest of the series keeps its rule. Editing and deletion both make the choice between one occurrence and the whole series explicit.

Product Implications​

  • Existing non-recurring manual events remain valid without migration.
  • Repeated events preserve their local wall-clock time and multi-day duration across occurrences.
  • A count ending counts scheduled occurrences, including an occurrence later removed as an exception.
  • Monthly and yearly rules preserve the original calendar day and skip periods where that day does not exist.
  • Calendar, Today, and quick-view projections must supply bounded date ranges rather than materializing a never-ending series.

Explicit Non-Goals​

  • importing or synchronizing external calendar providers;
  • RFC 5545 interchange or arbitrary RRULE editing;
  • turning project target dates or reminders into editable calendar series; or
  • materializing every future occurrence as an independent stored record.