Chapter 2.11 Revenue System Design Lab

A professional automation engineer is not hired to build workflows. They are hired to solve a business problem: a company’s leads are not being followed up quickly enough, their pipeline is opaque, their brokers are spending time on administrative tasks that automation should handle, or their scoring process is inconsistent across different team members.

The workflow is the implementation artifact. The business problem is the brief.

The difference between an engineer who builds good workflows and one who delivers valuable client engagements is the ability to begin with the business problem, translate it into architectural requirements, design a solution that fits those requirements, implement and verify it, document it for the client’s team, and transfer ownership in a way that the client can sustain.

Chapter 2.11 is the final section of Part II and the culminating assessment of the CRM and revenue systems module. It does not introduce new architectural capabilities the architecture is complete. What it introduces is a new professional challenge: the requirement to apply a mastered architecture to a previously unseen client scenario, making adaptation decisions without explicit per-step guidance.

Students receive a client brief a detailed description of a commercial real estate private equity firm’s operational situation, pain points, team structure, and expectations and are asked to deliver a complete CRM automation solution based on the architecture developed throughout Sections 5.1 through 5.10.

The distinction from Chapter 2.10’s lab is the perspective. Chapter 2.10 was an internal engineering exercise; Chapter 2.11 is a client engagement simulation.

The capstone section is organized around five analytical subsections, each corresponding to a phase of a professional engagement: Client Problem (2.11.1), System Design Requirements (2.11.2), Scoring and Prioritization Requirements (2.11.3), Implementation Scope (2.11.4), and Evaluation Criteria (2.11.5). The capstone scenario is Altium Capital Partners, a commercial real estate private equity firm raising capital for its fourth institutional fund.

A professional automation engagement has five phases: discovery, design, implementation, handover, and support. Students who have completed Sections 5.1 through 5.10 have mastered Part III (implementation). Chapter 2.11 requires them to practice Part I (discovery), Part II (design), Phase 4 (handover), and Part II (support planning) as structured deliverables grounded in the Altium scenario.

The core discipline across all five phases is adaptation without unnecessary customization. Adapting the Part II architecture to Altium means changing the scoring signal groups, adjusting the lifecycle stage names, and calibrating follow-up cadence intervals while preserving the governance model, the PERMITTED_TRANSITIONS state machine, the property ownership boundaries, the idempotent batch upsert pattern, and the audit logging discipline.

Every one of those preserved elements represents a hard-learned design decision that, if discarded in the name of customization, will likely produce a production failure that the original architecture was designed to prevent.

The third organizing principle of Chapter 2.11 is that documentation is a deliverable, not a byproduct. When the project ends, the client’s team must be able to operate, monitor, and modify the system without the engineer who built it. A system with no documentation is a liability: every operational question requires the original engineer’s time, and every modification risks breaking something that neither the client’s team nor a new engineer fully understands.

The three documentation deliverables of Chapter 2.11 the Portfolio Package, the Client User Guide, and the Handover Documentation are distinct artifacts with distinct audiences. The Portfolio Package is for the engineer’s professional portfolio. The User Guide is for the client’s non-technical operators. The Handover Documentation is for the technical contact or next engineer who will maintain and extend the system.

The professional standard for an automation engineer is not “I built it and it works.” It is “I built it, I tested it against defined acceptance criteria, I documented it for the people who will use it and maintain it, and I transferred ownership with the rigor required for the client to operate it confidently without me.”

Learning Objectives

After completing this capstone, you will be able to:

Translate the Altium Capital Partners client brief into a complete architectural specification, identifying how the Part II nine-layer architecture must be adapted for a private equity investor relations context.
Design and build the full four-workflow CRM automation platform adapted to Altium’s investor profile, intake channels, and deal progression stages.
Make and document at least three architectural adaptation decisions that differ from the brokerage reference implementation, with written rationale for each.
Deliver a client-facing system documentation package that describes the platform’s behavior, property schema, and operational procedures in language the client’s team can use without engineering support.
Evaluate your own implementation against the capstone rubric, identifying specific workflow nodes and configuration choices that satisfy each assessment criterion.

2.11.1 Client Problem

Business Scenario

Altium Capital Partners is a commercial real estate private equity firm raising capital for Fund IV. The IR team manages investor inquiries from a shared Gmail inbox and a Google Sheet updated 3–5 days behind actual activity. The firm has no CRM, no standardized scoring, and no escalation mechanism. Leads wait 24–48 hours for acknowledgment. Thirty percent of MQL-stage prospects have no contact record within two weeks of inquiry.

The Problem

An IR team without a governed follow-up system does not know which prospects are overdue, which have gone cold from inattention rather than disqualification, and which active conversations are competing with automated reminders. The managing director cannot report pipeline status with confidence because the source of truth is always stale.

The Architectural Solution

The four-workflow CRM automation architecture adapts directly to the investor relations context: Workflow A captures and scores investor inquiries, Workflow B manages the investor lifecycle through a six-stage PERMITTED_TRANSITIONS map, Workflow C governs a priority-tiered follow-up cadence calibrated to IR team capacity, and Workflow D processes pre-meeting questionnaire responses. Three elements require client-specific calibration (lifecycle stages, scoring signals, Slack channels); all other architectural decisions are preserved from the Part II baseline.

Client Problem Analysis

Client problem analysis is the discipline of transforming a client’s operational narrative into a precise set of automation requirements. A client rarely describes their problem in engineering terms. They describe symptoms: “we’re losing leads,” “our brokers can’t keep up,” “we have no visibility into the pipeline.”

The automation engineer’s first job is to translate these symptom descriptions into root causes, and then translate root causes into specific requirements that an automation system can address.

The process that makes this translation disciplined rather than intuitive is the three-part requirements document: current state (how the client’s process works today, including its manual steps, tools, and failure points), desired state (what outcomes the client wants the automation system to produce), and requirements gap (the specific capabilities the automation system must provide to close the distance between current and desired state).

The requirements document produced by client problem analysis is the most consequential artifact of the entire engagement. It is the agreement between the engineer and the client about what the system is supposed to do.

A vague requirements document “improve lead management” produces an engagement that ends with a dispute about scope, because the client’s expectations and the engineer’s implementation diverge in ways neither party anticipated. A precise requirements document “when a lead submits the contact form, create a HubSpot Contact with normalized field values, compute a combined score using the hybrid scoring model, assign a priority label, and create a broker Task due within 2 business hours for Hot leads” gives both parties a common and verifiable definition of success.

Specificity in the requirements document is the engineer’s primary protection against scope disputes, and the client’s primary protection against receiving something other than what they needed.

Altium Capital Partners Client Problem Analysis

Current State: Altium Capital Partners is a commercial real estate private equity firm managing three closed funds totaling $480M in assets under management. The firm is in the capital-raising phase for Fund IV, targeting $200M in new commitments over 18 months. The investor relations (IR) team consists of two senior IR associates and one IR director. The current lead management process is entirely manual.

Inbound investor inquiries arrive through three channels: the firm’s website contact form, email introductions from placement agents, and direct referrals from existing investors. All three channels deliver leads to a shared Gmail inbox. The IR director forwards new leads to IR associates based on geography and investment size, typically within 24 to 48 hours of receipt. Associates respond to leads via personal email. There is no CRM investor contact history lives in individual Gmail inboxes and a shared Google Sheet updated manually by associates.

The Google Sheet tracks: investor name, email, date of first contact, estimated investment size, last contact date, and current status (Prospect / In Conversation / LOI Signed / Committed / Declined). Updates are made inconsistently; the sheet is typically 3–5 days behind. The IR director has no real-time visibility into which prospects have been contacted, which are overdue for follow-up, and which are approaching commitment. Three problems dominate: response time (leads wait 24–48 hours for initial acknowledgment; Altium’s institutional investor prospects expect a same-business-day response); follow-up gaps (30% of MQL-stage prospects have no contact record within two weeks of initial inquiry); pipeline opacity (the IR director cannot report on the capital-raising pipeline with confidence because the Google Sheet is stale).

Desired State: Altium wants a CRM automation system that: captures all inbound investor inquiries from the website form, scores them within 5 seconds of submission, assigns a priority tier, and notifies the appropriate IR associate within the same business day; manages a governed follow-up cadence for each investor prospect based on their priority tier, with escalation notifications to the IR director when overdue; enriches investor records with qualification survey data when prospects complete a pre-meeting questionnaire; maintains a real-time investor pipeline in HubSpot visible to the entire IR team and fund management; and logs every automated action to the investor Contact record for IR associate review before any call.

Requirements Gap: The automation system must provide: webhook-triggered lead intake with field normalization and deduplication; hybrid scoring using investor qualification signals (investment size, investor type, prior fund experience, deployment timeline, referral source); lifecycle state management with a custom PERMITTED_TRANSITIONS map adapted for the investor lifecycle (Lead → MQL → SQL → Meeting Scheduled → Committed → Investor); governed follow-up cadence with Hot/Warm/Cool/Cold tiers calibrated to investor relations protocols; Typeform survey integration for the pre-meeting qualification questionnaire; HubSpot Deal tracking for Committed and Investor stage prospects; and complete audit logging to HubSpot Contact Notes.

Client problem analysis for a CRM automation engagement has a specific sequencing discipline: the engineer must understand the client’s current process before proposing a future architecture. An engineer who skips current-state analysis and immediately begins describing workflows is proposing a solution to a problem they have not yet confirmed.

Current-state analysis reveals whether pain points are actually addressable by automation, whether there are process dependencies that automation cannot remove, and whether the client’s team has the operational discipline to adopt a new system.

For Altium, current-state analysis reveals three important architectural constraints: investor introductions from placement agents arrive via email and will remain out of scope for the automated intake pipeline (manual entry only); the Google Sheet will continue to exist during the transition period; and the IR director must be able to view real-time pipeline status from HubSpot without automation engineering skills, meaning the audit Note format must be legible to non-technical operators.

Production Risk

Conflating the client’s stated request with their actual requirement leads to scoping a solution before the problem is understood. Altium’s IR director saying “we need better lead tracking” could mean a spreadsheet improvement, a standalone CRM, or a four-workflow automation platform. The automation engineer who immediately scopes an n8n implementation in response to “we need better lead tracking” has made a solution assumption before understanding the problem. The three-part requirements document current state, desired state, requirements gap forces the engineer to validate that the proposed solution is actually the right fit for the client’s operational context before any implementation work begins.

Production Risk

Not documenting scope exclusions in the requirements document creates scope creep conditions at the end of the engagement. The requirements document should explicitly state what the automation system will not do: it will not process email introductions from placement agents, it will not integrate with the legacy Google Sheet, and it will not generate AI-personalized outreach email content. Explicit scope exclusions prevent in-flight additions from being treated as always-intended deliverables and give the engineer a formal basis to manage change requests as change orders.

Production Risk

Skipping current-state analysis and proceeding directly to architecture design produces a solution that assumes things about the client’s process that may not be true. The three architectural constraints identified in Altium’s current-state analysis placement agent email as a manual channel, Google Sheet as a parallel system during transition, and non-technical operator requirements for audit Notes are not obvious from the desired state alone. Each of these constraints changes the implementation scope. Missing them during analysis means discovering them during implementation, when they are significantly more expensive to accommodate.

2.11.2 System Design Requirements

System Design Requirements

System design requirements translate the business requirements from Chapter 2.11.1 into specific architectural specifications: which workflows must be built, which HubSpot properties must be created, which external systems must be integrated, and which governance rules must be enforced. System design requirements are more specific than business requirements but less specific than implementation instructions they describe what the system must do, not how it must be configured in n8n node by node.

A system design requirements document for a CRM automation engagement has five sections: workflow inventory (which workflows are required and their triggers), HubSpot data model (which Contact properties, Deal stages, and lifecycle stages are required), integration inventory (which external APIs are called and why), governance rules (the communication governance model, the state machine, and the manual override protocol), and non-functional requirements (performance, reliability, error handling, and logging standards).

System design requirements are the engineering contract that parallels the business requirements document as the business contract. Business requirements define what outcomes the client wants; system design requirements define what the automation system must be. An engagement that skips system design requirements and jumps directly to implementation typically produces a system that works for the happy path but fails on edge cases that were entirely predictable from the business requirements.

For Altium Capital Partners, the key design requirement that is easy to miss in the business requirements is the investor lifecycle state machine. The IR process has six stages Lead, MQL, SQL, Meeting Scheduled, Committed, Investor and specific rules govern which transitions are valid. A prospect should not advance from Lead directly to Committed; the intermediate stages represent real-world qualification events that must occur before commitment.

The PERMITTED_TRANSITIONS map must be designed before the Workflow B implementation begins; retrofitting it after implementation is structurally disruptive.

Altium Capital Partners System Design Requirements

Workflow Inventory:

Workflow A (Investor Intake and Enrichment): Triggered by website contact form webhook. Implements all eleven CRM architecture layers for the investor context. Scoring signal groups adapted for investor qualification (see Chapter 2.11.3). Lifecycle qualification uses adapted SQL entry criteria (Investment Size >= $500K AND phone present AND deployment timeline is Active or Near-term). Governance initialization sets communication_governance_status = "active" and journey_state = "prospect". Follow-up cadence tiers: Hot (+2hr, +6hr, +24hr), Warm (+24hr, +72hr, +7 day), Cool (+5 business days, +10 business days, +20 business days), Cold (+45 calendar day escalation only).

Workflow B (Investor Lifecycle and Deal Management): Triggered by HubSpot Contact property-change webhook for lifecyclestage. PERMITTED_TRANSITIONS adapted for investor lifecycle. Deal creation on SQL transition using “Investor Relationship” pipeline. manual_override_active = true on Meeting Scheduled entry (IR associate is actively engaged). manual_override_active = false on Investor entry (relationship complete).

Workflow C (Follow-up and Governance Monitor): Schedule trigger 0,30 8-18 * * * (Altium’s IR business hours end at 6pm EST). Investor-calibrated cadence intervals. Slack channel names: #ir-team (TP1, TP2), #ir-escalations (Escalation), #crm-ops (governance alerts). Stale deal detection for Committed-stage prospects inactive for 14+ days.

Workflow D (Typeform Survey Handler): Processes responses from Altium’s pre-meeting qualification questionnaire. Maps 8 survey fields to survey_* HubSpot namespace. Investment size upgrade detection triggers requires_rescore_review flag. Idempotency via last_typeform_response_id.

HubSpot Data Model:

Custom Contact property groups: Investor Identity (standard intake fields), Investor Scoring (combined_score, priority_label, ai_confidence, scoring_model_version), Investor Follow-up Timing (followup_tp*_due_at, followup_schedule_tier), Investor Follow-up State (followup_tp*_sent_at, escalation_triggered), Investor Governance (communication_governance_status, manual_override_active, journey_state, communication_cooldown_until), Investor Survey (survey_investment_size_confirmed, survey_investor_type, survey_prior_fund_experience, survey_deployment_timeline, survey_net_worth_tier, survey_decision_maker_confirmed, survey_completed_at, last_typeform_response_id), Audit (requires_manual_review, requires_rescore_review, last_automation_error).

Custom lifecycle stages added to HubSpot’s default lifecycle model: meetingscheduled (inserted between SQL and Opportunity in the standard pipeline), committed (inserted between Opportunity and Customer), with Investor mapped to HubSpot’s customer stage for pipeline compatibility.

Integration Inventory:

HubSpot CRM API (batch upsert, search, notes, tasks, deals, associations, lifecycle webhooks), OpenAI Chat Completions API (gpt-4o-mini, AI scoring), Typeform Webhooks API (pre-meeting questionnaire), Slack API (IR team and ops notifications), Webflow form via webhook to n8n intake endpoint.

Governance Rules:

PERMITTED_TRANSITIONS for investor lifecycle: - lead → [marketingqualifiedlead, salesqualifiedlead] - marketingqualifiedlead → [salesqualifiedlead] - salesqualifiedlead → [meetingscheduled] - meetingscheduled → [opportunity] (Committed stage) - opportunity → [customer] (Investor stage) - customer → [] (terminal) - other → [lead, marketingqualifiedlead, salesqualifiedlead]

Manual override: manual_override_active = true set by Workflow B on Meeting Scheduled entry. IR associates may also manually set manual_override_active = true in HubSpot to pause automated follow-up for any Contact. All manual overrides are logged.

Non-Functional Requirements: Webhook response time: ≤ 200ms. End-to-end processing time: ≤ 5 seconds for Workflow A. Workflow C polling: every 30 minutes during IR business hours (8am–6pm EST). All errors log to HubSpot Contact Note and #crm-ops. Every automated action recorded in HubSpot Contact Note within 60 seconds.

Key Principle

Treat every preserved architectural element as the default and justify any deviation explicitly against the new client’s requirements. The governance gate, property ownership model, and idempotency checks are not implementation choices to reconsider with each new client they are hard-learned design decisions that prevent specific, documented production failures.

The system design requirements for Altium differ from the Part II commercial real estate brokerage architecture in three specific areas: the investor lifecycle stages (six stages vs. five, with custom stage names), the scoring signal groups (investor qualification signals vs. commercial real estate property signals), and the follow-up channels (IR team channels vs. broker channels). All other architectural elements the governance gate, the property ownership model, the idempotency checks, the audit logging are preserved without change.

This is adaptation in practice: three targeted changes, everything else intact.

A common failure of the adaptation discipline is to treat every difference between the new client context and the reference architecture as an opportunity to redesign. The discipline is the opposite: treat every preserved element as a default and justify any deviation explicitly against the new client’s requirements.

Production Risk

Specifying requirements at the wrong level of abstraction either “the system should handle lifecycle management” (too vague) or “the Switch node should have four branches in this order” (too specific) leaves the requirements document unable to serve its purpose. A requirement that is too vague cannot be used to determine whether an implementation is correct. A requirement that specifies implementation node configuration is a workflow instruction, not a design requirement. The right level: “Workflow B must validate lifecycle transitions against a PERMITTED_TRANSITIONS map before executing any side effects.” This specifies the mechanism and constraint without specifying the implementation.

Production Risk

Not designing the PERMITTED_TRANSITIONS map before beginning Workflow B’s implementation creates a situation where the state machine is defined after the transition logic has already been partially configured. The lifecycle stage names, the permitted transition paths, and the side effects on each valid transition (Deal creation on SQL entry, manual_override_active on Meeting Scheduled entry) are all interdependent. Designing the state machine at implementation time produces a Workflow B that reflects what was easy to build, not what the governance model requires. The PERMITTED_TRANSITIONS map must be finalized and client-approved during the design phase.

Critical Requirement

Adapting architectural elements that should be preserved for example, changing the governance gate’s three-condition structure or the property ownership model’s single-owner rule in an attempt to simplify the implementation discards the design decisions that prevent the production failures documented in the Part II case studies. The three adaptation areas (lifecycle stages, scoring signals, Slack channels) are the entire scope of justified deviation from the Part II architecture for the Altium engagement. Any additional adaptation requires explicit rationale grounded in Altium’s specific requirements.

Diagram 2.11.2 End-to-End Client Solution Topology

Figure 28.1: End-to-End Client Solution Topology. Diagram 2.11.2 End-to-End Client Solution Topology

2.11.3 Scoring and Prioritization Requirements

Scoring Model Calibration

Scoring and prioritization requirements define how the hybrid scoring model should be calibrated for the client’s specific lead population. The scoring model’s signal groups, their point values, the AI confidence thresholds, the score combination formula, and the priority tier thresholds all require client-specific calibration. A scoring model that uses commercial real estate property signals is not a useful investor qualification model.

Scoring calibration has three inputs: the client’s understanding of what distinguishes a high-priority lead from a low-priority one (qualitative), the distribution of actual lead signals in the client’s historical data (quantitative where available, estimated otherwise), and the operational capacity of the client’s team to act on prioritized leads (operational).

A firm whose IR team can handle 10 follow-ups per week should not have scoring thresholds that classify 40% of leads as Hot the queue would immediately exceed capacity, and the priority system would be meaningless in practice.

Scoring model calibration is where the automation engineer’s understanding of the client’s business determines the system’s operational value. A technically perfect scoring implementation that is miscalibrated to the client’s actual lead quality distribution will produce a priority tier breakdown that overwhelms the IR team with Hot leads they cannot follow up or underwhelms them with a pipeline of Cold leads they cannot convert.

For Altium Capital Partners, the IR team’s capacity constraint is the binding calibration input: two IR associates can each manage approximately 5 active investor relationships per week at the required level of attention. A system that classifies 30 of 50 weekly leads as Hot will produce more Hot-tier follow-up tasks than the IR team can execute, defeating the purpose of the priority system.

Altium Capital Partners Scoring Model Calibration

Investor Qualification Signal Groups:

Signal Group 1 Referral Source (0–5 points): Direct fund introduction (existing LP referral): 5; Placement agent introduction: 4; Industry conference or event: 3; Website (organic search): 2; LinkedIn / social outreach: 1; Unknown: 0.

Signal Group 2 Investment Size Indication (0–5 points): $5M or more: 5; $2.5M–$4.9M: 4; $1M–$2.4M: 3; $500K–$999K: 2; $250K–$499K: 1; Under $250K or not specified: 0.

Signal Group 3 Investor Type (0–4 points): Family office: 4; RIA / institutional: 4; High net worth individual (confirmed accredited): 3; Self-directed IRA / individual: 2; Unknown / unconfirmed: 0.

Signal Group 4 Deployment Timeline (0–4 points): Actively deploying capital now: 4; Deploying within 6 months: 3; Evaluating for end of year: 1; Exploring for future funds: 0.

Signal Group 5 Contact Completeness (0–2 points): Phone number present: +1; Company / firm name present: +1. Simplified to 2 points maximum because accredited status is confirmed by survey, not intake form.

Maximum rule_score: 20/20.

AI Scoring Adaptation:

The AI scoring model evaluates inquiry_description for investor-specific intent signals: capital availability language (“currently deploying,” “reviewing opportunities”), accreditation or qualification language (“accredited,” “family office,” “certified”), urgency language (“Q1 close,” “before year-end”), and relationship signals (“referred by,” “invested with you before”). The OpenAI prompt should be adapted with investor-domain context while keeping the intent_level (0–8) and confidence (0.0–1.0) schema identical to the Part II implementation.

Score Combination and Priority Thresholds:

The additive formula is identical to the Part II calibration: combined_score = rule_score + min(4, ai_score × confidence_multiplier). Priority thresholds calibrated to IR team capacity: Hot (combined_score ≥ 18, targeting approximately 5–10% of leads), Warm (combined_score 12–17, targeting approximately 20–30% of leads), Cool (combined_score 6–11, targeting approximately 40–50% of leads), Cold (combined_score < 6, representing exploratory or unqualified inquiries). The Hot threshold has been raised to 18 from Part II’s 20 to accommodate the different distribution of the 5+5+4+4+2 signal group structure. Students should verify against their expected lead distribution before finalizing thresholds.

Follow-up Cadence by Priority Tier:

Hot: TP1 at +2 business hours, TP2 at +6 business hours, escalation at +24 business hours. Warm: TP1 at +24 business hours, TP2 at +72 business hours, escalation at +7 calendar days. Cool: TP1 at +5 business days, TP2 at +10 business days, escalation at +20 business days (adjusted to business-day-based for IR context). Cold: Escalation only at +45 calendar days (extended from 30 to match Altium’s longer investor consideration cycles).

The investor scoring model’s Signal Group 2 (Investment Size, 0–5 points) differs from the Part II architecture’s property size signal in one important way: investment size is a self-reported value on the intake form, not an objective characteristic of the lead’s requirements. A lead who reports “$5M” may be aspirational; a lead who reports “$500K” may underreport to avoid appearing too small for the fund.

This self-reporting bias means the scoring model should treat investment size as one signal among several. The AI scoring layer’s evaluation of the inquiry description’s language quality and specificity serves as an important counterweight to inflated self-reported investment sizes.

Production Risk

Calibrating tier thresholds without accounting for carryover load from prior execution cycles will produce an IR team overload situation under steady-state conditions. Cadence interval calibration must account for the accumulation of TP2 tasks from the prior week competing with TP1 tasks from the current week. If the expected weekly lead volume is 40 leads and 25% are classified as Hot, the IR team faces 10 Hot TP1 tasks per week at capacity. But TP2 tasks from the previous week’s Hot leads run concurrently. All threshold and cadence interval decisions must be modeled against the team’s total weekly task capacity, not per-tier weekly new lead volume alone.

Production Risk

Not documenting the scoring model’s calibration rationale means that a year after deployment, when the IR director asks why a specific lead combination produces a Cool priority, the answer requires reverse-engineering the scoring code. The implementation notes must document every signal weight value and its rationale, every threshold value and the capacity calculation that produced it, and every deviation from the Part II baseline with the client-specific reason for the deviation. When the scoring model is recalibrated, the implementation notes must be updated with the new values and the recalibration rationale.

Production Risk

Treating self-reported intake form values investment size, investor type, deployment timeline as definitive qualification signals without cross-referencing them against AI inquiry evaluation and survey enrichment data will produce a priority distribution that reflects stated preferences rather than observed qualification signals. Hot-tier leads who stated “$5M, actively deploying” but whose inquiry descriptions are vague and generic should receive AI confidence penalties that reduce their combined score below the Hot threshold. The AI scoring layer exists precisely to evaluate the quality of the lead’s engagement, which self-reported fields cannot capture.

2.11.4 Implementation Scope

Implementation Scope

Implementation scope is the formal definition of what the engagement will build, configure, and deliver, expressed with enough precision that both the client and engineer can verify completion at handover. Implementation scope is not a list of features it is a list of deliverables, each with acceptance criteria.

“Lead scoring” is not a deliverable. “A HubSpot Contact scoring implementation that computes combined_score using the five investor qualification signals and assigns priority_label within 5 seconds of form submission” is a deliverable.

Implementation scope also defines scope exclusions what the engagement will not deliver with explicit rationale. Scope exclusions prevent the client from expecting capabilities that were never part of the engagement agreement and protect the engineer from scope creep driven by in-flight additions.

Implementation scope is the delivery contract. At project completion, the client reviews the scope document and verifies that each deliverable has been completed to the specified standard.

Without a precise scope document, every in-flight client request is either scope creep (“yes, that was always the plan”) or client frustration from an ambiguous expectation (“no, that’s out of scope”). The scope document is reviewed and approved by the client before implementation begins; changes after approval are managed as change orders with revised timelines and costs.

Altium Capital Partners Implementation Scope

In Scope Workflow Deliverables:

Workflow A: Complete eleven-layer implementation for Altium’s investor intake context, including the adapted investor qualification scoring model (five signal groups, 0–20 rule score), OpenAI AI scoring with investor-domain prompt, additive combination formula with Hot/Warm/Cool/Cold thresholds calibrated to Altium’s IR team capacity, four-branch Qualification Switch (Hot SQL, Warm SQL, MQL, Lead), business-hours-adjusted follow-up timing metadata, governance state initialization, and intake audit Note.

Workflow B: Six-stage PERMITTED_TRANSITIONS map (Lead, MQL, SQL, Meeting Scheduled, Committed, Investor), Deal creation in “Investor Relationship” pipeline on SQL transition, Meeting Scheduled entry with manual_override_active = true, Investor entry completion handler, complete notification routing by lifecycle stage to Altium’s IR team Slack channels.

Workflow C: Schedule trigger with Altium’s business hours (8am–6pm EST, 0,30 8-18 * * *), investor-calibrated follow-up cadence intervals, per-Contact governance gate, TP1/TP2/Escalation action branches, stale deal detection for Committed-stage prospects inactive for 14+ days.

Workflow D: Typeform webhook integration for Altium’s pre-meeting qualification questionnaire (8 survey fields), identity resolution, governance gate, idempotency via response_id, scoped survey property write, investment size upgrade detection with requires_rescore_review flag.

In Scope HubSpot Configuration:

Creation of all custom Contact property groups with all required properties. Creation of custom lifecycle stages (meetingscheduled, committed) in HubSpot’s lifecycle stage configuration. Creation of “Investor Relationship” deal pipeline with stages: Introductory Call Scheduled, Materials Sent, Due Diligence, LOI Signed, Committed, Invested. Creation of HubSpot inbox views for the IR team: Active Hot Leads (Hot + SQL), Follow-up Overdue (any tier with tp1_due_at past), and Committed Pipeline (opportunity + customer stages).

In Scope Documentation:

Client User Guide (non-technical, for IR associates and IR director), Technical Implementation Notes (for Altium’s IT contact or future engineer), HubSpot Property Inventory, API Inventory, Governance Rules Reference Card, and Deployment and Environment Variable Reference.

Out of Scope (explicitly excluded):

Email content generation or AI-personalized outreach drafts. Integration with placement agent email workflow (manual entry only). Google Sheet migration (IR team migrates their own historical data). Mobile app or SMS notifications. Calendar/scheduling integration (Calendly, etc.). Reporting dashboards or custom HubSpot reports. Compliance documentation for investor communications (SEC/FINRA requirements client’s legal responsibility). CRM training beyond the provided User Guide.

Adaptation Without Unnecessary Customization

The implementation scope for Altium closely mirrors the Chapter 2.10 lab deliverables, adapted for the investor context. This is the expected pattern for a professional engagement based on a mastered architecture: the engineer already knows what the deliverables are (four workflows, HubSpot schema, documentation), what the integration checkpoints are, and what the acceptance test scenarios are.

The professional value the engineer delivers is not the discovery of these deliverables. It is the correct calibration of them for the client’s specific context and the discipline of executing them to the established quality standard.

Production Risk

Not specifying HubSpot configuration deliverables explicitly alongside the workflow deliverables creates a situation where the client considers implementation complete when the n8n Code nodes work correctly, before verifying that all properties exist in HubSpot and that scoring data is actually being written to Contact records. Every scope item must reference both the automation implementation and the HubSpot configuration it depends on. A score computation that runs correctly in n8n but writes to a property that does not exist in the target HubSpot account produces no visible result and no error.

Critical Requirement

Not including the documentation deliverables in the scope document leaves the engineer no formal basis to claim the engagement is complete before they are written, and leaves the client no formal basis to require them. The User Guide, Technical Notes, Property Inventory, and Governance Reference Card are first-class scope items with acceptance criteria: they must exist, they must be complete, and they must be in the specified format before the handover session. “Documentation” as a generic scope item without specified deliverables and formats is insufficient.

Critical Requirement

Implementing in-flight client requests without written change order approval creates a scope boundary that exists only in the engineer’s understanding, not in any shared document. After handover, the client may request that the “trivial additions” made during implementation be maintained, extended, or replaced treating them as part of the original engagement commitment. Every change to the originally approved scope document, regardless of perceived complexity, must be written up as a change order and approved by the client before implementation begins.

Diagram 2.11.3 Four-Workflow Coordination and Governance Model

%%{init:{"theme":"base","themeVariables":{"primaryColor":"#eef2ff","primaryTextColor":"#1e1b4b","primaryBorderColor":"#6366f1","lineColor":"#6366f1","clusterBkg":"#f8f9ff","clusterBorder":"#6366f1","titleColor":"#1e1b4b","edgeLabelBackground":"#f6f4ef","fontFamily":"system-ui,sans-serif","fontSize":"13px"}}}%%

stateDiagram-v2
    [*] --> lead
    lead --> marketingqualifiedlead
    lead --> salesqualifiedlead
    marketingqualifiedlead --> salesqualifiedlead
    salesqualifiedlead --> meetingscheduled
    meetingscheduled --> opportunity : Committed
    opportunity --> customer : Investor
    customer --> [*] : terminal

    note right of customer
        Invalid transition attempt:
        Alert #crm-ops + Note,
        NO side effects
    end note

Figure 28.2: Investor Lifecycle State Machine. Diagram 2.11.3a Investor Lifecycle State Machine (PERMITTED_TRANSITIONS)

%%{init:{"theme":"base","themeVariables":{"primaryColor":"#eef2ff","primaryTextColor":"#1e1b4b","primaryBorderColor":"#6366f1","lineColor":"#6366f1","clusterBkg":"#f8f9ff","clusterBorder":"#6366f1","titleColor":"#1e1b4b","edgeLabelBackground":"#f6f4ef","fontFamily":"system-ui,sans-serif","fontSize":"13px"}}}%%

flowchart TD
    Start([Before any communication action]) --> C1{manual_override_active == false?}
    C1 -->|No| Hold[Governance Hold: skip action + write governance-hold Note]
    C1 -->|Yes| C2{communication_governance_status == active?}
    C2 -->|No, paused/DNC| Hold
    C2 -->|Yes| C3{communication_cooldown_until < now?}
    C3 -->|No, within 30-min window| Hold
    C3 -->|Yes| Permit[Action Permitted: execute + update cooldown_until]
    classDef trigger  fill:#dcfce7,stroke:#16a34a,color:#14532d,font-weight:600
    classDef process  fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
    classDef decision fill:#fef9c3,stroke:#ca8a04,color:#78350f,font-weight:600
    classDef success  fill:#d1fae5,stroke:#059669,color:#064e3b,font-weight:700
    classDef fallback fill:#fee2e2,stroke:#dc2626,color:#7f1d1d

Figure 28.3: Governance Gate Decision Logic. Diagram 2.11.3b Governance Gate Decision Logic (Enforced by All Four Workflows)

Workflow Responsibilities for Governance Fields

Workflow	Governance Field Action
Workflow A (Intake)	Sets `manual_override_active = false`, `governance_status = "active"`, `cooldown_until = +30min` on intake completion
Workflow B (Lifecycle)	Sets `manual_override_active = true` on Meeting Scheduled entry (IR associate takes control); sets `manual_override_active = false` on Investor entry (engagement complete, automation may archive)
Workflow C (Follow-up Monitor)	Checks all three gate conditions before every TP1, TP2, and Escalation action; writes Note on block; updates `cooldown_until` after every permitted action
Workflow D (Survey Handler)	Checks `governance_status` and `manual_override_active` before writing survey properties (enrichment, not communication cooldown not checked by Workflow D)

IR Team Manual Override: IR associates can set manual_override_active = true in HubSpot at any time to pause automated follow-up for a specific investor. The system logs the override in the Contact Note. Removing the override resumes automated cadence. Workflow B automatically sets the override on Meeting Scheduled entry so associates need not set it manually after booking a call.

Stale Deal Detection (Workflow C): Committed-stage (opportunity) investors with no activity for 14+ days trigger a stale_opportunity_escalation alert to #ir-escalations and the IR Director, prompting manual review.

2.11.5 Evaluation Criteria

Evaluation Criteria

Evaluation criteria define the measurable standards by which the completed capstone solution will be assessed. They transform the subjective judgment “does this work?” into a set of specific, verifiable tests: “does a test submission with these exact field values produce a combined_score of X, a priority_label of Y, and a Task due within Z business hours?”

Evaluation criteria have three dimensions: functional correctness (does the system produce the correct outputs for known inputs?), operational governance (does the governance model correctly permit and block actions under specified conditions?), and documentation completeness (does the deliverables package contain all required artifacts in the specified format?).

For the capstone, evaluation criteria serve two purposes simultaneously: they define the acceptance tests the student must demonstrate to the capstone evaluator, and they model the acceptance tests the student would use to demonstrate project completion to a real client.

Evaluation criteria make the capstone objective. Without them, two students could produce systems of very different quality and have no common basis for comparing them. With precise criteria, the same test scenario the same form submission payload, the same expected HubSpot property values, the same expected Slack notification is run against every student’s implementation.

The criteria also model professional practice: before handing over a CRM automation system to a client, the automation engineer runs a set of acceptance tests with this same structure and presents the results to the client for sign-off. A client who sees documented test results with actual-vs.-expected comparison tables is far more confident in the system’s reliability than one who was told “it works.”

Altium Capital Partners Evaluation Criteria

Criterion 1 Intake Processing (Functional Correctness): Submit a test payload: referral source = “existing LP referral” (5 pts), investment size = “$2.5M–$4.9M” (4 pts), investor type = “family office” (4 pts), deployment timeline = “actively deploying” (4 pts), phone and company present (2 pts), rich inquiry description with specific capital commitment language and hard timeline. Expected outcomes: rule_score = 19; AI intent_level ≥ 7, confidence ≥ 0.85; combined_score = 19 + min(4, 7×1.0) = 23; priority_label = “Hot”; lifecyclestage = "salesqualifiedlead"; Task created with due time within 2 business hours; intake audit Note present with complete scoring trace; Slack notification to #ir-team; Workflow B fires and creates Deal in Investor Relationship pipeline.

Criterion 2 Returning Investor Detection (Constraint C3): Using the same Contact from Criterion 1 (combined_score = 23), submit a second form submission with downgraded investment size (“$500K–$999K”) and a vague inquiry description. Expected outcomes: contact_action = "updated"; Constraint C3 activates (existing combined_score 23 > 18); combined_score remains 23; priority_label remains “Hot”; no downgrade occurs. Verify that the audit Note on the second submission explicitly states “Returning investor score preserved per Constraint C3.”

Criterion 3 Governance Gate Enforcement (Operational Governance): Set the test Contact’s manual_override_active = true in HubSpot. Wait for the next Workflow C cycle after the TP1 due timestamp passes. Expected outcomes: Workflow C finds the Contact in the TP1 overdue query; governance gate checks manual_override_active = true; action is blocked; a governance-hold Note is written; followup_tp1_sent_at is NOT written (due timestamp preserved for next cycle). Remove manual_override_active. Wait for next Workflow C cycle. Expected: governance gate passes; TP1 Task created; followup_tp1_sent_at written.

Criterion 4 Invalid Lifecycle Transition Detection (Operational Governance): Manually update the test Contact’s lifecyclestage from salesqualifiedlead directly to customer in HubSpot (skipping meetingscheduled and opportunity). Expected outcomes: Workflow B’s webhook fires; PERMITTED_TRANSITIONS check finds salesqualifiedlead -> customer not permitted; invalid transition branch fires; Slack alert sent to #crm-ops; Note created on Contact recording the attempted invalid transition; no Deal creation, no journey_state update, no manual_override_active change.

Criterion 5 Survey Idempotency (Protection): Submit the same Typeform survey webhook payload twice for the test Contact. Expected outcomes: first delivery writes all survey properties and sets last_typeform_response_id; second delivery returns 200, writes no properties, does not update survey_completed_at. Verify the Contact record shows only one survey completion timestamp.

Criterion 6 Documentation Completeness: The following documentation artifacts must be present and complete: Client User Guide (non-technical, covering IR team workflow, what the system does when a lead arrives, how to pause automated follow-up, how to read the audit Note); Technical Implementation Notes (environment variables, scoring model calibration rationale, known limitations); HubSpot Property Inventory (all custom properties with names, types, groups, and owner workflows); Governance Rules Reference Card (one-page summary of PERMITTED_TRANSITIONS, governance gate conditions, and manual override protocol).

Criterion 7 End-to-End Scenario Trace: Submit a complete intake-to-lifecycle scenario adapted for Altium’s investor context and trace the execution through all four workflows. Documentation must include: the submitted test payload, a screenshot of the HubSpot Contact record showing all expected property values, the intake audit Note, the Slack notification, the Deal record in the Investor Relationship pipeline, and the n8n execution logs for all four workflows triggered by the scenario.

The evaluation criteria follow the same structure as the Chapter 2.9 scenario definitions and the Chapter 2.10 integration checkpoints. This is intentional: the scenario definition discipline, the integration checkpoint discipline, and the evaluation criteria discipline are all instances of the same professional practice stating expected system behavior precisely and verifying it against actual behavior.

An engineer who has internalized this discipline through Sections 5.9 and 5.10 can generate evaluation criteria for any CRM automation engagement without explicit guidance.

Production Risk

Defining evaluation criteria that test only the happy path is the most common acceptance testing mistake. Criteria 1 and 7 test the happy path; Criteria 2 through 5 test edge cases and governance. A solution that passes Criterion 1 and fails Criteria 2 through 5 is not a production-ready system it is a demo system. Professional evaluation criteria must always include governance enforcement tests (Criterion 3), state machine violation detection tests (Criterion 4), and idempotency tests (Criterion 5). The happy path is the easiest path to pass; it is not a sufficient proxy for system reliability.

Critical Requirement

Not treating governance enforcement tests as first-class evaluation criteria listing them as “nice to have” or “bonus” tests after the functional correctness criteria signals to the client that governance is optional. Criteria 3 and 4 are not supplementary; they test the architectural guarantees that make the system trustworthy in production. A system that correctly scores and routes leads but does not enforce the governance gate or detect invalid lifecycle transitions has the most consequential failure modes of all the ones that produce incorrect behavior silently, without surfacing an error.

Critical Requirement

Not including documentation completeness as an explicit evaluation criterion (Criterion 6) gives the documentation deliverables no formal acceptance standard. Without an explicit criterion, documentation tends to be produced as a finishing afterthought rather than as a deliverable with a specific format and completeness requirement. Criterion 6’s list of required artifacts User Guide, Technical Notes, Property Inventory, Governance Reference Card must be verified by the capstone evaluator with the same rigor as the functional tests. An evaluation that passes Criteria 1–5 and 7 but does not evaluate Criterion 6 has not completed the professional engagement simulation.

Production Consideration

Adaptation Without Documentation Is a Liability

Every deviation from the Part II reference architecture requires documentation in the Technical Implementation Notes before handover. For the Altium engagement, three adaptations are made: the investor lifecycle includes six stages with custom HubSpot names (meetingscheduled, committed); the scoring signal groups are investor-specific rather than property-type-specific; and the business hours schedule is 8am–6pm rather than 8am–8pm. Each of these deviations must be explicitly documented with the rationale not only to inform a successor engineer, but to enable the client’s IT contact to verify that the system matches its own documentation.

An adaptation that is built but not documented is indistinguishable from a bug to a successor engineer. When the Altium engagement transitions to a different engineer six months later, the successor will review the workflow configuration and see a 0,30 8-18 * * * schedule trigger. Without documentation explaining that Altium’s IR business hours end at 6pm EST, the successor may “correct” the schedule to the Part II standard (0,30 8-20 * * *) and unknowingly change the system’s behavior. Every adaptation must be documented in the Technical Notes on the day it is implemented, with the specific client requirement that produced it.

Operational Considerations

Transition Period Management

The Altium Capital Partners engagement involves a transition from an existing manual process (shared Gmail inbox + Google Sheet) to the new CRM automation platform. The transition period requires careful operational management to prevent leads from falling through the gap between the old and new systems.

The recommended transition approach has three phases. In Part I (parallel operation, weeks 1–2), the automation platform is activated for new website form submissions while the Google Sheet continues to receive manual updates. IR associates receive both the new HubSpot Task notifications and the existing Gmail forwarding. This phase validates that the platform is processing leads correctly before the old system is decommissioned. In Part II (migration, week 3), all historical active leads from the Google Sheet are manually entered into HubSpot by an IR associate. The engineer verifies that all migrated Contacts have the correct lifecycle stage and that Workflow C is not generating spurious follow-up tasks for leads already in late stages. In Part III (full adoption, week 4 onward), Gmail forwarding is discontinued for new website leads. The Google Sheet is archived as read-only. The IR team operates exclusively from HubSpot and the Slack notification channels.

Ongoing Maintenance and Support

After handover, the automation platform requires periodic maintenance in three categories. Environment variable audits (quarterly): verify that all API keys, webhook secrets, Slack channel names, and scoring configuration values are current. Scoring model review (semi-annually): review the platform’s priority tier distribution against actual investor conversion rates. If Hot leads are converting at the same rate as Warm leads, the Hot threshold may need calibration upward. If fewer than 5% of leads are reaching the Hot tier despite strong inquiry quality, the threshold may need calibration downward. Governance gate review (quarterly): review the frequency of governance-hold Notes to assess whether the manual_override protocol is being used correctly. A high frequency of governance-hold Notes for Contacts who are not under active IR management suggests that manual_override_active is being set but not cleared after conversations end.

Complete Capstone Scenario

Altium Capital Partners Engagement Brief

Client Profile: Altium Capital Partners is a New York-based commercial real estate private equity firm. Founded in 2011, the firm has closed three funds focused on value-add multifamily and mixed-use properties in the Northeast US. Fund III (closed 2021, $165M) has delivered a 14.2% IRR to date. The firm is currently raising capital for Fund IV ($200M target), with a focus on mid-market family offices, registered investment advisors (RIAs), and high net worth individuals with prior real estate fund experience.

Team Structure: IR Director: Manages investor relationships strategy, oversees the fundraise, reports to Managing Partners. IR Associate (East Coast): Manages family office and HNW individual prospects in the Northeast and Southeast. IR Associate (West Coast/Midwest): Manages RIA and institutional prospects outside the Northeast. No dedicated CRM administrator or operations staff.

Current Process: Inbound leads arrive primarily through Altium’s website contact form, placement agent introductions (email), and referrals from existing LPs. Website form leads go to a shared Gmail inbox. The IR director triages daily and forwards to associates based on geography. Associates track interactions in a Google Sheet. The fund management team receives a monthly pipeline summary prepared manually by the IR director from the Google Sheet.

Pain Points: Response time is inconsistent some leads wait 48+ hours for acknowledgment. No standardized scoring IR associates use personal judgment, leading to inconsistent prioritization. Pipeline is stale the Google Sheet is updated 3–5 days behind actual activity. No escalation mechanism leads fall silent without the IR director knowing. No audit trail when a prospect asks “when did you last contact me?”, the answer requires searching individual email inboxes.

Engagement Request: Altium has engaged the student as an automation engineer to design and implement a CRM automation platform that addresses all five pain points within the existing four-workflow architecture. Budget and timeline: 4 weeks to full deployment and handover. The IR team will be available for a one-hour discovery call, a mid-engagement review, and a one-hour handover and training session.

Technical Environment: n8n Cloud (existing account, no workflows configured). HubSpot Sales Hub Professional (existing account, some manual Contact records). OpenAI API key (provided). Typeform Business account (pre-meeting questionnaire form built). Slack workspace with channels #ir-team, #ir-escalations, #crm-ops (new channels to be created). Webflow website with existing contact form (webhook configurable).

Deliverable Expectations: At project completion, the IR team should be able to: receive a new investor inquiry and see a HubSpot Task in their queue within 2 business hours (Hot leads) or 24 business hours (Warm leads); view a real-time investor pipeline in HubSpot without engineering assistance; pause automated follow-up for a specific investor by setting a flag in HubSpot; and review the complete automated action history for any investor by opening their Contact record in HubSpot.

Implementation Guidance

Part I Discovery and Requirements (Days 1–3)

Begin with the one-hour discovery call. Use the Client Problem Analysis framework from Chapter 2.11.1 to document the current state, desired state, and requirements gap in writing before the call ends. Ask specifically about: the expected weekly lead volume (this determines Workflow C’s per-execution Contact query limit), the IR team’s capacity in active relationships per associate (this determines scoring threshold calibration), the five Slack channels and their naming convention (environment variable configuration), and any compliance considerations around investor communications (scope the exclusion explicitly if applicable).

After the discovery call, draft the System Design Requirements document (Chapter 2.11.2 template) and the Implementation Scope document (Chapter 2.11.4 template). Send both to the client for review. Do not begin implementation until both are approved in writing.

Part II HubSpot Configuration (Days 4–6)

Before configuring any n8n workflow, build the complete HubSpot data model: create all custom Contact property groups and properties, configure the custom lifecycle stages (meetingscheduled, committed) in HubSpot’s Settings, and create the Investor Relationship deal pipeline with all pipeline stages. Run a property audit query against the configured account to verify all properties exist with the correct types before any workflow configuration begins.

Part III Workflow A Implementation (Days 7–10)

Implement Workflow A using the eleven-layer structure from Chapter 2.10, adapted for the Altium investor context: investor qualification scoring signals (Chapter 2.11.3), Altium-adapted OpenAI prompt, Hot/Warm/Cool/Cold thresholds calibrated to IR capacity, Altium-specific Qualification Switch branch conditions, and governance initialization. Run integration checkpoints 2.10.1 through 2.10.7 adapted for the investor context before proceeding.

Phase 4 Workflows B, C, D Implementation (Days 11–16)

Implement Workflow B with the investor lifecycle PERMITTED_TRANSITIONS map (six stages), Deal creation in the Investor Relationship pipeline, Meeting Scheduled governance override, and Investor entry completion handler. Implement Workflow C with the adjusted business hours (8am–6pm EST for Altium), investor-calibrated cadence intervals, and IR-specific Slack channels. Implement Workflow D with Altium’s Typeform pre-meeting questionnaire field mapping (eight survey fields). Run all integration checkpoints adapted for the investor context.

Part II End-to-End Testing (Days 17–19)

Run all seven evaluation criteria from Chapter 2.11.5 against the assembled platform in the Altium HubSpot sandbox account. Document the actual results against the expected results in a Testing and Validation Results document. Any criterion that does not pass becomes a defect to resolve before proceeding.

Part III Documentation and Handover (Days 20–24)

Write all four documentation deliverables: Client User Guide, Technical Implementation Notes, HubSpot Property Inventory, and Governance Rules Reference Card. Prepare the handover presentation for the one-hour training session. Conduct the training session with the IR team (User Guide walkthrough) and the IT contact (Technical Notes walkthrough). Transfer ownership of all environment variables and API keys to the client.

Phase 7 Post-Deployment Monitoring (Days 25–28)

Stay available for one week after full deployment to production. Monitor the n8n execution log daily for errors. Address any reported anomalies using the Chapter 2.9.3 decision tree. Document any issues and resolutions in the Technical Notes. At the end of the monitoring period, send the final engagement close note confirming system stability and the quarterly maintenance schedule.

Diagram 2.11.4 Deployment and Operational Support Model

Figure 28.4: Deployment and Operational Support Model. Diagram 2.11.4 Deployment and Operational Support Model: Infrastructure Topology

Operational Responsibilities After Handover

Role	Responsibility
IR Team (no technical knowledge required)	Respond to HubSpot Task notifications; set `manual_override_active = true` when taking active control; clear `manual_override_active = false` when conversation ends; review audit Notes on Contact records before calls; report anomalies to IT contact
IT Contact / Operations (basic technical knowledge)	Rotate API keys (quarterly, per maintenance schedule); verify Slack channel access (quarterly); monitor n8n execution log for errors (weekly); forward anomaly reports to engineer (as needed)
Automation Engineer (original or successor)	Investigate and resolve reported anomalies; perform semi-annual scoring model calibration review; implement scope changes as change orders; update Technical Notes after any configuration change

Environment Variable Audit (Quarterly Checklist)

Variable	Verification Step
`HUBSPOT_API_KEY`	Test with single HubSpot GET
`OPENAI_API_KEY`	Test with minimal chat completion
`TYPEFORM_API_KEY`	Verify webhook delivery
`FORM_WEBHOOK_SECRET`	Match Webflow form configuration
`SCORING_CONFIG`	Verify JSON is valid and complete
Slack channel names	Verify bot has posting access
`FOLLOWUP_CONFIG_*`	Verify cadence intervals are current

Portfolio Packaging Guidance

The completed Altium Capital Partners capstone should be packaged as a professional portfolio asset demonstrating the student’s ability to deliver a complete CRM automation engagement. The portfolio package has nine sections.

Section 1 Architecture Overview (1 page): A client-accessible description of the complete four-workflow CRM automation platform, including an architecture diagram adapted for the investor context. Write for a non-technical business executive: describe what the system does, how investor inquiries flow through it, what decisions it makes automatically, and what the IR team’s role is in the automated process. Avoid n8n, API, and workflow terminology in this section.

Section 2 Business Requirements Summary (1 page): A summary of the five Altium pain points and how the automation system addresses each one. Format as a two-column table: Pain Point (client’s language) | Automation Solution (what the system does to address it). This section demonstrates that the engineer understood the client’s business problem, not just the technical implementation.

Section 3 Workflow Inventory (4 pages, 1 per workflow): For each workflow: trigger type, business function, key implementation decisions with rationale, inputs, outputs, error handling, and integration with the other three workflows. Written at the technical level appropriate for a successor engineer.

Section 4 API and Integration Inventory (0.5 page): Complete inventory of all external API integrations. For each: API name, endpoint(s) called, authentication method, n8n workflow and node, rate limits and retry behavior, and environment variable name for each credential.

Section 5 CRM Property Inventory (1 page): Complete inventory of all custom HubSpot Contact properties created for the platform, organized by property group. For each property: internal name, display name, type, group, owner workflow, and purpose.

Section 6 Governance Rules (1 page): The PERMITTED_TRANSITIONS investor lifecycle diagram, the three-condition governance gate specification, the manual override protocol, the communication governance status values and their operational meanings, and the follow-up cadence tiers with their interval specifications. Written for an IR associate who needs to understand what the system will and will not do automatically.

Section 7 Testing and Validation Results (1 page): A table documenting the results of all seven evaluation criteria from Chapter 2.11.5. For each criterion: criterion number and description, test inputs, expected output, actual output, and pass/fail status. Include screenshots of key HubSpot Contact records and n8n execution logs as supporting evidence.

Section 8 Deployment Notes (0.5 page): The production deployment steps, including: n8n environment variables configured, HubSpot custom properties verified, webhook endpoints registered, Slack bot access verified, and the date of first live execution. Note any deviations from the standard implementation guidance and their rationale.

Section 9 Client User Guide (2 pages): Non-technical guide for the IR team covering: what happens when a new investor submits the contact form (from the IR associate’s perspective), how to read the automated HubSpot Task notification, what the Contact audit Note contains and how to interpret it, how to pause automated follow-up for an active conversation (manual_override steps in plain language), how to advance an investor’s lifecycle stage (and what happens automatically when you do), and who to contact if something seems wrong.

Diagram 2.11.5 Client Handover and Maintenance Architecture

Handover Session (1 hour, IR team + IT contact):

Walk through Client User Guide with IR associates
Demonstrate: submit test lead -> review Task + Note
Demonstrate: set/clear manual_override_active
Walk through Technical Notes with IT contact
Transfer all environment variables and API keys
Confirm IT contact has n8n admin access

Documentation Transferred at Handover

Document	Format	Audience
Client User Guide	PDF	IR associates
Technical Implementation Notes	PDF	IT contact
HubSpot Property Inventory	Spreadsheet	IT contact
Governance Rules Reference Card	1-page PDF	IR team + IT contact
Testing and Validation Results	PDF with screenshots	IT contact
Environment Variable Reference	Encrypted	IT contact only

Ongoing Maintenance Structure

Cadence	Owner	Tasks
Quarterly (~30 min)	IT contact	Environment variable audit (checklist from Deployment Notes); Slack channel access verification; review `#crm-ops` for persistent error patterns; confirm n8n Cloud subscription is active
Semi-annually (~2 hours)	Automation engineer	Scoring model calibration review (compare priority distribution to conversion rates); governance gate frequency review (high governance-hold rate may indicate protocol issues); follow-up cadence interval review (adjust if IR team feedback indicates mismatch); update Technical Notes with any configuration changes

Change Order Process (as needed):

Client requests new capability or modification
Engineer scopes change (new scope doc, timeline, cost)
Client approves change order in writing
Engineer implements, tests against new acceptance criteria
Update all documentation before re-handover

Succession Planning (if original engineer unavailable):

Successor engineer reads Technical Implementation Notes
Reads HubSpot Property Inventory (understand data model)
Reviews Testing and Validation Results (understand accepted behavior)
Runs evaluation criteria against current system (regression test)
Contacts original engineer for context if needed

Success Metrics (6-Month Review)

Metric	Target
Average lead response time	Hot tier: < 2 business hours
Follow-up coverage rate	100% of SQL leads with TP1
Escalation rate	< 10% of Warm leads reaching ESC
Manual override usage	Tracked: frequency and average duration
IR director pipeline visibility	Qualitative: no longer stale

Client Handover Documentation

Professional automation engineers are responsible for the quality of the systems they leave behind, not just the systems they build. A handover is not a project termination it is a transfer of ownership that must be executed with the same discipline as the implementation.

The client must leave the handover session with everything they need to operate the system without the engineer present, to understand what the system is doing and why, and to know how to request changes when their needs evolve.

Client handover documentation has three audiences and three corresponding document formats. The User Guide is written for the IR team the non-technical operators who will interact with the system daily through HubSpot Tasks and Slack notifications. The Technical Notes are written for the IT contact or successor engineer the person responsible for maintaining the infrastructure, rotating API keys, and modifying the system if needed. The Governance Reference is written for both audiences a compact, plain-language summary of the rules that govern automated communication with investors.

The User Guide should answer, in sequence, the three questions an IR associate will have when using the system for the first time: “What happened to this lead in HubSpot?” (the audit Note explains what the system did), “What do I need to do?” (the Task explains what action is expected and when), and “What if I want to handle this one manually?” (the manual override protocol explains how to pause the automation).

The User Guide should never assume technical knowledge. “Set manual_override_active = true in HubSpot” is not a user guide instruction “In HubSpot, open the investor’s Contact record, find the Automation Override property, and change the value to ‘Yes’” is.

The User Guide should include screenshots from the actual deployed HubSpot account showing what a newly created Contact record looks like after intake processing, what the audit Note contains, and where to find the Task in the HubSpot task queue.

The Technical Notes document should enable a competent engineer who has never seen this implementation to understand the system in 90 minutes. It should include the architecture diagram, a narrative description of each workflow’s function and key implementation decisions, all environment variable names and their descriptions (but not their values credentials should be transferred separately through a secure channel), the scoring model calibration rationale, known limitations, and the maintenance schedule.

Technical Notes should be updated every time the system is modified, with each update dated and attributed. A notes history like “June 2026: Adjusted Hot threshold from 18 to 16 per IR director request after first scoring model review” prevents a successor engineer from “correcting” a deliberate calibration change back to the original value.

API keys, webhook secrets, and authentication tokens should be transferred to the client through a secure channel separate from the documentation package a password manager entry, an encrypted email, or a direct verbal transfer in the handover session.

The handover is not complete until the client has reviewed the evaluation criteria results from Chapter 2.11.5 and confirmed in writing that all seven criteria pass. If any evaluation criterion does not pass at handover, it is a blocking defect that must be resolved before the handover session concludes. Partial handovers “we’ll fix Criterion 4 next week” are not professional practice.

Discussion Questions

The Altium Capital Partners engagement involves transitioning an existing manual process to an automated one, with a 4-week timeline. The IR director has expressed concern that the transition period will create a window where leads could fall through the gap between the old system and the new one. What specific steps in the Part I (parallel operation) transition plan would you take to ensure no lead is lost during the transition, and how would you demonstrate to the IR director that the parallel operation period is genuinely safe before asking them to decommission the Gmail/Google Sheet process?
The scoring model calibration in Chapter 2.11.3 sets the Hot threshold at combined_score ≥ 18 to target approximately 5–10% of leads, based on the IR team’s capacity of 5 active relationships per associate per week. If after 6 months of operation the IR director reports that Hot-tier leads are converting at a 40% rate but that Hot-tier follow-up coverage is only 70% (30% of Hot leads don’t receive a TP1 Task within the SLA window), what does this tell you about the scoring model, the IR team’s capacity, and the follow-up cadence? What changes would you recommend, and what data would you need to confirm your recommendation?
The PERMITTED_TRANSITIONS map for Altium includes salesqualifiedlead -> meetingscheduled as a valid transition, but in HubSpot’s standard lifecycle model there is no meetingscheduled stage it is a custom stage. If Altium’s HubSpot administrator accidentally deletes the meetingscheduled custom stage from HubSpot’s configuration, what will happen to Workflow B when the next SQL → Meeting Scheduled transition is attempted? How would you detect this failure from the n8n execution log or from the HubSpot Contact record, and what governance protection mechanism would prevent the loss of the investor’s state?
The Client User Guide instructs IR associates to set manual_override_active = true when taking active control of an investor relationship. After six months of operation, a pattern emerges: many IR associates set the override when they begin working with a prospect but routinely forget to clear it when conversations end or go silent. As a result, 35% of the active investor pool has manual_override_active = true and is receiving no automated follow-up despite the IR associates being unaware of this. What monitoring check would detect this pattern, how would you implement it in Workflow C, and what governance rule change would you recommend to reduce the rate of indefinitely active overrides?
The Portfolio Packaging Guidance specifies a Testing and Validation Results section with pass/fail documentation of all seven evaluation criteria. A junior colleague argues that this level of documentation is unnecessary “the client can just see that the system works.” Construct a professional argument for why documented, tabular acceptance test results are a necessary component of a professional automation engagement, referencing at least two scenarios in which undocumented testing creates a meaningful operational or professional risk.
The engagement scope explicitly excludes “AI-personalized outreach email content generation.” After the handover, the IR director contacts you to request this feature as an add-on, arguing that “the AI is already integrated for scoring, so it should be trivial to add email generation.” Describe the professional process for responding to this request, including how you would scope and price the change order, what new architectural components would actually be required (referencing the Part II sections that would need to be extended), and what governance considerations would need to be addressed before automating investor-facing email content.

Chapter Summary

Chapter 2.11 completes the Automation Engineer Mastery Program’s CRM and revenue systems module by simulating a complete professional engagement: discovery, design, implementation, testing, handover, and support planning. The capstone demonstrates that the Part II four-workflow architecture is not a brokerage-specific solution it is a general-purpose CRM automation framework adaptable to any lead-driven business context through targeted calibration of the scoring signals, lifecycle stages, cadence intervals, and channel configurations. The Altium Capital Partners scenario required exactly three specific adaptations from the Part II baseline: a six-stage investor lifecycle with custom stage names, an investor qualification scoring model replacing the commercial real estate property signals, and business hours adjusted to 8am–6pm EST for the IR context. All other architectural elements the governance gate, the PERMITTED_TRANSITIONS state machine, the property ownership model, the idempotent batch upsert, the audit logging were preserved without change.

The engagement lifecycle framework provides the professional scaffolding for this adaptation: requirements analysis before design, design before implementation, implementation before testing, testing before handover. Each phase produces a specific artifact the requirements document, the system design requirements document, the implementation scope, the evaluation criteria results, the documentation package that is reviewed and approved before the next phase begins. This sequencing is not bureaucratic overhead; it is the structural guarantee that the client’s expectations and the engineer’s implementation remain aligned through all four weeks of the engagement.

The evaluation criteria in Chapter 2.11.5 define the acceptance standard for the capstone at the level of a professional delivery: seven specific, measurable tests covering functional correctness, constraint enforcement, governance gate enforcement, state machine violation detection, idempotency protection, and documentation completeness. The emphasis on governance tests (Criteria 3 and 4) and documentation completeness (Criterion 6) alongside functional tests (Criteria 1, 2, 7) reflects the professional reality that a system’s most consequential failures are silent ones incorrect behavior that produces no error and that a system without documentation is a liability, not an asset, to the client.

Transition to Chapter 2.12

Chapter 2.12 builds directly on the system constructed in this chapter.

Key Takeaways

The Part II four-workflow architecture is a general-purpose CRM automation framework. The Altium engagement required three specific adaptations (lifecycle stages, scoring signals, Slack channels); all other architectural elements are preserved as defaults.
Client problem analysis produces a three-part requirements document current state, desired state, requirements gap that is the agreement between engineer and client on what the system must do. Vague requirements produce scope disputes; precise requirements produce verifiable definitions of success.
System design requirements translate business requirements into five architectural specification areas: workflow inventory, HubSpot data model, integration inventory, governance rules, and non-functional requirements. The PERMITTED_TRANSITIONS map must be designed and client-approved before Workflow B implementation begins.
Scoring model calibration requires three inputs: qualitative client understanding of lead quality, historical or estimated lead signal distribution, and the operational capacity of the team. Threshold calibration without reference to team capacity produces a priority distribution the team cannot execute against.
Implementation scope defines deliverables with acceptance criteria, not features with descriptions. HubSpot configuration and documentation deliverables are first-class scope items. Scope exclusions must be stated explicitly. All in-flight changes require written change order approval.
Evaluation criteria transform acceptance testing from subjective judgment into a set of specific, verifiable tests. Happy path testing alone is insufficient; governance enforcement, state machine violation detection, and idempotency tests are first-class evaluation criteria.
Documentation the Client User Guide, Technical Notes, Property Inventory, and Governance Reference Card is a professional deliverable with the same acceptance standards as the workflow implementations. A working system without documentation is a liability to the client.
The handover is complete when: (a) all seven evaluation criteria are documented as passing, (b) the client has signed off in writing, (c) all credentials have been transferred through a secure channel, and (d) the IT contact has verified n8n admin access. Partial handovers are not professional practice.
The professional standard for an automation engineer is: build it, test it against defined acceptance criteria, document it for the people who will use it and maintain it, and transfer ownership with the rigor required for the client to operate it confidently without you.

End of Chapter 2.11 Capstone: Revenue System (CRM Automation)