Building the agreement lifecycle Remuner was missing

The problem

Sales compensation agreements lived outside the system that managed them

Larger organisations don't treat compensation sign-off as a formality. It involves approval chains, legal requirements, and documented audit trails. In practice, this process sat entirely outside Remuner. Admins generated PDFs, sent them via email, collected signatures through third-party tools or manual processes, and stored the results separately.

The workflow was fragmented. Plan design, tracking, and performance lived in Remuner, but the agreement itself — the moment where terms are formally accepted — happened elsewhere. Status was invisible, completion couldn't be verified, and signed documents lived outside the product.

That also created operational risk. Without a consistent, auditable acceptance record tied to the system that defines compensation, organisations had limited visibility into who had agreed to what and when. In environments with stricter compliance requirements, that gap was harder to ignore.

And it showed up in sales. Remuner could model and calculate compensation, but it couldn't produce or manage a legally valid agreement. That made it harder to compete in compliance-heavy segments, even against competitors who hadn't fully solved it.

The approach

Defining the system through a set of structural decisions

The goal was clear, but the design work was in the details: how should a system like this behave across different organisations, compliance requirements, and plan structures without becoming something only an admin could navigate?

Three decisions shaped most of the design.

1. Defining the document composition model

A compensation letter isn't a static document. It combines structured plan data, legally required content, and org-specific additions, and the system needed to handle all three without compromising the document's integrity.

I defined a composition model with three distinct block types:

• Fixed structural blocks required for legal validity
• Configurable blocks that admins can reorder and extend
• A generated block that uses AI to translate plan rules into human-readable prose automatically

Each block type has different constraints and editing options. Those distinctions needed to be visible in the editor so admins couldn't accidentally change content that affects the document's meaning or legal validity.

2. Splitting configuration across global and plan-level contexts

The feature introduced configuration at two different levels. Templates are managed company-wide, but their usage depends on individual compensation plans. I split configuration into a global surface for template management and feature activation, and a plan-level surface for assignment and plan-specific behaviour. The challenge was making changes in one context visible and clear in the other, without loading either surface beyond what its users actually need.

3. Making enforcement configurable instead of fixed

Once a letter is issued, organisations have an interest in making sure it gets signed. The simplest approach would have been to block product access until signature. But that adds friction for reps and creates awkward edge cases for legitimate delays. Instead, I made enforcement configurable: admins can choose between a persistent reminder that lets reps keep working, or a hard gate that requires signature before access. The compliance decision belongs to the organisation, not the product.

The solution

A system that manages the full agreement lifecycle across roles, states, and documents

The final system covers the entire agreement lifecycle: template definition, letter generation, delivery, signature, and record-keeping. The design makes that lifecycle coherent across roles while respecting the constraints legal and organisational use require.

A composable template system with constrained editing

Templates are built from three block types with different levels of control:

• Fixed structural blocks that ensure required legal content is always present
• Configurable blocks that allow organisations to add and organise their own content
• A generated block that uses AI to translate compensation plan rules into human-readable prose automatically

These blocks are visually and functionally distinct in the editor, with different available actions. Admins can't accidentally change content that needs to stay fixed, but have room to customise where it's appropriate.

A live preview lets admins simulate the final document for a specific rep and plan. The output varies based on plan configuration, so previewing before sending matters — errors here end up in legally significant documents.

Dual-surface configuration with a shared underlying state

Configuration is split across two surfaces: a global context for template management and feature activation, and a plan-level context for assigning templates and defining behaviour. Both operate on the same underlying data but are scoped to different roles. Admins can access and modify both. Managers and more restricted roles only interact with the plan-level configuration.

Changes in one context show up immediately in the other, keeping configuration consistent across both entry points without bypassing access restrictions.

A lifecycle model spanning delivery, signature, and storage

Once a letter is generated, it enters a lifecycle with clearly defined states: issued, pending signature, signed, or rejected.

Reps can access the letter through two entry points:

• In-app notifications for active users
• Email links for out-of-product access

Both lead to the same signature flow, so the experience is consistent regardless of how a rep arrives. The signing interface shows the document, lets reps download it, and captures acceptance. Signed documents are stored in the platform, tied to the relevant plan and user, giving admins one place to check agreement status and history.

Configurable enforcement and explicit rejection handling

Organisations can define how strictly signature is enforced: a non-blocking approach with persistent reminders, or a blocking approach that restricts access until the document is signed. This lets the system adapt to different compliance models without hardcoding a single behaviour.

Rejection is a first-class state, not an edge case. When a rep declines, admins are notified and can respond; the rep sees what happened and what comes next. A process with legal and organisational weight can't afford silent failure.

During early usage, admins went through the workflow and immediately asked for a way to share draft letters with internal stakeholders before sending them to reps. That wasn't in scope, so it became the focus of the next iteration.