Fionn

1. System Overview

Fionn is an AI-based software renewal management system that automates the end-to-end renewal lifecycle — from initial customer outreach through final contract closure. It operates across multiple integrated platforms to identify upcoming renewals, engage customers via intelligent email conversations, track renewal stages, and provide real-time operational visibility through a management dashboard.

Fionn replaces manual renewal management with an autonomous AI agent that handles outreach, follow-ups, sentiment analysis, pricing, quoting, and stage progression — all while maintaining strict communication discipline and contract rules.

Core Principles

• Fully autonomous — Fionn handles outreach, replies, reminders, and escalations without human intervention in standard cases
• Asynchronous communication only — all customer engagement happens via email; no calls, no meetings
• Contract discipline — pricing, terms, and contract structures are enforced programmatically
• Stage-driven progression — every opportunity follows a defined renewal pipeline with clear transition rules
• Real-time visibility — a dedicated dashboard surfaces pipeline health, AI assessments, and email activity

2. High-Level Architecture

graph TB
    subgraph FionnSystem [Fionn System]
        SF["Salesforce<br/>(Trilogy Sales + No Software Speed)"]
        CC["CuChulainn<br/>AI Engine<br/>4 Packages · 14 Skills · 1 Agent"]
        DASH["Fionn Dashboard<br/>S3 + CloudFront + Cognito SSO"]
        MCP["MCP Server<br/>Function URL"]
        SBX["Sandbox Stack<br/>Parallel test environment"]
        COMP["Compliance<br/>Indexer + Docs API"]
    end

    subgraph ExternalSystems [External Systems]
        KLAIR["Klair<br/>NetSuite Data"]
        NETSUITE["NetSuite REST<br/>Subsidiary + Subscription"]
        KAYAKO["Kayako<br/>Support Tickets"]
        OPENAI["OpenAI<br/>GPT-5.3-instant + Cost API"]
        GAS["Gmail + Apps Script<br/>gmailwatch · senders"]
        GDRIVE["Google Drive + Sheets<br/>Compliance documents"]
        ADOBE["Adobe Sign<br/>Agreements"]
        ADOPT["Klairvoyant<br/>Adoption API"]
        COGNITO["AWS Cognito<br/>Google SSO"]
    end

    SF <--> CC
    CC <--> DASH
    SF <--> DASH
    CC --> KLAIR
    CC --> KAYAKO
    CC --> OPENAI
    GAS <--> CC
    OPENAI --> DASH
    DASH <--> COGNITO
    DASH <--> MCP
    DASH <--> ADOBE
    DASH --> ADOPT
    COMP --> GDRIVE
    COMP --> NETSUITE
    DASH <--> COMP
    DASH <--> SBX
    SBX --> CC
    CUSTOMER["Customer<br/>Email Inbox"] <--> GAS
    CC --> CUSTOMER
            

3. Component Architecture

3.1 CuChulainn — AI Execution Engine

CuChulainn is the core AI platform that powers Fionn's autonomous operations. It provides the runtime for AI packages, each containing workflows, skills, and agents.

graph LR
    subgraph CuChulainn Platform
        GO["GeneralOutbound<br/>First contact with customer"]
        GI["GeneralInbound<br/>Reply to every inbound email"]
        RP["ReminderPackage<br/>Follow-up + find more users"]
        EI["EmailInvestigator<br/>Find alternate emails"]
        SA["SalesforceAgent<br/>6 Salesforce skills"]
        SK["14 Shared Skills<br/>API endpoints"]
    end

    GO --> SK
    GI --> SK
    RP --> SK
    EI --> SK
    GO --> SA
    GI --> SA
    RP --> SA
    EI --> SA
            

3.2 Fionn Dashboard — Operational Visibility Layer

The dashboard provides real-time pipeline visibility, AI health assessments, and operational controls.

3.3 Lambda Inventory

All deployed Lambdas in account 582049328161 / us-east-1. Source-of-truth deploy mappings live in .cursor/rules/lambda-deploy.mdc.

3.4 DynamoDB Tables

3.5 Scheduled Processes

Five scheduled jobs run via AWS EventBridge:

3.6 Function URL Lambdas

Two Lambdas are exposed via dedicated AWS Function URLs (no API Gateway):

4. CuChulainn Packages — Detailed Flows

4.1 GeneralOutbound

Purpose: First contact with the customer when a renewal is approaching.
Trigger: Dashboard trigger (manual or auto-trigger at ≤180 days to renewal).
Package ID: PACKAGE-d3a9354c-3d3e-4edd-9494-c55898403852 (common for all products)

flowchart LR
    T["Trigger<br/>(Manual or Auto)"] --> FETCH["Fetch Opportunity<br/>from Salesforce"]
    FETCH --> KLAIR["Get NetSuite<br/>Contract Data"]
    KLAIR --> COMPOSE["AI Composes<br/>Outreach Email"]
    COMPOSE --> SEND["Send Email<br/>to Customer"]
    SEND --> LOG["Log to<br/>FionnEmailLogs"]
    LOG --> UPDATE["Update Opp Stage<br/>→ Outreach"]
            

Key behaviors

• Retrieves full contract context from NetSuite via Klair before composing
• Email is AI-generated, warm, professional, and product-aware
• Never mentions pricing, internal IDs, or meeting requests in first outreach
• Marks opportunity as FionnTriggered = Yes in DynamoDB

4.2 GeneralInbound

Purpose: Process and respond to every inbound customer email related to a renewal.
Trigger: Google Apps Script routes inbound email to CuChulainn.

flowchart LR
    IN["Inbound Email<br/>via Apps Script"] --> PARSE["Parse Email<br/>+ Thread Context"]
    PARSE --> ANALYZE["AI Sentiment<br/>Analysis"]
    ANALYZE --> DECIDE["Determine<br/>Response Strategy"]
    DECIDE --> REPLY["AI Composes<br/>Reply"]
    REPLY --> SEND["Send Reply<br/>to Customer"]
    SEND --> STAGE["Update Stage<br/>if Needed"]
            

Key behaviors

• Maintains full thread context for coherent conversations
• Detects customer sentiment and adjusts tone accordingly
• Escalates to human when customer explicitly requests it
• Progresses stage automatically when conversation milestones are reached

4.3 ReminderPackage

Purpose: Follow up when no customer response has been received. Discovers and adds additional contacts to widen the outreach net.
Trigger: Auto-trigger (daily at 2 PM GMT for Pending opps with no reply in 5+ days) or manual dashboard trigger.
Package ID: PACKAGE-9dc9897a-3d92-4dc1-b7c6-ddd3591a74e8

flowchart LR
    CHECK["Check Last<br/>Mail Date"] --> DEFER{"Defer Signal<br/>Detected?"}
    DEFER -->|Yes| PAUSE["Pause Until<br/>Follow-up Date"]
    DEFER -->|No| CONTACTS["Find Additional<br/>Contacts"]
    CONTACTS --> COMPOSE["AI Composes<br/>Follow-up"]
    COMPOSE --> SEND["Send Reminder<br/>Email"]
    SEND --> LOG["Log + Update<br/>Reminder Count"]
            

Key Differentiator: Actively searches for additional contacts beyond Salesforce, broadening reach when the original contact is unresponsive.

4.4 EmailInvestigator

Purpose: Find alternate email addresses when delivery fails or the primary contact is unreachable.
Trigger: Called by other packages when email bounces or no response after multiple reminders.

flowchart LR
    BOUNCE["Delivery Failure<br/>or No Response"] --> SEARCH["Search Kayako<br/>+ Other Systems"]
    SEARCH --> VALIDATE["Validate Found<br/>Addresses"]
    VALIDATE --> UPDATE["Update Contact<br/>in Salesforce"]
    UPDATE --> RETRY["Retry Outreach<br/>with New Address"]
            

5. Automated Trigger & Reminder System

The system runs autonomously at 2:00 PM GMT daily via the fionn-auto-trigger Lambda.

5.1 Auto-Trigger Rules

5.2 Smart Defer Detection

Before sending any auto-reminder, the system analyzes the last 5 emails using GPT-5.3-instant to detect defer signals from the customer.

Detected signals include

• "It's too early, let's discuss later"
• "We will follow up in June"
• "Let's reconnect after Q2"
• "Can we discuss this on March 25?"
• "We're not ready yet, please reach out in 3 months"

When a defer is detected

1. GPT extracts the follow-up date (converts relative dates like "in 2 weeks" to actual dates)
2. ReminderPausedUntil is stored in DynamoDB with the extracted date
3. DeferReason captures the customer's statement
4. Reminders are suppressed until the follow-up date
5. When the date arrives, reminders automatically resume

flowchart TB
    AUTO["Auto-Trigger<br/>2 PM GMT Daily"] --> SCAN["Scan All<br/>Open Opportunities"]
    SCAN --> TRIGGER{"≤180 Days<br/>& Not Triggered?"}
    TRIGGER -->|Yes| OUTBOUND["Call Fionn<br/>Outbound API"]
    TRIGGER -->|No| PENDING{"Pending Stage<br/>& 5+ Days Stale?"}
    PENDING -->|Yes| PAUSED{"Reminder<br/>Paused?"}
    PAUSED -->|Yes, Future| SKIP["Skip — Wait for<br/>Follow-up Date"]
    PAUSED -->|No or Expired| ANALYZE["AI Analyzes<br/>Recent Emails"]
    ANALYZE --> DEFER{"Defer Signal<br/>Found?"}
    DEFER -->|Yes| STORE["Store Pause Date<br/>+ Reason"]
    DEFER -->|No| REMIND["Send Reminder<br/>via ReminderPackage"]
    PENDING -->|No| NEXT["Next Opportunity"]
            

5.3 Manual Pause/Resume

The dashboard provides manual controls to pause or resume reminders:

• Pause — Set a specific follow-up date and reason from the dashboard
• Resume — Clear any existing pause immediately
• API endpoint: POST /reminder-pause with {action: 'pause'|'resume', opportunityId, pauseUntil?, reason?}

6. Skills Reference

All skills are shared across packages. Each skill is an API endpoint performing one atomic task.

7. Agents Reference

8. Renewal Pipeline — Stage Progression

The renewal lifecycle follows a strict sequential pipeline. Fionn manages transitions automatically based on conversation state.

flowchart LR
    P["Pending"] --> O["Outreach"]
    O --> E["Engaged"]
    E --> PR["Proposal"]
    PR --> QF["Quote Follow Up"]
    QF --> F["Finalizing"]
    F --> CW["Closed Won"]
    F --> CL["Closed Lost"]
            

Stage Definitions

Stage Treatment

• Finalizing is treated as a closed stage — it is excluded from "open" counts, does not trigger reminders, and receives a deterministic GREEN AI signal
• Finalizing can result in either Closed Won or Closed Lost

9. Data Flow — End to End

graph TB
    subgraph ExternalDataSources [External Data Sources]
        SF_TS["Salesforce: Trilogy Sales<br/>Fionn AI owned opportunities"]
        SF_NS["Salesforce: No Software Speed<br/>Renewal data · ARR · Stages"]
        GDRIVE["Google Drive + Sheets<br/>Compliance documents"]
        ADOBE["Adobe Sign<br/>Agreement status"]
    end

    subgraph AIandCost [AI & Cost Services]
        OAI["OpenAI GPT-5.3-instant<br/>AI status · Summaries · Defer analysis"]
        OAI_COST["OpenAI Org Cost API<br/>Hourly billing pull"]
        AWS_COST["AWS Cost Explorer<br/>Vendor spend"]
    end

    subgraph FionnCore [Fionn Core]
        CC["CuChulainn<br/>4 Packages"]
        LAMBDA_SYNC["Lambda: Sync<br/>Daily 6 AM UTC"]
        LAMBDA_AI["Lambda: AI Scan<br/>Daily ~7 AM GMT"]
        LAMBDA_API["Lambda: API<br/>Dashboard backend"]
        LAMBDA_AUTO["Lambda: Auto-Trigger<br/>Daily 2 PM GMT"]
        LAMBDA_OAI_COST["Lambda: Cost Updater<br/>Hourly"]
        LAMBDA_COMP["Lambda: Compliance<br/>Indexer + Docs"]
        LAMBDA_MCP["Lambda: MCP Server<br/>Function URL"]
        LAMBDA_SBX["Lambda: Sandbox<br/>Testing + Query"]
        DDB["DynamoDB<br/>10 tables (prod + sandbox)"]
        DASH["Dashboard UI<br/>S3 + CloudFront + Cognito"]
    end

    SF_TS --> LAMBDA_SYNC
    SF_NS --> LAMBDA_SYNC
    LAMBDA_SYNC --> DDB
    LAMBDA_AI --> OAI
    LAMBDA_AI --> DDB
    DDB --> DASH
    DASH --> LAMBDA_API
    LAMBDA_API --> CC
    LAMBDA_API --> ADOBE
    LAMBDA_AUTO --> CC
    LAMBDA_AUTO --> OAI
    LAMBDA_AUTO --> DDB
    LAMBDA_OAI_COST --> OAI_COST
    LAMBDA_OAI_COST --> AWS_COST
    LAMBDA_OAI_COST --> DDB
    LAMBDA_COMP --> GDRIVE
    LAMBDA_COMP --> DDB
    DASH --> LAMBDA_MCP
    LAMBDA_MCP --> LAMBDA_API
    DASH --> LAMBDA_SBX
    LAMBDA_SBX --> CC
    LAMBDA_SBX --> DDB
            

Data Sync Process (Daily + On-Demand)

1. Trilogy Sales query — Fetch all Fionn AI-owned opportunity IDs via SOAP API
2. No Software Speed query — Fetch renewal data (ARR, stage, dates) for those IDs via REST API
3. Email log merge — Fetch from FionnEmailLogs DynamoDB + legacy mail tracking API
4. Safe upsert — Write to DynamoDB preserving protected fields (triggers, reminders, flags, notes, AI status, defer state)
5. Stale cleanup — Remove records no longer in Salesforce
6. AI refresh — Generate/update AI health status for all open opportunities
7. DaysSinceLastMail — Recalculated in real-time on every API response (not stored stale)

10. Dashboard Features

10.1 Hierarchical Table View

Opportunities are organized in a collapsible hierarchy:

All groups are collapsed by default. Expand All / Collapse All toggle is available. A second "Flat View" tab shows all opportunities without grouping.

10.2 Per-Opportunity AI Status

Each opportunity has an AI-generated health assessment powered by GPT-5.3-instant:

AI status is refreshed:

• Daily — automatically after sync (overdue refresh runs first so the AI prompt sees fresh AR data)
• On demand (single) — click refresh icon next to any opportunity
• On demand (bulk) — click "Refresh All AI" in toolbar (with progress polling)

10.2.1 AR / Overdue Risk Override

The AI prompt is given the customer's NetSuite overdue balance plus, for indirect deals, the reseller's overdue balance. If either is > $0 the signal is forced to RED (deterministic post-process, independent of what the model returns) and the summary is prefixed with the overdue amounts. This guarantees that an account who is 30+ days behind on invoices never shows GREEN regardless of stage or email engagement.

• Customer overdue — fetched from NetSuite via NETSUITE_OVERDUE_URL using Account.NetSuite_ID__c; stored as OverdueBalance + OverdueBalanceUpdatedAt.
• Reseller overdue — only captured when the SF OpportunityPartner relationship has a Reseller/Distributor/VAR record (the SOQL pulls AccountFrom.NetSuite_ID__c). Stored as ResellerOverdueBalance + ResellerOverdueBalanceUpdatedAt + ResellerNetSuiteID. Opps where reseller is only inferred from the opp-name pattern get a ResellerName label but no NS lookup.

10.3 AI Status Click-to-Expand

Clicking an AI signal expands an inline detail panel below that opportunity showing:

• Color-coded signal badge (On Track / Attention / At Risk)
• Full AI-generated summary text
• Last updated timestamp

10.4 Smart Reminder Controls

Each opportunity's reminder column shows contextual controls:

• Active — "Remind" button + pause (⏸) button to manually set a follow-up date
• Deferred (AI-detected) — Green badge with follow-up date + resume (▶) button
• Deferred (Manual) — Blue badge with follow-up date + resume (▶) button
• Expired pause — "Remind" button reappears + clear (✕) button

10.5 KPI Cards & Running Totals

10.6 Additional Features

• Sync Health — Trilogy Sales count vs Dashboard count, missing opportunity tracking
• Email History — Full conversation thread per opportunity with HTML rendering, quoted replies, signatures; external images stripped for tracking pixel protection
• Notes — Internal notes per opportunity with timeline view and delete
• Flags — Flag at-risk opportunities for visibility
• PDF Reports — Filtered renewal reports with AI executive summary, cover page with stage breakdown, timeline, legend; loading indicator prevents double-clicks
• CSV Export — Configurable column selection, grouping by BU/Product
• Product Configuration — Manage product settings with Ephor Project IDs; product alias mapping for Salesforce name variations
• Searchable Multi-Select Filters — Product, Stage, Fionn Status, Open/Closed (with separate Finalizing option), Renewal Window
• Support Link — Direct link to fionn-renewals.kayako.com
• Architecture Page — This document, accessible from the sidebar

10.7 Dashboard Sections (Sidebar Views)

The dashboard exposes multiple views via the sidebar in dashboard/index.html + dashboard/app.js. Some are admin-only (gated by FionnUsers role). The sidebar order matches the in-product order; Performance is the default landing route after sign-in (Viewer accounts fall back to Renewals).

Performance, Renewals, and Conversation Quality share a single Unified Filter Bar (Date Range · BU · Products · Stages · Fionn Status · Renewal Window · ARR Tier · Status · Search). Filter state persists in URL params with a localStorage fallback (fionn.filters.v1) and follows the operator across these three views — an active-filter pill row appears above the KPIs with per-pill clear buttons and a "Clear all" link. The BU control is a preset that auto-populates Products with the selected Business Unit's product list (mirrors BUSINESS_UNIT_MAP in backend/lambdas/lambda_handler.py); manually editing products auto-resets BU to "All". Window-scope KPIs and charts respect the Date Range; portfolio-scope sections are tagged with a Portfolio badge and ignore the Date Range.

The Performance header is organised into three semantic strips: Portfolio (Total ARR Managed — portfolio-scope, ignores Date Range), Retention (Gross Retention, Net Retention, DM%, Renewal Event Retention — all window-scope, Playbook conventions; Net Retention carries a ✓/⚠ indicator vs the 90% floor), and ARR Flow (Closed ARR, Active ARR, New ARR out-for-signature, Churn $, Downsell $, Overdue ARR). Gross and Net Retention share the same denominator (Total Revenue = Old ARR = Curr ARR on Won + Lost); Gross clamps each renewal to min(New, Curr), Net includes upsells. DM% (Double Maintenance) = (Total Revenue + Upgrades − Downgrades − Churn + New Business) / Total Revenue, with New Business = 0 for this dataset. Every $ tile in the flow strip is a drill-through: clicking mutates the unified FILTERS state (status/stages/win, preserving dr) and navigates to the Renewals or Agreements view. Prior-window deltas (same-length window immediately preceding) appear as ▲/▼ arrows; colours invert for churn and downsell so rising = red. Overdue ARR ignores the Date Range end (always as-of-now) and renders a red accent when > 0.

Below the three primary strips, the Performance tab renders a secondary Agent metrics row containing five demoted KPIs (Win Rate, Automated Resolution, Response Rate, Avg Reminders / Deal, Avg Emails to Close) plus a Conversation Quality link tile that navigates to the Conversation Quality view. Each tile exposes its formula as small muted text at rest (readable without hovering). Win Rate, Automated Resolution, and Response Rate render a 90-day weekly SVG sparkline (_perfSparkline) with a dashed target line — 80%, 50%, 60% respectively — and the line/last-point colours green when at/above target, amber when below.

The Performance tab also carries three window-scoped diagnostic charts/queues, all respecting the unified filter bar: (1) HVO Cadence Funnel — opportunities with ARR_USD (or ARR) ≥ $100K distributed across cadence buckets (Pre-cadence >210d / Upcoming / Mid / Urgent / Overdue) using DaysToRenewal; bars are clickable drill-throughs into Renewals with win+tier=hvo pre-applied, and an "N off-cadence" pill surfaces when any HVO falls into the Overdue bucket. (2) AR Step Funnel — Sub-HVO accounts (<$100K) on auto-renewal, counted at each of the six live notice milestones projected on Opportunity: D-104 → D-89 → D-60 → D-40 → D-14 → D-0 (confirm). (3) Escalation Queue — a table of AI-flagged escalations (AISignal=RED) sorted by urgency (lowest DaysToRenewal) then ARR desc, with a "N flagged" pill in the header. The Stage Funnel bars now carry inline numeric labels via the shared _perfValueLabelsPlugin (Chart.js afterDatasetsDraw). Earlier iterations included three placeholder sections (D-82/D-21/D-7 greyed AR bars, a Pricing Strategy Mix card awaiting Opportunity.PricingStrategy__c, and a "Linked Fix Ticket" column awaiting FixTicketURL) — all removed to keep the Performance tab live-data-only.

The Adobe Sign Quote & Term Breakdown (3 summary tiles: Agreements Sent · Signed · Waiting to be Signed, plus 4 term cards: 12mo, 36mo, 60mo, No Term Data) lives on the Agreements tab rather than Performance. The "No Term Data" card absorbs agreements with no matched opp/term and non-standard terms (18/24/48/…). renderQuoteTermBreakdown(_agreementsData) is called from refreshAgreements() and from _refreshAgreementsAfterOverride() so that manual signed overrides propagate into the breakdown tiles.

Settings access. Settings is no longer a sidebar nav entry — it now opens from a gear icon at the bottom of the sidebar (Admin-only). The redesigned modal uses a card-based product list with inline search, two-column forms, and in-modal toast feedback instead of blocking alert() dialogs. Esc closes the modal; overlay click still dismisses.

Agreements carry an optional manual status override (e.g. "customer signed outside Adobe Sign"). Overrides are stored per-browser in localStorage["fionn.agreementStatusOverrides"] keyed by Adobe Sign agreement ID; the override rewrites the effective status at match-cache build time, so Performance Strip 3 ("New ARR out-for-signature"), the Agreements table, the Quote & Term Breakdown, and the status chip counters all stay coherent without branching. The raw Adobe Sign status is preserved on _rawStatus and exposed in the agreement detail panel alongside an Undo control.

Standalone pages

• live.html — Live Activity feed (polls /live-activity) + Fionn AI WebSocket chat tab
• swagger.html — Public OpenAPI 3 documentation page (auth banner)

11. Integration Map

graph TB
    subgraph ExternalDataSources [External Data Sources]
        SF_TS["Salesforce: Trilogy Sales<br/>Fionn AI owned opportunities"]
        SF_NS["Salesforce: No Software Speed<br/>Renewal data · ARR · Stages"]
        KLAIR["Klair<br/>NetSuite contract · Pricing"]
        NETSUITE["NetSuite REST<br/>Subsidiary · Subscription"]
        KAYAKO["Kayako<br/>Support tickets · Contacts"]
        GDRIVE["Google Drive + Sheets<br/>Compliance documents"]
        ADOBE["Adobe Sign<br/>Agreements"]
        ADOPT["Klairvoyant Adoption API"]
    end

    subgraph AIServices [AI Services]
        OAI_CC["OpenAI<br/>CuChulainn email gen + sentiment"]
        OAI_DASH["OpenAI GPT-5.3-instant<br/>AI status · Defer · Summaries"]
        OAI_COST["OpenAI Org Cost API"]
        AWS_COST["AWS Cost Explorer"]
    end

    subgraph FionnCore [Fionn Core]
        CC["CuChulainn<br/>4 Packages"]
        LAMBDA["AWS Lambda<br/>18 functions"]
        MCP["MCP Server<br/>Function URL"]
        WS["WebSocket Chat<br/>fionn-chat-websocket"]
        DDB["DynamoDB<br/>10 tables"]
        DASH["Dashboard UI<br/>S3 + CloudFront"]
    end

    subgraph AuthAndComms [Auth & Communication]
        COGNITO["AWS Cognito<br/>Google SSO"]
        GAS["gmailwatch + senders<br/>Apps Script"]
        CUST["Customer<br/>Email inbox"]
    end

    SF_TS --> LAMBDA
    SF_NS --> LAMBDA
    LAMBDA --> DDB
    DDB --> DASH
    LAMBDA --> OAI_DASH
    LAMBDA --> OAI_COST
    LAMBDA --> AWS_COST
    LAMBDA --> ADOBE
    LAMBDA --> ADOPT
    LAMBDA --> NETSUITE
    LAMBDA --> GDRIVE

    CC --> KLAIR
    CC --> KAYAKO
    CC --> OAI_CC
    CC --> SF_NS

    DASH --> COGNITO
    DASH --> LAMBDA
    DASH --> MCP
    DASH --> WS
    WS --> CC
    MCP --> LAMBDA
    LAMBDA --> CC

    GAS --> CC
    CC --> CUST
    CUST --> GAS
            

12. Security & Authentication

13. Communication Guardrails

Fionn operates under strict communication rules enforced at the package level:

Forbidden in All Outbound Communication

• Pricing, contract terms, or deadlines (first outreach only)
• Meeting or call invitations
• Phone numbers, Calendly links, scheduling URLs
• Internal identifiers (NetSuite ID, Opportunity ID, ARR)
• Urgency or pressure language
• Assumptions about customer knowledge of renewal processes

Required in All Communication

• HTML formatted emails
• Professional, warm, non-aggressive tone
• Product name referenced (not internal codes)
• Signed as "Fionn" (no placeholders)
• Single email per workflow execution
• Thread history preserved in replies

Contract Rules

• Allowed terms: 1 year, 3 year, 5 year only
• No monthly contracts, no 2-year contracts
• No custom pricing outside approved structure
• Platinum Success Tier positioned first in upgrade discussions

14. Deployment Architecture

flowchart LR
    DEV["Developer<br/>Machine"] --> FE["S3 Upload<br/>index.html · app.js<br/>styles.css · logo.png<br/>architecture.html"]
    DEV --> BE["Lambda Deploy<br/>lambda_handler.py<br/>→ API + Sync + Auto-Trigger"]
    DEV --> RT["API Gateway<br/>Route creation"]
    DEV --> EB["EventBridge<br/>Schedule rules"]
    FE --> CF["CloudFront<br/>Cache Invalidation"]
    CF --> LIVE["Live Dashboard"]

    style LIVE fill:#EDFAF3,stroke:#1A7F4B,color:#1A1A18
            

15. Email Pipeline

All customer email flows through a layered pipeline: a Gmail Apps Script poller (gmailwatch) routes inbound mail to CuChulainn, dedicated sender scripts handle outbound, and an event logger persists every send/receive into DynamoDB.

graph LR
    INBOX["Customer<br/>Inbox"] --> GAS["gmailwatch<br/>Apps Script poller"]
    GAS --> CC["CuChulainn"]
    GAS --> BOUNCE["/handle-bounce/"]
    GAS --> LOGIN["/log-inbound/"]
    GAS --> PRODQ["fionn-product-query<br/>sandbox-query"]
    CC --> SENDER["emailsenderprod<br/>or emailsendersandbox"]
    SENDER --> LOGGER["fionn-email-logger"]
    LOGGER --> DDB[("FionnEmailLogs<br/>+ Sandbox mirror")]
    SENDER --> INBOX
    CC --> GMAIL_API["lambda_gmail_thread<br/>Gmail API skill"]
            

Components

16. MCP Server

fionn-mcp-server (backend/lambdas/lambda_mcp_server.py) exposes 56 Fionn operations as Model Context Protocol tools over Streamable HTTP. This lets external MCP clients (Claude Code, Claude Desktop, Cursor) drive Fionn programmatically — querying opportunities, sending emails, triggering AI analysis, and more.

Endpoint

https://eu4zkntsvzzv66gwmir2lragi40kxcpe.lambda-url.us-east-1.on.aws/?token=<MCP_ACCESS_TOKEN>

Authentication

• Bearer token in URL query string (?token=...) or Authorization: Bearer header
• Token stored as Lambda environment variable (MCP_ACCESS_TOKEN) and in fionn/app-keys Secrets Manager
• Surfaced to admins through the Developer view (/app-config)

Deployment note

Deploy with python3 deploy_lambda.py fionn-mcp-server. The ZIP must include both lambda_mcp_server.py and secrets_helper.py — the handler is lambda_mcp_server.lambda_handler (not the AWS default lambda_function.lambda_handler).

56 tools by category

Used from

• Claude Code / Claude Desktop — primary usage; full tool access via MCP connection
• Dashboard Developer view — copy-paste connection string + key
• Cursor and other MCP-compatible IDEs

17. Compliance System

A two-Lambda pair maintains an indexed cache of compliance documents (NDAs, MSAs, addenda) and resolves them by opportunity or NetSuite ID.

graph LR
    DRIVE["Google Drive<br/>Compliance folder"] --> INDEXER["fionn-compliance-indexer<br/>Daily EventBridge"]
    SHEET["Google Sheet<br/>Manifest"] --> INDEXER
    INDEXER --> CIDX[("FionnComplianceIndex")]
    CLIENT["Dashboard / Caller"] --> DOCS["fionn-compliance-docs<br/>Function URL"]
    DOCS --> SUB[("FionnSubsidiaryCache")]
    DOCS --> NS["NetSuite REST"]
    DOCS --> CIDX
    DOCS --> DRIVE
    DOCS --> CLIENT
            

Components

Key dependencies

• google_client.py + vendored rsa==4.9 for Drive/Sheets auth
• netsuite_client.py for subsidiary resolution
• secrets_helper.py for credential lookup

18. Sandbox Environment

A parallel sandbox stack mirrors the production pipeline so test emails, synthetic NetSuite data, and CuChulainn dry-runs never touch real customer data or production Salesforce.

Components

Related skill

• email-lookup-sandbox — Cursor skill at .cursor/skills/email-lookup-sandbox/SKILL.md for checking if an email thread exists in the sandbox database during testing

19. Customer Asks (Request Tracker)

A standalone web page (dashboard/requests.html, separate from the main renewals dashboard) that surfaces every distinct customer request extracted from email threads (Phase 2: Salesforce meeting transcripts). Each ask is classified into legal / compliance / finance / document / other and routed to the appropriate ticket system. The board hides any opportunity that is not in an in-progress stage or has zero open asks.

graph LR
    GMAIL["Gmail inbound"] --> WATCH["gmailwatch<br/>Apps Script"]
    WATCH -->|/log-inbound| API["fionn-dashboard-api"]
    API --> LOGS[("FionnEmailLogs")]
    SF[("Salesforce<br/>Opportunity + Transcripts")] --> EXT["fionn-request-extractor<br/>EventBridge 30 min"]
    LOGS --> EXT
    EXT -->|"OpenAI classify"| REQS[("FionnRequests")]
    EXT -->|doc lookup| CIDX[("FionnComplianceIndex")]
    CIDX -. auto-resolves doc asks .-> REQS
    EXT -->|writes rollup| DASH[("FionnDashboard<br/>OPP#id#DETAILS")]
    REQS --> PAGE["dashboard/requests.html<br/>standalone page"]
    DASH --> PAGE
    PAGE -->|"POST /asks/create-ticket<br/>(Phase 3)"| ROUTER["fionn-ticket-router"]
    ROUTER --> JIRA["Jira REST<br/>legal"]
    ROUTER --> KCOMP["Kayako Compliance dept"]
    ROUTER --> KFIN["Kayako Finance dept"]
    SYNC["fionn-ticket-sync<br/>EventBridge 30 min<br/>(Phase 4)"] --> JIRA
    SYNC --> KCOMP
    SYNC --> KFIN
    SYNC --> REQS
            

Components (Phase 1 shipped)

Categorisation & ticket routing

Board visibility rules (server-side, non-toggleable)

• Stage ∉ { Closed Won, Closed Lost, Finalizing } — the board only ever shows live deals.
• asksOpenCount ≥ 1 — opps with zero open asks fall off the board automatically.
• Sorted by asksAttentionScore = Σ (urgencyWeight × (askAgeDays + 1)), descending.

Phasing

• Phase 1 (shipped) — FionnRequests table, extractor (email-only), API routes, standalone page, sidebar link in renewals dashboard.
• Phase 2 — ingest Salesforce meeting transcripts (object/field shape TBD with user).
• Phase 3 — fionn-ticket-router Lambda + Jira / Kayako secrets + drawer Create Ticket buttons.
• Phase 4 — fionn-ticket-sync EventBridge cron for ticket status backfill.
• Phase 5 — mirror to Salesforce custom object Customer_Request__c (gated on explicit user approval per workspace rules).

20. Product Portfolio

Products are organized by Business Unit. Each product has an Ephor Project ID for CuChulainn integration and may have Salesforce name aliases for normalization.

21. Automated Contact Discovery

When Fionn's outreach goes unanswered for 30 days (or a hard bounce occurs immediately), this system automatically discovers and validates new contacts at the customer company using a role-prioritized external lookup, then restarts outreach.

Discovery Flow

graph TB
    subgraph Detection [Detection — Daily Cron]
        Scan[Scan FionnDashboard<br/>for stale opps]
        Bounce[Hard bounce<br/>immediate trigger]
        Stale[0 replies after<br/>30 days]
    end
    subgraph Discovery [Discovery — Per Opportunity]
        Adobe[AdobeSign Delegation<br/>Lookup — Priority 0]
        Apollo[Apollo People Search<br/>Role Priority Matrix 1-7]
        Merge[Merge & Deduplicate<br/>vs existing SFDC contacts]
        Verify[Email Verification<br/>via Apollo]
    end
    subgraph WriteBack [Write-Back]
        SFDC[Create Contact in<br/>Salesforce + ContactRole]
        DDB[Store queue in<br/>FionnContactDiscovery]
        Fionn[Fionn picks up<br/>contact on next cycle]
    end
    subgraph Fallback [14-Day Fallback — Daily Cron]
        Check[Check active<br/>discovery timers]
        Advance[Advance to next<br/>contact in queue]
        Escalate[Escalate to human<br/>after 3 contacts]
    end
    Scan --> Stale
    Scan --> Bounce
    Stale --> Adobe
    Bounce --> Adobe
    Adobe --> Apollo
    Apollo --> Merge
    Merge --> Verify
    Verify --> SFDC
    SFDC --> DDB
    DDB --> Fionn
    Check --> Advance
    Advance --> Escalate
        

Role Priority Matrix

Lambda Functions

HTTP API Routes

DynamoDB Table: FionnContactDiscovery

Partition key: pk (OPP#<opportunityId>), Sort key: sk (DISCOVERY). Stores the discovery queue, current contact index, status (active/exhausted/resolved), and source summary for each opportunity.

External Integrations

• Apollo.io — People Search API for contact discovery + built-in email verification. Secrets: fionn/apollo
• Adobe Sign — Delegation history lookup for high-signal prior signers. Reuses existing fionn/adobe secrets
• Salesforce (NSS) — Contact + OpportunityContactRole write-back with Contact_Source__c tag

Escalation

When all 3 discovery contacts are exhausted (3 × 14-day cycles = 42 days), the system generates a structured escalation report for Clarisa/Jay containing: company name, renewal date, every contact tried (name, title, source, dates, verification status), and a recommendation.