Skip to main content

Understanding Your Chuff CRM Data Model

At the heart of Chuff is a well-organized system for storing all your important customer information. This system, often called a data model, defines how different pieces of information are connected and stored. Understanding this helps you see the complete picture of your customer relationships and why certain features work the way they do.

Think of Chuff as a highly organized digital filing cabinet. Instead of just throwing everything into one big pile, we use different "folders" (which we call data entities or models) for different types of information, and we make sure these folders are linked together logically.

Your Core CRM Data Entities​

Chuff is designed around a few key types of information, which are organized into distinct data entities:

1. Tenants (Your Account)​

  • What it represents: Your entire Chuff account. When you sign up for Chuff, you create a "Tenant." This is your dedicated space within Chuff where all your team's data resides, completely separate from other businesses using Chuff.
  • What it holds: Your company's name, a unique web address (slug) for your account, and important dates like when your account was created. It also manages if your account is temporarily deleted or scheduled for permanent removal.
  • Why it's important: It's the foundational "container" for all your CRM data, ensuring your information is secure and private to your business.

2. Users (Your Team Members)​

  • What it represents: Each individual person on your team who uses Chuff.
  • What it holds: Basic details for each team member like their name, email, job title, and their specific role within Chuff (e.g., "user," "admin"). It also stores their unique login information (your password is kept secure and encrypted). We also track if an account is pending, invited, or active, and if a user has been deactivated.
  • Why it's important: Users are linked directly to your Tenant, allowing team members to access your shared CRM data. This link also enables features like assigning contacts or companies to specific team members.

3. People (Your Contacts and Leads)​

  • What it represents: All the individual contacts and leads you interact with. This is one of the most central pieces of your CRM.
  • What it holds: Essential contact information like first name, last name, primary email address (which can also track if it's verified), phone numbers, and social media links (Facebook, LinkedIn, etc.). It also includes their job title, location, and the company they're associated with.
  • Tags: You can add tags to people for quick categorization (e.g., "VIP," "Prospect," "Customer").
  • Status: A general status field helps categorize where a person is in your process (e.g., "new," "contacted," "qualified").
  • Custom Fields: This is where Chuff shines! Beyond the standard information, you can add your own custom fields to track unique details important to your business, such as "Lead Score" or "Last Product Interest." These fields are defined separately but appear directly on each person's profile.
  • "Master" vs. "View": Chuff actually uses two "layers" for People data:
    • Person Master: This holds the core, unchanging details about a person (like their name and primary contact info).
    • Person View: This is the version you interact with daily. It links to the Master record and also includes your team's specific information, like who the person is assigned to within your company, any overrides to their details (like a specific job title your team uses), their status, and your custom fields. This separation helps keep your core contact data clean while allowing your team to add their own context.
  • Why it's important: This is where you store all the details about the individuals you're building relationships with, enabling personalized outreach and effective follow-ups.

4. Companies (Your Organizations)​

  • What it represents: All the companies and organizations your contacts belong to, or that you're targeting.
  • What it holds: Company name, description, website domains, industry, and social media links. You can also track their headquarters location, estimated revenue, number of employees, funding raised, and foundation year.
  • Tags: Similar to people, you can use tags to categorize companies (e.g., "Key Account," "Target," "Competitor").
  • Custom Fields: Just like with People, you can add your own custom fields to company profiles to track unique business-level details like "Account Tier," "Last Contact Date," or "Annual Contract Value."
  • "Master" vs. "View": Similar to People, Companies also have a "Master" record for core company details and a "View" record that includes your team's specific assignments, overrides, and custom fields.
  • Why it's important: Companies provide crucial context for your contacts, allowing you to manage relationships at an organizational level and understand the broader business landscape.

5. Custom Fields (Your Customizations)​

  • What it represents: The definitions of any extra fields you've created to personalize your Chuff CRM.
  • What it holds: The unique name you give to your custom field (e.g., "Deal Stage"), what type of data it holds (e.g., text, number, true/false), and whether it applies to People or Companies. It also tracks who last updated the custom field definition.
  • Why it's important: This entity ensures that when you add custom information to a Person or Company, Chuff knows what kind of data to expect and how to validate it.

Additional Data Entities for Enhanced Functionality​

Beyond the core CRM elements, Chuff includes several specialized data entities that power advanced features like automated outreach and communication tracking:

6. Snippets (Reusable Content Blocks)​

  • What it represents: Short, reusable pieces of text or content that you can quickly insert into emails or messages. Think of them as your go-to phrases, common answers, or compelling statements.
  • What it holds: A title to help you identify the snippet (e.g., "Problem Statement," "Why Us") and the actual content of the snippet itself. Each snippet is linked to your account (Tenant) and the user who created it.
  • Why it's important: Snippets save you time and ensure consistency in your messaging, especially when crafting personalized outreach campaigns. You write it once, and reuse it everywhere!

7. Campaigns (Automated Outreach Sequences)​

  • What it represents: A series of automated messages or actions designed to engage with a group of people over time, often for sales or marketing purposes.
  • What it holds:
    • Core Information: A unique name for your campaign, its type (usually "sequence"), and links to the user who created it and your Chuff account (Tenant).
    • Sender Account: It links to a Third-Party Authentication record, which specifies the email account (like your Gmail or Outlook) from which the campaign messages will be sent.
    • Sending Rules: You can define specific allowed days for sending, a maximum number of messages per hour, and a start/end hour for sending each day.
    • Behavior Rules: You can choose whether the campaign stops automatically on a reply, preventing you from sending unwanted follow-ups once a conversation has started.
    • AI Guidance: You can provide a goal for the campaign (what you want to achieve), a style for the messages (e.g., "formal," "casual," "persuasive"), and even specific phrases or topics you want the AI not to say.
    • Content Building Blocks: You can link to Snippets to ensure certain key messages or information are included in your campaign.
    • Status: A status helps you manage campaigns (e.g., "draft," "active," "inactive").
  • Why it's important: Campaigns are the engine of automated personalization, allowing you to consistently engage with leads and customers at scale, using AI to craft relevant messages.

8. Campaign Recipients (Who's in Your Campaigns)​

  • What it represents: Each individual person who is currently part of a specific campaign.
  • What it holds: Links to the specific Campaign they're enrolled in and to their Person View record. It tracks their status within the campaign (e.g., "new," "sent," "replied," "finished") and when their next message is scheduled to be sent.
  • Why it's important: This entity allows Chuff to manage the progress of each person through your campaigns, ensuring they receive messages at the right time and that the campaign reacts appropriately to their engagement (like stopping on a reply).

9. Message Templates (Blueprint for Messages)​

  • What it represents: The actual content blueprint for each step within a campaign.
  • What it holds:
    • Campaign Step Information: Linked to a Campaign, it defines the channel (e.g., "email," "SMS"), the message type (e.g., "new" for an initial message or "reply" for a follow-up), and the wait time (in hours) before the next message in the sequence is sent.
    • AI-Generated Content: If AI created the message, it stores the AI's rationale (why it chose certain wording), the subject line, and the main message template (the body of the message).
    • Step Order: A step_id helps define the order of messages within a campaign sequence.
  • Why it's important: Message Templates ensure that your automated campaigns deliver consistent, well-structured, and (if AI-generated) contextually relevant messages at each stage of your outreach.

10. Outbox (Scheduled & Sent Messages)​

  • What it represents: A record of all messages that are scheduled to be sent, currently pending, or have already been sent from Chuff.
  • What it holds:
    • Recipient & Campaign Info: Links to the Campaign, Message Template, and Campaign Recipient involved, as well as the specific Person View the message is for.
    • Sender & Contact Info: The sender account (via Third-Party Auth) used to send the message and the recipient's contact account (e.g., their email address).
    • Message Details: The subject and the full message content to be sent.
    • Status: Tracks the current status of the message ("scheduled," "pending," "sent," "failed").
    • Metadata: An optional meta field for storing any additional technical details or context about the message.
  • Why it's important: The Outbox acts as a queue and a log, ensuring that messages are delivered reliably and providing a clear record of all communication initiated from Chuff.

11. Third-Party Auth (Connecting Your Other Accounts)​

  • What it represents: Your securely stored login details for connecting Chuff to external services like your email provider (Gmail, Outlook) or other tools.
  • What it holds:
    • Type & Provider: Specifies the type of connection (e.g., "email," "API") and the provider (e.g., "gmail," "msft," "resend").
    • Account Details: The specific email address or account name associated with the connection.
    • Security: This is where Chuff securely encrypts and stores your authentication token (like an access key) and details about the authentication schema (how Chuff connects to that service). It also tracks if the token is still valid.
    • Email Specifics: For email accounts, you can add a custom signature that will be appended to your outgoing messages and enable an auto-enrich feature to automatically update contact details from incoming emails.
  • Why it's important: This is the secure bridge that allows Chuff to send emails on your behalf, sync inboxes, and potentially connect with other applications, all while keeping your credentials safe.

12. Touchpoints (Tracking All Interactions)​

  • What it represents: A comprehensive log of every communication interaction you have with your contacts, whether it's an email sent by Chuff or a reply received.
  • What it holds:
    • Interaction Details: The type of interaction (e.g., "email," "WhatsApp"), the provider (e.g., "Gmail," "MSFT"), and links to the Third-Party Auth account and potentially the Campaign involved.
    • People Involved: A list of Person Views linked to this touchpoint, so you know which contacts were part of the conversation.
    • Sender & Recipients: The "from" email address, and lists of "to" and "cc" email addresses.
    • Message Content: The timestamp of the interaction, the subject, a short message preview, and an S3 key (a technical reference) to retrieve the full message body if needed.
    • Metadata: An optional meta field for storing additional technical details.
  • Why it's important: Touchpoints create a complete timeline of your communication history with each contact, providing full visibility into all interactions and helping AI agents understand context for more personalized responses.

How Everything Connects (Expanded)​

The power of Chuff's data model comes from how these different entities are linked:

  • Tenant is the Hub: Every User, Custom Field definition, Person, Company, Snippet, Campaign, Campaign Recipient, Message Template, Outbox entry, Third-Party Auth record, and Touchpoint is linked to a specific Tenant. This keeps your business's data isolated and secure.
  • Users Manage Data & Campaigns: Users create and manage Snippets, Campaigns, and are often the "assigned to" a Person or Company.
  • Third-Party Auth Powers Outreach: Your connected email accounts (Third-Party Auth) are used by Campaigns to send messages, and by Touchpoints to log incoming and outgoing communication.
  • Campaigns Drive Engagement: Campaigns define the strategy, Message Templates provide the content for each step, and Campaign Recipients track who's currently being engaged.
  • Outbox & Touchpoints Log Communication: The Outbox queues messages to be sent, and Touchpoints record every single interaction, building a rich communication history for each Person.
  • People and Companies are Central: All communication (Campaigns, Outbox, Touchpoints) ultimately revolves around engaging with your People and Companies, with custom fields adding unique context to these core records.

Why This Matters to You​

Understanding this structure helps you:

  • Organize Your Data: You'll know exactly where to find and store different types of information.
  • Improve Data Quality: The defined relationships and field types help ensure your data is clean and accurate.
  • Leverage Chuff's Features: Many features, especially those involving AI agents and reporting, rely on this underlying structure to provide intelligent insights and automation.
  • Troubleshoot Issues: If something isn't working as expected (e.g., a campaign message isn't sending), knowing how the data is structured can help you understand where to look for potential issues (e.g., checking your Third-Party Auth connection).

Chuff's data model is designed to be robust and flexible, giving you the foundation you need to manage your customer relationships effectively and adapt the CRM to your unique business needs.