You asked your AI assistant a question - and it confidently gave you an answer. But here's the part nobody tells you: that answer might be months - or even years - out of date.

Every AI model has a "Knowledge Cutoff Date" - the point where its learning froze. After that, the world kept moving. New technologies launched. Elections happened. Companies merged. Regulations changed. But your AI? It stayed stuck in time.

Understanding this isn't optional anymore - it's critical. Whether you're a developer, a marketer, a student, or a business leader - knowing when your AI's knowledge expires can save you from costly, embarrassing mistakes.

What Exactly Is a Knowledge Cutoff Date?

Think of an AI model like a student who studied intensively for years, then locked themselves in a room. Everything they learned before entering that room? Crystal clear. Everything that happened outside after the door closed? Completely unknown.

A Knowledge Cutoff Date is the final date up to which an AI model's training data was collected. The model was trained on billions of texts, articles, books, and web pages - but only up to that specific moment in time.

Why Does This Matter?

If you ask an AI about a law that changed after its cutoff, a product that launched after its cutoff, or a person who rose to fame after its cutoff - it either won't know, or worse, will confidently give you outdated information as if it's current fact.

Knowledge Cutoff Dates: All Major AI Models Compared

Here's what the evidence reveals - cross-verified and fact-checked:

Fact-Check Note: Perplexity describes itself as 'powered by Grok 4.1' in the screenshot - this is Perplexity's interface using xAI's Grok model as its backend engine. Perplexity itself is the product; Grok 4.1 is one of the underlying models it may route queries through. This is accurate as of early 2026.

Deep Dive: What Each AI Actually Said

1. Perplexity AI - 'No Strict Cutoff'

Perplexity boldly claims it has no strict knowledge cutoff date like traditional static models. Instead, it uses tools like real-time web search to fetch the latest information for every single query. As of March 3, 2026, it can reflect current events accurately - making it one of the most 'live' AI assistants available.

✅ Verdict: Accurate. Perplexity is fundamentally a retrieval-augmented AI - it searches the web before answering, which genuinely reduces the knowledge gap problem.

2. DeepSeek - 'May 2025'

DeepSeek transparently states its knowledge cutoff is May 2025. What's fascinating is its visible 'thinking' process - it shows its internal reasoning before delivering a clean, concise answer. This chain-of-thought transparency is a genuine differentiator for DeepSeek.

✅ Verdict: Accurate. DeepSeek R1/V3 series has a training cutoff around May 2025. The reasoning transparency shown is genuine.

3. Claude (Anthropic) - 'Early August 2025'

Claude clearly states a cutoff of early August 2025. It also proactively acknowledges the ~7-month gap to the current date (March 2026) and offers to use web search to fill the gap. This transparency-first approach is by design - Anthropic prioritizes honesty about limitations.

✅ Verdict: Accurate. Claude's training data extends to early August 2025.

4. Figma Make AI - 'Early 2025'

Figma Make's embedded AI is specialized - it exists primarily to help build web applications using React and Tailwind CSS inside Figma's development environment. Its knowledge cutoff is early 2025, but this matters less given its narrow, code-generation focus.

✅ Verdict: Accurate. Figma Make uses a focused AI optimized for front-end code generation, not general knowledge tasks.

5. ChatGPT - 'June 2024'

The screenshot shows a tool reporting a cutoff of June 2024 for its core training data. It also mentions personalization - suggesting this may be a custom GPT or a version of ChatGPT with memory enabled.

⚠️ Validation Note: OpenAI's GPT-4o has a training cutoff of April 2024, while GPT-4 Turbo's is December 2023. 'June 2024' may reflect a specific model variant or custom GPT configuration. Always verify which exact model version you're using.

6. Gemini 3 Flash - 'Real-Time via Google Search'

Gemini 3 Flash claims it doesn't have a single static cutoff date - instead, it's integrated with Google Search for real-time retrieval. It knows today is March 3, 2026, and can access current events as they happen - making it competitive with Perplexity in the 'live knowledge' category.

✅ Verdict: Accurate. Google's Gemini models are increasingly integrated with Search for grounding. However, for very niche breaking news, it recommends double-checking.

Real-World Consequences: When Cutoff Dates Bite

Here's why this isn't just a technical curiosity - it's a practical risk:

• Legal & Compliance: A lawyer using AI to research regulations that changed after the cutoff could provide incorrect advice.
• Medical Information: Healthcare guidance based on outdated studies could be genuinely harmful.
• Financial Decisions: Market data, interest rates, or company valuations from before the cutoff are now misleading.
• Technology Recommendations: Recommending a framework version that has since been deprecated or has known security vulnerabilities.
• Competitive Intelligence: A product strategy based on competitor info that's 12 months old.
• News & Current Events: Treating an AI summary as current news when it predates major world events.

🔑 The Golden Rule: Always match your task type to your AI tool. For current events -> use Perplexity or Gemini. For deep reasoning on stable knowledge -> Claude or DeepSeek. For code generation -> Figma Make excels in its niche.

Why Do Knowledge Cutoff Dates Change - And Why Do They Stay Fixed?

This is one of the most misunderstood aspects of AI. People wonder: 'If AI is so smart, why can't it just keep learning?' The answer is fascinating - and it reveals how fundamentally different AI training is from human learning.

Why Cutoff Dates Get Updated

AI companies periodically release new model versions with extended cutoff dates. This happens for several important reasons:

1. Competitive Pressure: The AI race is fierce. OpenAI, Google, Anthropic, and others must regularly update models to stay relevant. A model with a 2-year-old cutoff becomes commercially unviable.
2. Scheduled Retraining Cycles: Most top-tier AI labs run major training cycles every 6–12 months. Each new cycle incorporates a more recent data snapshot, pushing the cutoff date forward.
3. User Demand & Feedback: When millions of users report that an AI 'doesn't know' about major recent events, companies are pressured to update sooner.
4. Infrastructure Improvements: As compute becomes cheaper and training pipelines more efficient, updating models becomes faster and more cost-effective.
5. Safety & Alignment Research: New versions incorporate the latest safety techniques - meaning a model update isn't just about knowledge, it's about being safer too.

📅 Real Example: Claude's cutoff advanced from April 2024 (Claude 3) -> January 2025 (Claude 3.5) -> August 2025 (current Claude). Each new version pushed the knowledge boundary forward. This is normal, expected, and ongoing.

Why Cutoff Dates Stay Fixed - The 6 Core Limitations

Even if an AI company wanted to give a model 'live' knowledge, it's architecturally very hard - and comes with serious trade-offs.

1. 💸 Training Cost Is Astronomical

Training a frontier LLM costs tens to hundreds of millions of dollars and consumes enormous GPU compute. You simply cannot retrain a full model weekly or even monthly. Each training run is a massive, deliberate, expensive operation - not a button you press lightly.

2. 🗂️ Data Curation Takes Months

You can't feed an AI 'everything on the internet today.' Training data must be carefully collected, cleaned, filtered for quality, deduplicated, checked for harmful content, and formatted correctly. This data pipeline itself takes months - meaning by the time training starts, the data is already somewhat outdated.

3. 🔐 Weights Are Frozen After Training

Once an LLM's training is complete, its weights - the billions of numerical parameters that encode knowledge - are frozen. The model does not 'learn' during conversations. Every chat session starts from the same fixed state. Injecting new knowledge post-training requires either fine-tuning or a completely new training run.

4. 🧠 Continuous Learning Creates 'Catastrophic Forgetting'

Neural networks have a known problem: if you keep training them on new data without full retraining, they tend to 'forget' what they previously learned - a phenomenon called catastrophic forgetting. This makes incremental online learning technically challenging and potentially harmful to model quality.

5. 🛡️ Safety & Alignment Validation

Before any model is released publicly, it undergoes extensive safety evaluation - red-teaming, bias testing, harmful output detection, and alignment validation. This process alone can take weeks to months. You can't rush it just because the training data is fresh.

6. ⚖️ Copyright & Legal Constraints

Not all internet content can legally be used for training. Licensing agreements, copyright law, and data privacy regulations (GDPR, CCPA) restrict which data can be harvested. Curating legally compliant training datasets is a complex, ongoing challenge - not just a technical one.

What Does an AI Actually Do When You Ask Something Beyond Its Cutoff?

When you ask an AI about something that happened after its training cutoff, it doesn't crash or say 'error.' It does something far more nuanced - and sometimes problematic.

Scenario 1: The AI Doesn't Know It Doesn't Know 😬

This is the most dangerous scenario. The AI has no direct information about the event, but it has enough related context to construct a plausible-sounding answer. It doesn't flag uncertainty. It just... answers. Confidently.

Example: You ask about the outcome of an election that happened 3 months after the AI's cutoff. The AI might describe the political landscape as it was before the election and present it as current fact - without ever signaling it's outdated.

⚠️ This is called 'hallucination by omission' - the AI doesn't lie, but it omits the crucial caveat that its information is outdated.

Scenario 2: The AI Honestly Acknowledges the Gap ✅

Well-designed AI systems - like Claude - are trained to recognize when a query likely touches post-cutoff territory and proactively say so. You'll see responses like:

"My training data goes up to August 2025. For the most current information on this topic, I recommend checking recent news sources - or I can use web search to look it up for you."

This is the ideal behavior - transparency about limitations paired with an active offer to help bridge the gap.

Scenario 3: The AI Makes a Confident 'Best Guess' 🎲

For some questions, the AI extrapolates from trends it knows. If you ask about a technology trajectory or market direction, it might make a projection based on patterns in its training data - and present it with moderate confidence. Sometimes these guesses are surprisingly accurate. Other times, they're completely wrong because of unexpected events (a pandemic, a sudden market crash, a regulatory change).

Scenario 4: The AI Uses Web Search to Fill the Gap 🔍

This is the most powerful modern solution. Tools like Perplexity, Gemini (with Search), ChatGPT (with browsing), and Claude (with search enabled) can reach outside their training data and retrieve real-time information. The AI essentially becomes a reasoning layer on top of live search results.

Behavior Risk Matrix

The Technical Truth: What Happens Inside the Model

When an LLM receives a query about something beyond its training data, here's what actually happens at a technical level:

1. Token Prediction Still Runs: The model generates a response token-by-token based on the probability distributions learned during training. It has no internal 'flag' that says 'I don't know this specific thing.'

2. Related Patterns Fill the Gap: The model finds the closest related patterns in its training data and generates a coherent response based on those patterns - even if those patterns don't apply to the new situation.

3. Context Window is the Lifeline: If you paste current information INTO the conversation (like a news article), the model CAN reason about it correctly. It uses in-context information over its trained knowledge - which is why providing context with your questions dramatically improves accuracy.

4. Retrieval-Augmented Generation (RAG) is the Solution: The industry's answer to this limitation. RAG systems retrieve relevant, current documents first, then feed them to the model as context before generating a response. This is exactly what Perplexity and Gemini do with web search.

💡 Pro Tip for Advanced Users: You can partially overcome an AI's knowledge cutoff right now - without web search. Simply paste the relevant current information (a news article, a document, a data table) directly into your conversation. The AI will reason about YOUR provided context rather than relying solely on its training data. This works with any AI model.

How to Protect Yourself: 5 Practical Tips

1. Always Ask Your AI Its Cutoff Date

Before any important task, ask: "What is your knowledge cutoff date?" Most models will tell you honestly - as this blog demonstrates.

2. Cross-Reference Time-Sensitive Facts

For anything involving dates, events, laws, prices, or people in current roles - verify with a current web source. Use your AI to understand and synthesize, not as the sole source of truth.

3. Use the Right Tool for the Right Job

Need real-time information? Use Perplexity or Gemini (with Search enabled). Need deep reasoning, coding help, or document analysis? Claude and DeepSeek excel. Need to build a UI fast? Figma Make is purpose-built.

4. Enable Web Search Features When Available

Most AI platforms - including Claude, ChatGPT, and Gemini - offer optional web browsing features. Always enable these when working on current events or recent developments.

5. Treat AI Outputs as a Starting Point, Not an Endpoint

AI is your powerful research assistant, not your final authority. The best AI users are the ones who combine AI's speed and breadth with their own critical thinking and current knowledge.

The Future: AI That Never Goes Stale?

The trend is clear - the industry is moving toward Retrieval-Augmented Generation (RAG) and real-time search integration. Perplexity and Gemini are leading this shift, while ChatGPT and Claude offer web search as optional features.

We're entering an era where the distinction between 'trained knowledge' and 'live knowledge' will blur. Future AI systems may continuously learn and update - though this brings its own challenges around accuracy, bias, and information verification.

🚀 The Bottom Line: Knowledge cutoff dates are not a bug - they are an architectural feature of how LLMs are built. Understanding them doesn't make you distrust AI. It makes you use AI smarter. And in 2026, smart AI use is a genuine competitive advantage.

Conclusion

Knowledge cutoff dates are a fundamental aspect of how AI models work, and understanding them is essential for anyone using AI tools professionally. The comparison across major AI platforms reveals a clear divide: some models like Perplexity and Gemini offer real-time access through web search, while others like Claude and DeepSeek maintain static cutoffs but excel in reasoning and specialized tasks.

The key to effective AI usage lies in matching the right tool to the right task, always verifying time-sensitive information, and treating AI outputs as starting points rather than final authorities. As the industry evolves toward more RAG-based systems, the gap between trained knowledge and live knowledge will continue to narrow.

Key Takeaways

1. Perplexity & Gemini - Real-time web access - closest to 'no cutoff'
2. Claude - August 2025 cutoff - transparent and honest about limitations
3. DeepSeek - May 2025 cutoff - unique chain-of-thought visibility
4. Figma Make - Early 2025 - specialized for UI/code generation
5. ChatGPT - Varies by model - always check which version you're using
6. Cutoff dates stay fixed due to cost, data curation time, frozen weights, catastrophic forgetting, safety validation, and legal constraints
7. When asked out-of-cutoff questions, AI may answer confidently with outdated info - always verify
8. You can bypass cutoff limits today by pasting current information directly into your AI chat
9. Always ask. Always verify. Always use the right tool for the right task.

Accessibility Starts in Design - Not in Code

Accessibility isn't a post-development checklist. It's a design decision - and it starts in Figma.

If you're estimating an HTML project from a Figma file and skipping the accessibility audit, you're setting yourself up for rework, scope creep, and frustrated clients. Here's everything you need to catch issues before they cost you.

Every week, developers receive Figma links with beautiful interfaces - pixel-perfect gradients, clever micro-interactions, carefully chosen typography. And almost every week, those same designs contain accessibility issues that will cost hours to fix after the fact.

Low contrast text. Missing focus states. Form labels replaced by placeholder text. Touch targets the size of a fingernail. These aren't edge cases. They're endemic to the way most UI design currently works.

"An accessible design isn't a differently constrained design. It's a better design - for every user, on every device, in every context."

The good news: WCAG compliance is entirely auditable inside Figma, before any code is written. This guide walks you through every principle, every check, and every tool you need to make accessibility part of your estimation and handoff workflow.

The 4 Principles of WCAG - P.O.U.R.

WCAG (Web Content Accessibility Guidelines) is built on four non-negotiable pillars. Every rule in the standard traces back to one of these principles. Understanding them changes how you read a Figma file.

👁️ 1. Perceivable - Can Every User See It?

Information and UI components must be presentable to users in ways they can perceive. This covers contrast ratios, alt text for images, text over gradients, and ensuring color is never the sole means of conveying information.

⌨️ 2. Operable - Can Every User Interact with It?

UI components and navigation must be operable. All interactive elements need visible focus states, logical tab order, minimum touch target sizes of 44×44px, and controls for any animations or auto-advancing content.

🧠 3. Understandable - Can Every User Understand It?

Information and operation of the UI must be understandable. Navigation must be consistent, CTAs must be descriptive, error messages must explain what went wrong, and forms must have visible labels - not just placeholders.

💪 4. Robust - Does It Work Everywhere?

Content must be robust enough to be reliably interpreted by assistive technologies. This means proper heading hierarchy (one H1 per page), ARIA role annotations in Figma, semantic landmark regions, and fully designed component states.

Principle 1 - Perceivable: Color Contrast

Contrast is the single most frequently failed WCAG criterion in real-world designs. Here's what the numbers mean and what to check.

Contrast Ratio Standards

Color & Contrast Checklist

• [x] Text contrast ≥ 4.5:1 (AA) - Normal body text on any background, including text layered over images or gradients (WCAG 1.4.3)
• [x] Large text contrast ≥ 3:1 - Applies to text 18px+ regular weight, or 14px+ bold (WCAG 1.4.3)
• [x] UI component contrast ≥ 3:1 - Buttons, input borders, icons, focus rings, and interactive elements against their background (WCAG 1.4.11)
• [x] Color is not the only indicator - Error states, required fields, and links must also use icons, underlines, or labels - not just a color change (WCAG 1.4.1)
• [x] Placeholder text contrast - Placeholder text in form fields must still pass the 4.5:1 threshold (WCAG 1.4.3)
• [x] Disabled state contrast - Disabled elements are exempt from contrast requirements, but must be explicitly marked in the design as intentional (WCAG 1.4.3)

Typography & Readability Checklist

• [x] Body text ≥ 16px - Designs that use 12–13px for body copy will fail readability standards and require revision (WCAG 1.4.4)
• [x] Line height ≥ 1.5× font size - Tight leading significantly reduces readability for users with dyslexia and cognitive disabilities (WCAG 1.4.12)
• [x] No text embedded in images - Text inside images cannot be resized, translated, or read by screen readers (WCAG 1.4.5)
• [x] Layout works at 400% zoom - No horizontal scrolling, no content clipping, and no overlap of elements when zoomed (WCAG 1.4.10)

Images & Media Checklist

• [x] Alt text annotated for all images - Figma annotations should describe image content; decorative images must be marked as presentational (WCAG 1.1.1)
• [x] Icon-only elements have labels - Any icon without visible text must have an annotated accessible name (ARIA label) for screen readers (WCAG 1.1.1)

Principle 2 - Operable: Focus, Navigation & Interaction

A design that only works with a mouse is a design that fails millions of users. Every interactive state must be explicitly designed in Figma - never left to browser defaults.

The Focus State Problem

The most commonly missing design element in Figma handoffs is the focus state. Browsers have default focus rings, but they are frequently overridden with outline: none in CSS - and then nothing replaces them. This leaves keyboard users with no visual indicator of where they are on the page.

Every clickable element in a Figma design needs a purpose-built focus state.

What to Flag in Your Estimation

When reviewing a Figma file, document these as design gaps that require resolution before development begins:

• -> Missing focus states on buttons and links
• -> Touch targets smaller than 44×44px
• -> No error or disabled state designed
• -> Form fields missing visible labels
• -> Animations with no pause control
• -> Links distinguishable only by color
• -> Heading hierarchy not established
• -> Modal and drawer states undefined

"Catching an accessibility failure in Figma takes 30 seconds. Catching it after development takes 3 hours. Catching it after a client audit takes much longer."

Operable Checklist

• [x] Visible focus state on every interactive element - Buttons, links, inputs, dropdowns, modals. The focus ring must have at least 3:1 contrast against adjacent colours (WCAG 2.4.7)
• [x] Logical tab order annotated - Use the Focus Orderer plugin or numbered annotations to define the expected keyboard navigation sequence (WCAG 2.4.3)
• [x] Touch targets ≥ 44×44px - Especially critical for mobile designs; includes icon buttons, close buttons, and navigation items (WCAG 2.5.5)
• [x] Animations have pause/stop controls - Carousels, auto-playing videos, parallax backgrounds, and looping animations require a mechanism to stop or pause (WCAG 2.2.2)
• [x] No content flashes more than 3× per second - Rapidly flashing content can trigger seizures in photosensitive users (WCAG 2.3.1)

Principle 3 - Understandable: Clear, Consistent Design

Forms: The Most Commonly Broken Pattern

Forms are where the most Understandable-principle failures occur. The pattern is almost always the same: a beautifully minimal form with light placeholder text, no visible labels, and error states that only change a border color. All three of these are WCAG failures.

Every input field must have a persistent visible label that does not disappear when the user starts typing. Error messages must identify what went wrong and how to fix it. Required fields must be marked in a way that doesn't rely solely on an asterisk color.

Understandable Checklist

• [x] All form inputs have a visible label - Placeholder text alone fails this criterion; the label must persist even after the user begins entering data (WCAG 1.3.1)
• [x] Error messages are descriptive - "Invalid input" fails; "Please enter a valid email address" passes. Error states must be visible in the Figma design (WCAG 3.3.1)
• [x] CTA labels are descriptive - Buttons and links labelled "Click Here" or "Read More" fail; screen readers read these out of context, so each label must stand alone (WCAG 2.4.4)
• [x] Navigation is consistent across pages - The position, order, and labelling of navigation elements must not change between pages without user action (WCAG 3.2.3)
• [x] Confirmations for destructive actions - Delete, submit, and other irreversible actions must have a confirmation step designed in Figma (WCAG 3.3.4)

Principle 4 - Robust: Semantic Structure

Robust / Semantic Structure Checklist

• [x] Heading hierarchy is logical - One H1 per page, followed by H2 -> H3 in order. Headings must not skip levels (WCAG 1.3.1)
• [x] Landmark regions annotated - Header, Nav, Main, Footer, and Aside regions should be labelled in Figma using the A11y Annotation Kit so developers implement them correctly (WCAG 1.3.6)
• [x] All component states designed - Default, Hover, Focus, Active, Disabled, and Error. States that aren't designed in Figma will be skipped or inconsistently implemented (WCAG 4.1.2)
• [x] ARIA roles annotated where needed - Custom components like sliders, accordions, tabs, and carousels need their ARIA role documented alongside the design (WCAG 4.1.2)

The Best Figma Plugins for WCAG Auditing

You don't need to eyeball contrast ratios or count pixels manually. These four plugins cover every WCAG check in this article.

🔌 Stark

The most comprehensive accessibility suite for Figma. Covers color contrast, color blindness simulation (8 types), focus order visualization, and exportable accessibility reports. Premium tier unlocks full audit features.

Contrast Color Blindness Reports

🔌 A11y - Color Contrast Checker

Scans entire frames or selected layers at once and flags every failing contrast pair with WCAG level indicators. The fastest way to do a full-page contrast audit before writing your estimate.

Batch Scan AA / AAA

🔌 Contrast by Able

Quick, lightweight contrast checker. Select two layers and instantly see the ratio plus WCAG pass/fail for AA and AAA. Ideal for checking individual components during the design review process.

Quick Check Lightweight

🔌 A11y Annotation Kit

A design system of annotation components for marking up Figma files with reading order, ARIA roles, landmark regions, and focus order. Essential for producing developer-ready, accessible handoffs.

Annotations Handoff

Browser-Based Tools

Full WCAG Quick-Reference Checklist

Conclusion

Make Accessibility Part of Every Estimate

The next time you receive a Figma link for an HTML project, run through this checklist before writing a single number in your estimate. Identify every missing state, every low-contrast text pair, every label-less form field, and document them explicitly.

This serves two purposes. First, it protects you from scope creep when a client asks why a "simple" page took longer than expected. Second, and more importantly, it starts a conversation about quality - and positions you as a developer who builds things right, not just fast.

"Catching an accessibility failure in Figma takes 30 seconds. Catching it after development takes 3 hours. Catching it after a client audit takes much longer."

Accessibility is not a constraint on creative design. The contrast ratios, the touch targets, the clear labels - these make interfaces better for everyone. A design that passes WCAG AA isn't a compromised design. It's a more considered one.

Key Takeaways

1. Audit accessibility in Figma before development - WCAG compliance is entirely checkable at the design stage, saving hours of rework later
2. Follow the P.O.U.R. principles - Perceivable, Operable, Understandable, and Robust are the four pillars every design must satisfy
3. Contrast is the #1 failure - Text contrast ≥ 4.5:1 (AA) and UI component contrast ≥ 3:1 are the most commonly missed requirements
4. Design every interactive state - Focus, hover, active, disabled, and error states must all exist in Figma - not be improvised during development
5. Forms need visible labels - Placeholder text is not a label; every input needs a persistent, visible label
6. Use Figma plugins - Stark, A11y Color Contrast Checker, Contrast by Able, and A11y Annotation Kit cover every check in this guide
7. Document design gaps in estimates - Flag missing states, low-contrast pairs, and label-less fields before quoting development time

Next Steps

1. Install the recommended Figma plugins (Stark, A11y Color Contrast Checker, A11y Annotation Kit)
2. Run a contrast audit on your current Figma project using the checklist above
3. Create a reusable WCAG checklist template for your team's estimation workflow
4. Share the 24-point quick-reference checklist with your design team to prevent issues at the source

Additional Resources

• WCAG 2.1 Guidelines - W3C
• WebAIM Contrast Checker
• Who Can Use - Accessibility Impact Tool
• Stark Figma Plugin
• A11y Annotation Kit for Figma
• Adobe Color Accessibility Tools

A Real-World Case Study from Performance Optimization Experience

If you've ever worked on Core Web Vitals optimization, you've likely experienced the frustration: you fix performance issues, deploy your changes, and then... nothing happens. Days pass, metrics stay unchanged, and you start questioning whether your optimizations actually worked.

While working on enterprise website performance optimization, I uncovered something surprising that led me down a path of discovery about how Google's Core Web Vitals really work - and more importantly, what the infamous '28-day period' actually means.

The Scenario: What We Experienced

Our optimization journey started like most: we identified issues, implemented fixes, and expected to see improvements reflected in our Core Web Vitals scores. Instead, we found ourselves in a waiting game.

What we discovered:

• Changes took approximately 28 days to fully reflect in CrUX reports
• CrUX generates reports based on real user data for both Mobile and Desktop
• When we made recurring changes within the 28-day window, results became inconsistent and less accurate
• Most surprisingly: when development was on hold for 2-3 months, our Core Web Vitals scores improved dramatically

This led us to a hypothesis: Does Google wait for a 28-day 'idle stage' before validating Core Web Vitals improvements?

The Investigation: Understanding the 28-Day Window

To validate our hypothesis, we needed to understand the source of truth. Here's what we discovered about how Core Web Vitals measurements actually work.

What the 28-Day Period Really Means

According to the official Chrome UX Report documentation, Core Web Vitals in Google Search Console and CrUX are based on a rolling 28-day aggregated real user data window.

CrUX uses a 28-day rolling window of aggregated real user metrics.

Critically, this is NOT:

• A 28-day waiting period before changes are recognized
• An idle validation period requiring no code changes
• A freeze window where deployments must stop
• A 'no change' requirement for accuracy

Instead, it's simply a rolling average that continuously aggregates data from the last 28 days of real Chrome users.

Lab Data vs. Field Data: The Critical Difference

Understanding why changes don't reflect immediately requires knowing the difference between two types of performance data:

Lab Data (Synthetic Testing):

• Tools: Lighthouse, PageSpeed Insights (lab section)
• Characteristics: Immediate, controlled, synthetic environment
• Updates: Reflects changes instantly

Field Data (Real User Monitoring):

• Tools: CrUX, Google Search Console Core Web Vitals Report
• Characteristics: Real Chrome users, actual devices, real network conditions
• Updates: Aggregated over 28 days, gradual improvement visibility

The gradual reflection happens because:

• Day 1 after fix: Only 1 day of improved data in the 28-day window (27 days still contain old, poor performance data)
• Day 7: 7 days good + 21 days old data
• Day 14: 50% good, 50% old data
• Day 28: 100% improved data - full reflection of your optimizations

The Revelation: Why the Development Hold Improved Our Scores

When our development was on hold for 2-3 months, we weren't experiencing some special 'idle stage' recognition from Google. Instead, several factors converged:

1. No New Regressions

During the hold period:

• No new JavaScript bundles were added
• No A/B experiments introduced performance variability
• No layout shifts from new features
• No Google Tag Manager additions
• No caching rule changes that could impact load times

2. The Rolling Window Caught Up

Our previous optimizations needed the full 28 days to completely phase out old, poor-performing data. Once the window fully contained post-optimization data, scores reflected the true improvements.

The result: Clean, stable performance with consistent LCP, CLS, and INP metrics across the entire 28-day window.

3. Statistical Smoothing Effect

CrUX calculates 75th percentile metrics across:

• All page visits
• All Chrome users
• All device categories (mobile, desktop, tablet)
• The last 28 days of data

When you continuously deploy changes, you introduce variability that affects percentile calculations. When the site remains stable, percentiles stabilize and outliers reduce, leading to score improvements.

Why Recurring Changes Hurt Accuracy

We observed that making recurring changes within 28 days resulted in less accurate results. Here's why:

Scenario: Multiple deployments within 28 days

• Day 1-7: Good LCP after optimization
• Day 8: New heavy script added, LCP regresses
• Day 12: Script optimized
• Day 15: New Google Tag Manager tag affects performance
• Day 18: Tag issue fixed

Result: The 28-day window now contains:

• Multiple different performance states
• Mixed percentile calculations
• High variability and noise in the data

CrUX aggregates all of this, making the signal noisy and harder to interpret. The metrics you see represent an average of multiple performance states, not a clear picture of your current optimization level.

Official Sources of Truth

Here are the authoritative references that confirm the rolling 28-day window methodology:

1. Chrome UX Report Methodology

https://developer.chrome.com/docs/crux/methodology/

2. Defining Core Web Vitals Thresholds

https://web.dev/articles/defining-core-web-vitals-thresholds

3. Search Console Core Web Vitals Report

https://support.google.com/webmasters/answer/9205520

All of these official resources confirm:

• Rolling 28-day window of real user data
• 75th percentile metric calculation
• Daily data updates (not 28-day delays)
• No 'idle stage' requirement

The Verdict: Myth Busted

Our Original Hypothesis: Google waits for 28 idle days with no changes before validating improvements.

Reality: ❌ This is not officially correct.

The Correct Understanding:

Google continuously aggregates the last 28 days of real user data. Stability improves percentile metrics. Frequent changes increase variance and delay visible improvement - not because Google requires idle time, but because statistical consistency requires stability.

Professional Recommendations for Enterprise CWV Optimization

Based on real-world optimization experience, here's the recommended approach:

1. Fix Performance Issues Comprehensively

Address all identified performance bottlenecks in a single, well-tested deployment rather than making incremental changes across multiple deployments.

2. Implement a Performance Freeze Period

After major performance optimizations, freeze performance-affecting deployments for at least 28 days. This isn't because Google requires it - it's because statistical consistency requires stability.

3. Monitor CrUX Trends Actively

Track your rolling 28-day metrics daily. You should see gradual improvement starting around day 7-14, with full reflection by day 28.

4. Implement Performance Guardrails

Avoid during optimization periods:

• Uncontrolled Google Tag Manager additions
• New third-party scripts without performance testing
• A/B tests that don't have performance guardrails in place

5. Use Real User Monitoring (RUM) for Immediate Feedback

Don't rely solely on CrUX. Implement RUM tools to get real-time feedback on your optimizations without waiting for the 28-day window to complete.

One More Critical Factor: Traffic Volume

CrUX only reports data if a minimum traffic threshold is met. If your traffic is:

• Low volume
• Highly fluctuating
• Seasonal in nature

This impacts statistical stability. Changes in traffic patterns can also explain unexpected improvements or regressions in Core Web Vitals scores.

Conclusion: Understanding Leads to Better Optimization

This Core Web Vitals optimization journey taught an important lesson: sometimes what appears to be a platform requirement is actually a statistical reality of how data is aggregated.

The '28-day idle period' isn't a Google requirement - it's a byproduct of how rolling averages work combined with the need for statistical stability in real user monitoring.

Key Takeaways:

• CrUX data updates daily but uses a 28-day rolling average
• Changes are reflected gradually, not after an idle period
• Stability improves accuracy - not because of platform requirements, but because of statistics
• Frequent deployments create noise in percentile calculations
• You can make continuous improvements - but for accurate measurement, allow 28 days of stability after major optimizations

By understanding the mechanics behind Core Web Vitals measurement, you can design better optimization strategies that account for how the data actually works, rather than fighting against perceived platform limitations that don't actually exist.

About This Case Study

This case study is based on real-world performance optimization work on enterprise websites, focusing on Core Web Vitals improvements and the practical challenges teams face when measuring their impact. The insights shared here aim to help other teams navigate the complexities of Core Web Vitals optimization with a better understanding of how the measurement system actually works.

This document provides a professional security assessment of Cursor AI based on its official security documentation. It covers the key pros and cons of using Cursor for client projects, highlights critical risks, and provides actionable recommendations for secure configuration. Understanding these implications is essential before adopting Cursor AI in any professional or enterprise environment.

✅ PROS

1. Compliance & Auditing

• SOC 2 Type II certified (industry standard)
• Annual penetration testing by third parties
• Transparent security documentation

2. Privacy Mode (CRITICAL for Client Work)

• Zero data retention agreements with all AI providers (OpenAI, Anthropic, Google, xAI, etc.)
• Code never stored or used for training in Privacy Mode
• Enforced at team level (auto-enabled for team members within 5 minutes)
• Dual infrastructure (separate replicas for privacy vs. non-privacy mode)
• Over 50% of users already use Privacy Mode

3. Infrastructure Security

• US-based infrastructure (AWS primary, Azure/GCP secondary)
• No Chinese infrastructure or subprocessors
• Multi-factor authentication enforced
• Least-privilege access controls

4. Codebase Indexing Controls

• Can be completely disabled
• .cursorignore support (like .gitignore for AI)
• File path obfuscation for privacy mode users
• No plaintext code stored on servers in Privacy Mode

5. VS Code Foundation

• Built on open-source VS Code (battle-tested codebase)
• Regular upstream security patches merged

⚠️ CONS & RISKS

1. CRITICAL: All Code Goes Through Their Servers

• Even with your own API keys, code still routes through Cursor's AWS infrastructure
• No direct-routing to your enterprise OpenAI/Azure/Anthropic
• No self-hosted deployment option
• This is a dealbreaker for some enterprises

2. Codebase Indexing Vulnerabilities

⚠️ Key Concerns:
- Enabled by default (must be manually disabled)
- File path obfuscation leaks directory hierarchy
- Academic research shows embedding reversal is possible
- Git history indexed (commit SHAs, parent info)
- Secret key for obfuscation shared across team members in same repo

3. Extension Security Gaps

• Extension signature verification disabled by default (unlike VS Code)
• Workspace Trust disabled by default (protection against malicious folders)
• You're exposed to malicious extensions

4. Data Retention Caveats

• If you're NOT in Privacy Mode, data may be used for training
• Account deletion takes up to 30 days
• Already-trained models won't be retrained if your data was used

5. Maturity Concerns

Their own admission:

"We are still in the journey of growing our product and improving our security posture. If you're working in a highly sensitive environment, you should be careful when using Cursor (or any other AI tool)."

6. Third-Party Data Exposure

• 13+ subprocessors see your code data
• Turbopuffer stores obfuscated embeddings (still vulnerable to attacks)
• Web search feature exposes derived code data to Exa

7. Network Overhead

• Heavy indexing load causes failed requests
• Files may be uploaded multiple times
• Higher bandwidth usage than expected

🎯 Recommendations for Client Project

MUST DO:

1. Enable Privacy Mode IMMEDIATELY - Configure at team level
2. Disable codebase indexing - Settings -> Turn off indexing
3. Create comprehensive .cursorignore - Block sensitive files:

   .env
   .env.*
   secrets/
   config/credentials.*
   private-keys/
   *.pem
   *.key
   

4. Enable Workspace Trust - Set security.workspace.trust.enabled: true
5. Review network whitelist - Ensure corporate proxy allows required domains
6. Document in client contract - Disclose that code transits Cursor's servers

SHOULD DO:

1. Review client's data classification requirements
2. Get explicit client approval for using Cursor
3. Set up team-level privacy enforcement
4. Monitor network traffic to repo42.cursor.sh initially
5. Educate team on privacy mode requirements

CONSIDER ALTERNATIVES IF:

• Client has strict data sovereignty requirements (healthcare, finance, defense)
• Client prohibits code leaving their infrastructure
• Client requires self-hosted solutions
• Client is in regulated industry with strict compliance (HIPAA, SOC 2 Type II for their own product)

ACCEPTABLE FOR:

• Standard commercial projects
• Projects without strict IP protection requirements
• Rapid prototyping and development
• Projects where productivity gains outweigh security concerns

🔒 Secure Configuration Checklist

Team Settings:
  ✓ Privacy Mode: Force enabled at team level
  ✓ Codebase Indexing: Disabled
  ✓ Workspace Trust: Enabled
  
Project Setup:
  ✓ .cursorignore created
  ✓ Sensitive directories excluded
  ✓ API keys in environment variables only
  
Network:
  ✓ Corporate proxy configured
  ✓ Required domains whitelisted
  
Documentation:
  ✓ Security policies documented
  ✓ Client disclosure completed
  ✓ Team training on privacy mode

Final Verdict

Proceed with Cursor IF:

• You enable Privacy Mode at team level
• You disable codebase indexing
• Client approves third-party AI tool usage
• Project doesn't involve highly sensitive IP

DO NOT proceed with Cursor IF:

• Client requires on-premise/self-hosted solutions
• You're in healthcare, defense, or highly regulated industries
• Client has strict data residency requirements
• Client IP is highly proprietary/competitive advantage

Conclusion

Cursor AI can be a powerful productivity tool for client projects, but it requires careful security configuration. The critical takeaway is that all code transits Cursor's servers - even with your own API keys - making Privacy Mode and codebase indexing controls non-negotiable for professional use. For standard commercial projects with proper configuration (Privacy Mode enabled, indexing disabled, .cursorignore in place), Cursor is a viable and productive choice. However, for highly regulated industries or clients with strict data sovereignty requirements, alternative self-hosted solutions should be explored. Always document AI tool usage in client contracts and obtain explicit approval before adoption.

Short Answer: Overrides force ALL packages in your project to use specific versions of dependencies, even when those packages ask for different versions.

Not a "Patch" or "Workaround" - It's a legitimate feature introduced in npm 8.3.0 to solve real dependency management problems.

💡 Real-World Problem It Solves

The Dependency Hell Problem

Imagine this scenario:

Your Project
├── You want: React 19.0.0
│
├── Package A (FullCalendar)
│   └── Asks for: React ^16.8.0 || ^17.0.0 || ^18.0.0
│       └── ❌ Doesn't mention React 19!
│
├── Package B (some-ui-lib)
│   └── Asks for: React ^18.2.0
│       └── ❌ Wants React 18!
│
└── Package C (old-package)
    └── Has dependency: React 17.0.2
        └── ❌ Actually installs React 17!

Without Overrides:

npm install

# Result:
node_modules/
├── react@19.0.0                    # Your version
├── some-ui-lib/
│   └── node_modules/
│       └── react@18.2.0           # Different version!
└── old-package/
    └── node_modules/
        └── react@17.0.2           # Another version!

# You now have THREE versions of React! 💥

Problems This Causes:

• ❌ Multiple React instances = Hooks break
• ❌ Massive bundle size (3 copies of React)
• ❌ "Invalid Hook Call" errors
• ❌ State management breaks
• ❌ Context doesn't work across packages

With Overrides:

{
  "overrides": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

npm install

# Result:
node_modules/
├── react@19.0.0                    # Your version
├── some-ui-lib/                    # Uses React 19 ✅
└── old-package/                    # Uses React 19 ✅

# Only ONE version of React! ✅

🎯 Is It a "Patch" or "Workaround"?

❌ NO - It's a Legitimate Feature

Overrides are NOT:

• ❌ A hack or workaround
• ❌ A temporary fix
• ❌ A sign of poor dependency management
• ❌ Something to avoid

Overrides ARE:

• ✅ An official npm feature (since npm 8.3.0)
• ✅ A solution to real-world dependency conflicts
• ✅ Used by major projects (Next.js, Create React App, etc.)
• ✅ The recommended way to handle version conflicts
• ✅ A way to enforce consistent dependencies

Comparison: Overrides vs Other Solutions

📚 Real-World Use Cases

Use Case 1: React 19 Migration (Your Case)

Problem:

You: Upgrading to React 19
Your dependencies: Still list React 18 in peerDependencies

Without Overrides:

npm install
npm WARN @fullcalendar/react@6.1.15 requires a peer of react@^16.8.0 || ^17.0.0 || ^18.0.0
npm WARN some-lib@1.2.3 requires a peer of react@^18.0.0

# npm might install React 18 for some packages
# You get multiple React versions

With Overrides:

{
  "overrides": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

npm install
# All packages forced to use React 19 ✅
# Single React version across entire project ✅

Result: Clean, working React 19 project

Use Case 2: Security Vulnerability Fix

Problem:

Security alert: lodash@4.17.19 has critical vulnerability
Your dependencies use various lodash versions:
- package-a uses lodash@4.17.19 (vulnerable)
- package-b uses lodash@4.17.20 (vulnerable)
- package-c uses lodash@4.17.21 (safe)

Solution:

{
  "overrides": {
    "lodash": "^4.17.21"  // Force everyone to use safe version
  }
}

Result: ALL packages use the patched version, security hole closed

Use Case 3: Dependency Version Conflicts

Problem:

package-a wants axios@0.21.0
package-b wants axios@0.27.0
package-c wants axios@1.4.0

All are incompatible with each other!

Solution:

{
  "overrides": {
    "axios": "^1.6.0"  // Force latest compatible version
  }
}

Result: Single axios version, no conflicts

Use Case 4: Transitive Dependency Issues

Problem:

Your dependency tree:
You -> package-a -> package-b -> old-library -> react@16.0.0

You can't control what package-b uses!

Solution:

{
  "overrides": {
    "old-library": {
      "react": "^19.0.0"  // Force old-library to use React 19
    }
  }
}

Result: Control dependencies several levels deep

Use Case 5: Testing with Specific Versions

Problem:

You want to test if your app works with a beta version:
React 19.1.0-beta.1

Solution:

{
  "overrides": {
    "react": "19.1.0-beta.1",
    "react-dom": "19.1.0-beta.1"
  }
}

Result: Entire project uses beta version for testing

🛠️ Advanced Override Patterns

Pattern 1: Selective Overrides (Target Specific Packages)

{
  "overrides": {
    // Only override React for @fullcalendar packages
    "@fullcalendar/*": {
      "react": "^19.0.0"
    },
    
    // Different override for other packages
    "some-ui-lib": {
      "react": "^19.0.0"
    }
  }
}

Pattern 2: Deep Dependency Overrides

{
  "overrides": {
    // Override a dependency of a dependency
    "package-a": {
      "package-b": {
        "vulnerable-lib": "^2.0.0"
      }
    }
  }
}

Pattern 3: Multiple Overrides

{
  "overrides": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "typescript": "^5.7.0",
    "lodash": "^4.17.21",
    "axios": "^1.6.0"
  }
}

⚠️ Potential Risks & How to Mitigate

Risk 1: Breaking Changes

Problem: Forcing a package to use a newer dependency version it wasn't tested with

Example:

{
  "overrides": {
    "react": "^19.0.0"  // But some-old-lib only works with React 16
  }
}

Mitigation:

• ✅ Test thoroughly after applying overrides
• ✅ Check package compatibility first
• ✅ Monitor error logs
• ✅ Have rollback plan

Risk 2: Unexpected Behavior

Problem: Package might rely on specific behavior in old version

Mitigation:

• ✅ Read package changelogs
• ✅ Test critical functionality
• ✅ Use semantic versioning wisely (^19.0.0 vs 19.0.0)

Risk 3: Future Updates

Problem: When package updates to officially support new version, your override might conflict

Mitigation:

• ✅ Regularly review and remove unnecessary overrides
• ✅ Document why each override exists
• ✅ Check release notes when updating packages

📊 When to Use vs When NOT to Use

✅ USE Overrides When:

1. Upgrading major versions (like React 18 -> 19)

   • Dependencies haven't updated peerDependencies yet
   • You've tested and know it works

2. Security vulnerabilities

   • Transitive dependency has security issue
   • Direct dependency not yet updated

3. Dependency conflicts

   • Multiple packages want different versions
   • You know specific version works for all

4. Bundle size optimization

   • Reduce duplicate dependencies
   • Force single version across tree

5. Testing bleeding edge

   • Testing beta/alpha versions
   • Temporary for development

❌ DON'T Use Overrides When:

1. You don't understand the implications

   • Research first, override second

2. Package explicitly requires specific version

   • Check package docs
   • Might break functionality

3. As first solution

   • Try updating packages first
   • Check if official support exists

4. Without testing

   • Always test before production
   • Overrides can hide real incompatibilities

🔍 How to Verify Overrides Work

Check Installed Versions:

# See what's actually installed
npm list react

# Should show single version:
└── react@19.0.0  ✅

Check for Duplicates:

# Find duplicate packages
npm dedupe

# List all instances
npm list react --all

Verify Bundle:

# Build and check bundle
npm run build

# Check bundle size
# Should be smaller without duplicates

Test Application:

# Run your app
npm start

# Check console for errors
# Look for "Invalid Hook Call" or version mismatch errors

📝 Your Specific Case: React 19

Your Override:

{
  "overrides": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

What It Does:

Before Override:

node_modules/
├── react@19.0.0 (your install)
├── @fullcalendar/react/
│   └── node_modules/
│       └── react@18.2.0 (its own copy)
└── @react-google-maps/api/
    └── node_modules/
        └── react@18.3.1 (its own copy)

Bundle size: ~500kb (3 copies of React)
Runtime: Broken (multiple React instances)

After Override:

node_modules/
├── react@19.0.0 (single copy)
├── @fullcalendar/react/ (uses react@19.0.0)
└── @react-google-maps/api/ (uses react@19.0.0)

Bundle size: ~200kb (1 copy of React)
Runtime: Works (single React instance)

Is This Safe for Your Project?

✅ YES, because:

1. React 19 is backward compatible with React 18/17 APIs
2. Your dependencies (FullCalendar, Google Maps) don't use removed APIs
3. You'll test before production
4. It's the recommended approach for React 19 migration

⚠️ BUT you must:

1. Test all components thoroughly
2. Check for console warnings
3. Verify FullCalendar works
4. Verify Google Maps works
5. Monitor production for issues

🎓 Industry Best Practices

What Major Projects Do:

Next.js:

{
  "overrides": {
    "react": "19.0.0-rc-...",
    "react-dom": "19.0.0-rc-..."
  }
}

Create React App (CRA): Uses overrides for React version management

Material-UI: Documents using overrides for peer dependency issues

Vercel: Recommends overrides for React 19 adoption

✅ Conclusion: Should You Use Overrides?

For Your React 19 Migration:

YES - Use overrides! ✅

Reasons:

1. ✅ It's the official way to handle this
2. ✅ React 19 is compatible with React 18 code
3. ✅ Prevents multiple React instances
4. ✅ Reduces bundle size
5. ✅ Industry standard practice
6. ✅ Recommended by React team

It's NOT a "patch" - it's the RIGHT solution!

Final Verdict:

{
  "overrides": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

This is:

• ✅ Professional
• ✅ Standard practice
• ✅ Safe (with testing)
• ✅ Recommended
• ✅ Production-ready

Not a workaround, but a feature designed exactly for this use case! 🎯

📚 Further Reading

• npm overrides documentation
• React 19 Migration Guide
• Dependency Resolution in npm

Summary

NPM overrides are a powerful and legitimate tool for managing dependency versions across your entire project. They solve real-world problems like multiple React instances, security vulnerabilities in transitive dependencies, and version conflicts. When used appropriately with proper testing, overrides are the industry-standard solution for forcing version consistency across your dependency tree.

Piano Analytics + HubSpot Integration Project

Pre-Development Discovery Questions

📋 Purpose of This Document

This questionnaire will help us:

• ✅ Define exact project scope
• ✅ Identify all requirements upfront
• ✅ Prevent scope creep and disputes
• ✅ Provide accurate estimates
• ✅ Set clear expectations
• ✅ Define deliverables precisely

Important: Please answer all questions. "I don't know" or "To be decided" are valid answers, but they affect timeline and cost.

Section 1: Piano Integration - Current State

1.1 Existing Piano Setup

Q1.1: What Piano product(s) are you currently using?

• [ ] Piano ID (Identity/Authentication)
• [ ] Piano Analytics (Web Analytics)
• [ ] Piano Composer (Experience Engine/Paywall)
• [ ] Piano Activation (Subscription Management)
• [ ] Piano Amp (CRM/Marketing)
• [ ] Other: ___________________
• [ ] Don't know - need to confirm

Q1.2: Is Piano already integrated in your existing application?

• [ ] Yes, fully functional
• [ ] Yes, partially working
• [ ] Yes, but needs fixes
• [ ] No, needs to be integrated from scratch
• [ ] Don't know

Q1.3: If already integrated, what is the current integration method?

• [ ] Iframe
• [ ] JavaScript SDK
• [ ] Server-side API
• [ ] Third-party plugin
• [ ] Custom implementation
• [ ] Don't know

Q1.4: Can you provide access to:

• [ ] Piano dashboard/admin panel
• [ ] Piano API credentials (read-only for review)
• [ ] Existing Piano integration code
• [ ] Piano integration documentation you received
• [ ] Piano support contact (if available)

Q1.5: What is the Piano iframe URL currently being used?

Answer: _________________________________

Q1.6: Does the Piano iframe currently work correctly?

• [ ] Yes, works perfectly
• [ ] Works but has issues (describe): _______________
• [ ] Doesn't work
• [ ] Haven't tested
• [ ] Don't know

Section 2: Piano Integration - Required Functionality

2.1 Authentication Requirements

Q2.1: What authentication flows need to be supported?

• [ ] User Login
• [ ] User Signup/Registration
• [ ] Social Login (Google, Facebook, etc.)
• [ ] Password Reset
• [ ] Email Verification
• [ ] Two-Factor Authentication (2FA)
• [ ] Remember Me functionality
• [ ] Single Sign-On (SSO)
• [ ] Other: ___________________

Q2.2: What user information needs to be collected during signup?

• [ ] Email (required)
• [ ] Password (required)
• [ ] First Name
• [ ] Last Name
• [ ] Phone Number
• [ ] Company Name
• [ ] Job Title
• [ ] Country/Region
• [ ] Custom fields: ___________________

Q2.3: After successful login, where should users be redirected?

Answer: _________________________________
Example: /dashboard, /home, /profile, etc.

Q2.4: What should happen after logout?

• [ ] Redirect to login page
• [ ] Redirect to homepage
• [ ] Show logout confirmation
• [ ] Clear all user data
• [ ] Other: ___________________

Q2.5: Do you need "Remember Me" functionality?

• [ ] Yes
• [ ] No
• [ ] Not sure

Q2.6: Session timeout requirements:

Session should expire after: _____ minutes of inactivity
OR
[ ] No automatic timeout
[ ] Don't know - use best practice

Q2.7: Do you need password strength requirements?

• [ ] Yes (specify): ___________________
• [ ] No
• [ ] Use Piano's default

Q2.8: Email verification required?

• [ ] Yes, users must verify email before login
• [ ] Yes, but users can login before verification
• [ ] No verification needed
• [ ] Don't know

2.2 User Data & Profile Management

Q2.9: Do users need to be able to:

• [ ] View their profile
• [ ] Edit their profile
• [ ] Delete their account
• [ ] Change password
• [ ] Update email
• [ ] Upload profile picture
• [ ] None of the above

Q2.10: Should user data from Piano sync to your backend database?

• [ ] Yes, immediately after login/signup
• [ ] Yes, periodically (how often: _______)
• [ ] No, use Piano as source of truth
• [ ] Don't know

Q2.11: Where should user data be stored?

• [ ] Piano only
• [ ] Your backend database only
• [ ] Both Piano and backend (synced)
• [ ] Don't know - recommend best practice

2.3 Advanced Piano Features

Q2.12: Do you need Piano paywall/subscription features?

• [ ] Yes, users need to subscribe/pay
• [ ] No, free access only
• [ ] Maybe in future
• [ ] Don't know

Q2.13: If subscriptions are needed, what payment providers?

• [ ] Stripe
• [ ] PayPal
• [ ] Piano handles payment
• [ ] Other: ___________________
• [ ] Not applicable

Q2.14: Do you need Piano's analytics tracking?

• [ ] Yes, track user behavior
• [ ] Yes, track content access
• [ ] Yes, track conversions
• [ ] No analytics needed
• [ ] Don't know

Q2.15: Do you need Piano's A/B testing capabilities?

• [ ] Yes
• [ ] No
• [ ] Maybe in future
• [ ] Don't know what this is

Section 3: HubSpot Integration

3.1 HubSpot Current State

Q3.1: Is HubSpot already integrated in your application?

• [ ] Yes, fully working
• [ ] Yes, partially working
• [ ] Yes, but broken
• [ ] No, needs to be integrated
• [ ] Don't know

Q3.2: What HubSpot products are you using?

• [ ] HubSpot Marketing Hub (Free/Starter/Professional/Enterprise)
• [ ] HubSpot Sales Hub
• [ ] HubSpot Service Hub
• [ ] HubSpot CMS
• [ ] HubSpot Operations Hub
• [ ] Don't know

Q3.3: Can you provide access to:

• [ ] HubSpot portal/dashboard
• [ ] HubSpot Portal ID
• [ ] HubSpot API key (for backend)
• [ ] HubSpot tracking code
• [ ] Existing HubSpot integration code (if any)

Q3.4: What is your HubSpot Portal ID?

Portal ID: _________________________________
(Found in HubSpot Settings > Account & Billing)

3.2 HubSpot Data Requirements

Q3.5: What user data should be sent to HubSpot after Piano login/signup?

• [ ] Email
• [ ] First Name
• [ ] Last Name
• [ ] Phone
• [ ] Company
• [ ] Job Title
• [ ] Piano User ID
• [ ] Signup Date
• [ ] Subscription Status
• [ ] Custom properties: ___________________

Q3.6: When should user data be sent to HubSpot?

• [ ] Immediately after signup
• [ ] Immediately after login
• [ ] After email verification
• [ ] Only after first purchase/subscription
• [ ] Other: ___________________

Q3.7: What events should be tracked in HubSpot?

• [ ] User Signup
• [ ] User Login
• [ ] User Logout
• [ ] Profile Update
• [ ] Password Reset
• [ ] Content Access
• [ ] Subscription Created
• [ ] Payment Completed
• [ ] Page Views
• [ ] Custom events: ___________________

Q3.8: Do you have custom HubSpot properties already created?

• [ ] Yes (provide list): ___________________
• [ ] No, need to create them
• [ ] Don't know

Q3.9: Should existing contacts in HubSpot be updated when they login?

• [ ] Yes, update every login
• [ ] Yes, but only certain fields
• [ ] No, don't update existing contacts
• [ ] Don't know

Q3.10: Do you need HubSpot forms embedded in the application?

• [ ] Yes (for what: ___________________)
• [ ] No
• [ ] Don't know

3.3 HubSpot Workflows & Automation

Q3.11: Do you have HubSpot workflows that trigger based on user actions?

• [ ] Yes (describe): ___________________
• [ ] No
• [ ] Plan to create them
• [ ] Don't know

Q3.12: Should certain actions trigger HubSpot emails?

• [ ] Yes, welcome email after signup
• [ ] Yes, verification email
• [ ] Yes, password reset email
• [ ] Yes, other: ___________________
• [ ] No, emails handled elsewhere
• [ ] Don't know

Q3.13: Do you need email marketing features?

• [ ] Yes, users can subscribe to newsletter
• [ ] Yes, users can manage email preferences
• [ ] No
• [ ] Don't know

Section 4: Piano + HubSpot Synchronization

Q4.1: Should Piano and HubSpot data stay in sync?

• [ ] Yes, real-time sync
• [ ] Yes, sync every X minutes: _____
• [ ] Yes, sync once daily
• [ ] No sync needed
• [ ] Don't know

Q4.2: If Piano user data changes, should it update HubSpot?

• [ ] Yes, automatically
• [ ] Yes, but only certain fields
• [ ] No
• [ ] Don't know

Q4.3: If HubSpot contact data changes, should it update Piano?

• [ ] Yes, automatically
• [ ] Yes, but only certain fields
• [ ] No
• [ ] Don't know

Q4.4: What happens if sync fails?

• [ ] Retry automatically
• [ ] Log error and alert admin
• [ ] Show error to user
• [ ] Other: ___________________
• [ ] Don't know - recommend best practice

Section 5: Existing Application Details

5.1 Technology Stack

Q5.1: What is your frontend technology?

• [ ] React.js (version: _____)
• [ ] Next.js
• [ ] Vue.js
• [ ] Angular
• [ ] Plain JavaScript/HTML
• [ ] Other: ___________________

Q5.2: What is your backend technology?

• [ ] Node.js (Express/Nest.js/Other: _____)
• [ ] Python (Django/Flask/FastAPI/Other: _____)
• [ ] PHP (Laravel/Symfony/Other: _____)
• [ ] Java (Spring/Other: _____)
• [ ] .NET/C#
• [ ] Ruby on Rails
• [ ] Other: ___________________
• [ ] No backend (frontend only)

Q5.3: What database are you using?

• [ ] PostgreSQL
• [ ] MySQL
• [ ] MongoDB
• [ ] Firebase
• [ ] Other: ___________________
• [ ] None

Q5.4: Do you have a user authentication system already?

• [ ] Yes, fully functional (technology: _______)
• [ ] Yes, but replacing with Piano
• [ ] Yes, and Piano will be additional option
• [ ] No, Piano will be the first auth system

Q5.5: State management library (if React/Vue):

• [ ] Redux
• [ ] Context API
• [ ] MobX
• [ ] Zustand
• [ ] None
• [ ] Other: ___________________

5.2 Access & Environment

Q5.6: Can you provide access to:

• [ ] Source code repository (GitHub/GitLab/Bitbucket)
• [ ] Development environment
• [ ] Staging environment
• [ ] Production environment (read-only)
• [ ] API documentation
• [ ] Database schema

Q5.7: Do you have separate environments?

• [ ] Development
• [ ] Staging/QA
• [ ] Production
• [ ] Only production

Q5.8: Where is the application hosted?

• [ ] AWS
• [ ] Google Cloud
• [ ] Azure
• [ ] Vercel
• [ ] Netlify
• [ ] Heroku
• [ ] Other: ___________________
• [ ] On-premise servers

Q5.9: Who will handle deployment?

• [ ] Your team
• [ ] Our team (us - the developers)
• [ ] DevOps/Third party
• [ ] Don't know yet

Section 6: Security & Compliance

Q6.1: Do you need to comply with data protection regulations?

• [ ] GDPR (Europe)
• [ ] CCPA (California)
• [ ] HIPAA (Healthcare)
• [ ] Other: ___________________
• [ ] Not sure
• [ ] No specific requirements

Q6.2: Do you need cookie consent management?

• [ ] Yes, for GDPR compliance
• [ ] Yes, for other reasons
• [ ] No
• [ ] Not sure

Q6.3: What data privacy features are needed?

• [ ] Cookie consent banner
• [ ] Privacy policy link
• [ ] Terms of service acceptance
• [ ] Right to deletion (delete account)
• [ ] Data export (download user data)
• [ ] Opt-out of tracking
• [ ] Other: ___________________

Q6.4: Do you have existing security requirements?

• [ ] SSL/HTTPS only
• [ ] Two-factor authentication
• [ ] Password complexity rules
• [ ] Session encryption
• [ ] IP whitelisting
• [ ] Rate limiting
• [ ] Other: ___________________

Q6.5: Are there any compliance audits or certifications needed?

• [ ] SOC 2
• [ ] ISO 27001
• [ ] PCI DSS (if handling payments)
• [ ] Other: ___________________
• [ ] No

Q6.6: Do you need security penetration testing?

• [ ] Yes, by our team
• [ ] Yes, by third party
• [ ] No
• [ ] Don't know

Section 7: User Experience & Design

Q7.1: Do you have design mockups/wireframes for:

• [ ] Login page
• [ ] Signup page
• [ ] Profile page
• [ ] Password reset flow
• [ ] Loading states
• [ ] Error states
• [ ] None - we need designs created

Q7.2: Should the Piano iframe match your application's design?

• [ ] Yes, must look seamless (provide brand guidelines)
• [ ] Yes, basic matching
• [ ] No, Piano's default design is fine
• [ ] Not sure if this is possible

Q7.3: Do you have brand guidelines to follow?

• [ ] Yes (can provide)
• [ ] No

Q7.4: What should happen during loading?

• [ ] Show loading spinner
• [ ] Show skeleton UI
• [ ] Show custom animation
• [ ] Nothing special
• [ ] Other: ___________________

Q7.5: How should errors be displayed?

• [ ] Inline error messages
• [ ] Toast/notification messages
• [ ] Modal popups
• [ ] Dedicated error page
• [ ] Other: ___________________

Q7.6: Mobile responsiveness required?

• [ ] Yes, must work on all devices
• [ ] Desktop only
• [ ] Don't know

Q7.7: Accessibility requirements (WCAG)?

• [ ] WCAG 2.1 Level A
• [ ] WCAG 2.1 Level AA
• [ ] WCAG 2.1 Level AAA
• [ ] No specific requirements
• [ ] Don't know what this means

Section 8: Testing & Quality Assurance

Q8.1: What level of testing is required?

• [ ] Unit tests
• [ ] Integration tests
• [ ] End-to-end tests
• [ ] Manual testing only
• [ ] No testing required (not recommended)

Q8.2: What browsers must be supported?

• [ ] Chrome (latest)
• [ ] Firefox (latest)
• [ ] Safari (latest)
• [ ] Edge (latest)
• [ ] Internet Explorer 11 (legacy)
• [ ] Mobile browsers (iOS Safari, Chrome Mobile)
• [ ] All modern browsers

Q8.3: Who will perform QA testing?

• [ ] Your QA team
• [ ] Our team
• [ ] Third party
• [ ] No formal QA

Q8.4: Do you need a testing environment?

• [ ] Yes, separate staging server
• [ ] Yes, can use production with test accounts
• [ ] No

Q8.5: What is your User Acceptance Testing (UAT) process?

Describe: _________________________________
OR
[ ] No formal UAT process

Section 9: Documentation & Training

Q9.1: What documentation do you need?

• [ ] Technical documentation for developers
• [ ] API documentation
• [ ] User guide/manual
• [ ] Admin guide
• [ ] Deployment guide
• [ ] Troubleshooting guide
• [ ] Code comments only
• [ ] No documentation needed

Q9.2: Do you need training for your team?

• [ ] Yes, for developers
• [ ] Yes, for admins
• [ ] Yes, for end users
• [ ] No training needed

Q9.3: Documentation format preference:

• [ ] Markdown files
• [ ] PDF documents
• [ ] Video tutorials
• [ ] Wiki/Confluence
• [ ] In-code comments only
• [ ] No preference

Section 10: Project Scope & Timeline

Q10.1: What is NOT included in this project? (Out of scope)

List features/tasks that are explicitly NOT part of this project:
_________________________________
_________________________________
_________________________________

Q10.2: What features are "Must Have" (cannot launch without)?

List critical features:
1. _________________________________
2. _________________________________
3. _________________________________

Q10.3: What features are "Nice to Have" (can be added later)?

List optional features:
1. _________________________________
2. _________________________________
3. _________________________________

Q10.4: When do you need this project completed?

Target deadline: _________________________________
Is this deadline flexible? [ ] Yes [ ] No

Q10.5: Are there any hard deadlines we must meet?

Example: Product launch date, compliance deadline, etc.
_________________________________

Q10.6: How many developers will work on this from your side?

• [ ] 0 (only external team)
• [ ] 1 developer
• [ ] 2-3 developers
• [ ] More than 3
• [ ] Don't know yet

Section 11: Support & Maintenance

Q11.1: After launch, who will maintain the integration?

• [ ] Your in-house team
• [ ] Our team (ongoing contract)
• [ ] Third party
• [ ] To be decided

Q11.2: Do you need post-launch support?

• [ ] Yes, X months: _____
• [ ] Yes, ongoing monthly retainer
• [ ] No, handoff after completion
• [ ] To be decided

Q11.3: Do you need monitoring/alerting setup?

• [ ] Yes, for errors
• [ ] Yes, for performance
• [ ] Yes, for security
• [ ] No
• [ ] Don't know

Q11.4: How should critical issues be handled post-launch?

Contact method: _________________________________
Response time expectation: _________________________________

Section 12: Budget & Priorities

Q12.1: What is your budget for this project?

• [ ] Fixed budget: $_____
• [ ] Hourly rate: $_____ (max hours: _____)
• [ ] Flexible, need estimate
• [ ] Prefer not to disclose

Q12.2: What is more important to you? Rank 1-3 (1=most important):

• [ ] Cost (staying within budget)
• [ ] Speed (fast delivery)
• [ ] Quality (best practices, testing, security)

Q12.3: If we exceed the timeline, would you prefer:

• [ ] Extend deadline to maintain quality
• [ ] Reduce scope to meet deadline
• [ ] Increase budget for more resources
• [ ] To be decided when needed

Q12.4: Are there any cost constraints we should know about?

Answer: _________________________________

Section 13: Communication & Workflow

Q13.1: How often do you want progress updates?

• [ ] Daily
• [ ] Every 2-3 days
• [ ] Weekly
• [ ] Bi-weekly
• [ ] Only at milestones

Q13.2: Preferred communication channel:

• [ ] Email
• [ ] Slack
• [ ] Microsoft Teams
• [ ] Phone calls
• [ ] Video meetings
• [ ] Project management tool: ___________________

Q13.3: Who is the primary point of contact?

Name: _________________________________
Role: _________________________________
Email: _________________________________
Availability: _________________________________

Q13.4: Who are the decision makers for:

Technical decisions: _________________________________
Design decisions: _________________________________
Budget decisions: _________________________________
Timeline decisions: _________________________________

Q13.5: How should we handle change requests during development?

• [ ] Pause work and re-estimate
• [ ] Document and handle after initial scope
• [ ] Add to backlog for Phase 2
• [ ] Discuss case-by-case
• [ ] Other: ___________________

Q13.6: Do you use project management tools?

• [ ] Jira
• [ ] Asana
• [ ] Trello
• [ ] Monday.com
• [ ] GitHub Projects
• [ ] Other: ___________________
• [ ] No, prefer email/Slack

Section 14: Risks & Constraints

Q14.1: Are there any technical constraints we should know about?

Examples: Legacy code, old frameworks, specific libraries to use, etc.
_________________________________

Q14.2: Are there any business constraints?

Examples: Seasonal traffic, upcoming campaigns, regulatory deadlines, etc.
_________________________________

Q14.3: What are the biggest risks you see for this project?

Your concerns:
1. _________________________________
2. _________________________________
3. _________________________________

Q14.4: Have you had similar integration projects before?

• [ ] Yes, successful
• [ ] Yes, had issues (describe): ___________________
• [ ] No, first time

Q14.5: Is there anything else we should know?

Any other important information:
_________________________________
_________________________________
_________________________________

Section 15: Sign-Off & Agreement

Q15.1: Who needs to approve:

Technical specifications: _________________________________
Design mockups: _________________________________
Final deliverable: _________________________________

Q15.2: What defines "project completion"?

• [ ] All features working on production
• [ ] Successful UAT
• [ ] Passed security audit
• [ ] Documentation delivered
• [ ] Training completed
• [ ] X weeks of stable operation
• [ ] Other: ___________________

Q15.3: How will we handle disagreements about requirements?

• [ ] Client has final say
• [ ] Developer recommends, client decides
• [ ] Escalate to project manager
• [ ] Other: ___________________

📝 Next Steps After Completing This Questionnaire

1. Review Answers Together

   • Schedule call to discuss answers
   • Clarify any unclear responses
   • Identify gaps in requirements

2. Create Detailed Specification Document

   • Based on your answers
   • With technical architecture
   • Including timeline and cost estimate

3. Define Statement of Work (SOW)

   • Clear deliverables
   • Timeline with milestones
   • Payment terms
   • Change request process

4. Get Written Approval

   • Sign-off on specifications
   • Agree on timeline
   • Approve budget

5. Begin Development

   • With clear scope
   • No surprises
   • Regular communication

⚠️ Important Notes

1. "I don't know" is a valid answer - We'll help you figure it out, but it may affect timeline/cost
2. Be specific - Vague answers like "make it work" or "the usual" can lead to misunderstandings
3. Think about the future - Consider what might be needed in 6-12 months
4. Prioritize ruthlessly - Not everything can be "high priority"
5. Budget reality - More features = more time = higher cost

Document Prepared By: _________________________________
Date: _________________________________
Client Name: _________________________________
Project Name: Piano + HubSpot Integration

📧 Submission

Please complete this questionnaire and send to:

• Email: your-email@company.com
• Deadline: _________________________________

If you have questions while filling this out, contact:

• Name: _________________________________
• Email: _________________________________
• Phone: _________________________________

Thank you for your time in completing this questionnaire!
This will ensure a smooth, successful project with no surprises.

This checklist helps teams evaluate whether Graph Commerce is the right fit and what needs to be validated before committing to a headless build. Use it to surface risks early, align stakeholders, and avoid costly rework.

1. Technical Infrastructure & Setup

Hosting & Deployment

• What hosting infrastructure will support Graph Commerce (Vercel, AWS, Google Cloud)?
• Do we have experience with serverless/edge deployments?
• What's our budget for hosting costs (Next.js can be expensive at scale)?
• How will we handle image optimization and CDN costs?
• Do we need multi-region deployment for performance?

Development Environment

• What Node.js version are we standardizing on (Graph Commerce requires 18+)?
• Which package manager (pnpm, yarn, npm) - Graph Commerce recommends pnpm?
• Do all developers have sufficient local machine resources (8GB+ RAM minimum)?
• How will we handle long build times during development?
• What's our strategy for managing .env files across teams?

2. Magento 2 Backend Integration

Magento Setup & Compatibility

• Which Magento 2 version are we running (Graph Commerce requires 2.4.3+)?
• Is our Magento instance optimized for GraphQL queries?
• Have we enabled all required Magento 2 GraphQL modules?
• Are there custom Magento extensions that might break GraphQL compatibility?
• How will we handle Magento GraphQL rate limiting?

Custom Magento Development

• Do we have custom product types that need frontend representation?
• Are there custom customer attributes that need to be surfaced?
• How many custom GraphQL resolvers/mutations do we have?
• Will we need to extend Magento's GraphQL schema significantly?
• Who maintains the Magento backend vs. the Graph Commerce frontend?

API Performance

• What's the average response time of our Magento GraphQL endpoint?
• How will we handle slow Magento responses (caching, SWR, fallbacks)?
• Do we need GraphQL query optimization/batching?
• What's our strategy for handling Magento API downtime?

3. Team Skills & Learning Curve

Current Team Expertise

• Does the team have experience with Next.js App Router and React Server Components?
• Are developers comfortable with GraphQL (queries, fragments, mutations)?
• Do we understand TypeScript at an intermediate/advanced level?
• Has anyone worked with monorepo architectures before?
• Do we have frontend performance optimization expertise?

Learning & Training

• How much time can we allocate for the team to learn Graph Commerce?
• Who will become the Graph Commerce "expert" on the team?
• What's our plan for knowledge transfer and documentation?
• Do we have budget for external Graph Commerce consultants if needed?
• How will we stay updated with Graph Commerce releases and breaking changes?

4. Customization & Extensibility

Design & Theming

• How much will our design deviate from Graph Commerce defaults?
• Do we need to completely override the Material-UI theme?
• Are we comfortable with Emotion CSS-in-JS or prefer other solutions?
• How will we manage design tokens and brand consistency?
• Do we need multiple themes (B2B, B2C, white-label)?

Plugin System

• Do we understand Graph Commerce's plugin architecture?
• How many custom plugins will we need to create?
• Will we need to override core Graph Commerce components significantly?
• What's our strategy for maintaining plugins across Graph Commerce updates?
• How will we test custom plugins in isolation?

Third-Party Integrations

• What payment gateways need integration (beyond Magento's defaults)?
• Do we need custom shipping calculators or methods?
• Are there specific analytics/tracking tools to integrate (GA4, GTM, Segment)?
• Do we need integration with PIM, ERP, or CRM systems?
• What's our strategy for managing third-party service API keys?

5. Performance & Scalability

Performance Requirements

• What are our target Core Web Vitals scores (LCP, FID, CLS)?
• How will we handle large product catalogs (10k+ SKUs)?
• What's our strategy for image optimization at scale?
• Do we need server-side caching (Redis, Varnish)?
• How will we optimize for mobile performance on slow networks?

Traffic & Load

• What's our expected traffic volume (concurrent users)?
• Do we have seasonal traffic spikes (Black Friday, holidays)?
• How will we load test Graph Commerce before launch?
• What's our auto-scaling strategy?
• Do we need a CDN strategy for static assets?

6. Data & State Management

GraphQL Data Fetching

• How will we handle data fetching patterns (SSR, SSG, ISR, CSR)?
• What's our caching strategy for GraphQL responses?
• Do we need optimistic UI updates for better UX?
• How will we handle stale data and revalidation?
• What's our approach to pagination and infinite scroll?

Client-Side State

• Which pages need client-side state management?
• Do we need a global state solution beyond React Context?
• How will we handle cart state synchronization with Magento?
• What's our strategy for persisting user preferences?
• How will we handle authentication state and token management?

7. SEO & Content Management

SEO Requirements

• Do we need multi-language/multi-region SEO?
• How will we handle dynamic metadata for products/categories?
• What's our strategy for structured data (Schema.org)?
• Do we need XML sitemaps generation?
• How will we manage canonical URLs and redirects?

Content Strategy

• Will we use Magento CMS or an external headless CMS (Contentful, Sanity)?
• How will we manage landing pages and marketing content?
• Do we need A/B testing capabilities?
• What's our content preview/staging strategy?
• How will non-technical users manage content?

8. Testing & Quality Assurance

Testing Strategy

• What's our testing pyramid (unit, integration, E2E)?
• Which testing frameworks (Jest, React Testing Library, Playwright)?
• How will we test GraphQL integrations?
• Do we need visual regression testing?
• What's our cross-browser/device testing strategy?

Quality Gates

• What code coverage percentage is required?
• How will we enforce code quality (ESLint, Prettier, TypeScript strict mode)?
• What's our code review process?
• Do we need automated accessibility testing (WCAG compliance)?
• How will we monitor bundle size and performance budgets?

9. Security & Compliance

Security Concerns

• How will we handle PCI compliance for payment data?
• What's our strategy for protecting customer PII?
• How will we prevent XSS, CSRF, and other vulnerabilities?
• Do we need rate limiting on the frontend?
• How will we handle security headers and CSP?

Data Privacy

• Do we need GDPR compliance features?
• How will we handle cookie consent management?
• What's our data retention policy?
• Do we need customer data export/deletion features?
• How will we handle third-party tracking compliance?

10. Maintenance & Long-term Support

Update Strategy

• How frequently can we update Graph Commerce versions?
• What's our process for handling breaking changes?
• Do we have a staging environment for testing updates?
• How will we handle dependency security vulnerabilities?
• What's our rollback strategy if updates fail?

Monitoring & Debugging

• What monitoring tools will we use (Sentry, LogRocket, Datadog)?
• How will we track frontend errors in production?
• What's our alerting strategy for critical issues?
• How will we debug issues reported by customers?
• Do we need real user monitoring (RUM)?

Documentation

• Who will maintain technical documentation?
• How will we document custom implementations?
• What's our process for onboarding new developers?
• Do we need architecture decision records (ADRs)?
• How will we document GraphQL schema changes?

11. Budget & Timeline

Cost Considerations

• What's the total estimated development cost?
• What are ongoing operational costs (hosting, CDN, monitoring)?
• Do we need to budget for Graph Commerce support/consulting?
• What's the cost of third-party services (CMS, analytics, etc.)?
• Are there license costs for any tools or services?

Project Timeline

• What's our realistic timeline for MVP launch?
• How much time for initial setup and configuration?
• What's the migration strategy if replacing an existing frontend?
• Do we have buffer time for unexpected challenges?
• What's our phased rollout plan?

12. Business Requirements

Feature Parity

• Which existing features are must-haves for launch?
• What features can be deferred to post-launch?
• Do we need B2B features (company accounts, quote management)?
• Are there specific localization requirements?
• What customer account features are essential?

Success Metrics

• How will we measure success (conversion rate, page speed, etc.)?
• What KPIs are we optimizing for?
• How will we compare against the current solution?
• What's our A/B testing strategy post-launch?
• How will we gather and act on user feedback?

13. Risk Assessment

Technical Risks

• What happens if Graph Commerce development stalls or is abandoned?
• How dependent are we on Graph Commerce's roadmap?
• What's our contingency if we can't solve a critical limitation?
• How will we handle major Next.js breaking changes?
• What if Magento GraphQL has breaking changes?

Business Risks

• What's the impact if launch is delayed by 3-6 months?
• How will we handle competitive pressure during development?
• What if key team members leave during the project?
• Do we have stakeholder buy-in for the learning curve?
• What's the fallback if Graph Commerce doesn't meet needs?

14. Vendor Lock-in & Exit Strategy

Platform Independence

• How tightly coupled will we be to Graph Commerce?
• Can we migrate to another framework if needed?
• What components are reusable outside Graph Commerce?
• How will we avoid vendor lock-in with hosting providers?
• What's our strategy if we need to switch commerce backends?

Priority Questions to Ask First

Before diving deep, answer these critical questions:

1. Do we have a clear business case for using Graph Commerce vs. alternatives?
2. Does our team have the technical skills, or can we acquire them quickly?
3. Is our Magento instance ready and optimized for headless commerce?
4. Do we have realistic timeline and budget expectations?
5. Are we prepared for the ongoing maintenance burden of a complex stack?

Red Flags to Watch For

• Team has no Next.js or React Server Components experience
• Magento instance is heavily customized with old extensions
• Expecting plug-and-play solution with zero customization
• Unrealistic timeline (less than 3 months for complex implementations)
• No plan for handling Graph Commerce updates
• Unclear ownership between backend and frontend teams
• No performance monitoring strategy
• Assuming AI tools will handle most of the development

Server and domain migrations are common in modern infrastructure management, but they can introduce unexpected challenges in email delivery and display. One such challenge is how email clients handle remote images from newly migrated domains. This guide provides clarity on how different email clients manage image visibility after a domain change and what users can expect.

Understanding the Migration Impact

When an organization migrates to a new server and domain, email clients treat the new domain as a potentially new sender. This security-conscious behavior is designed to protect users from malicious content, but it can temporarily affect how images are displayed in emails.

Why Email Clients Block Images

Email clients implement image blocking as a security measure because:

1. Privacy Protection: Remote images can be used to track email opens through pixel tracking
2. Malware Prevention: Images hosted on malicious domains can pose security risks
3. Spam Detection: Blocking images helps identify and filter spam emails
4. Bandwidth Conservation: Prevents automatic loading of potentially large image files

Email Client Behavior Breakdown

Microsoft Outlook (Classic v2024)

Behavior: Microsoft Outlook Classic (2024) implements strict security controls that block remote images by default.

User Action Required:

• Users must manually select "Download Pictures" for each new email
• This action is required per email, not per sender
• Images will not automatically load in subsequent emails from the same domain

Why This Happens: Outlook Classic prioritizes security and privacy, requiring explicit user consent for each email to prevent tracking and potential security threats.

Best Practice: After migration, inform users that they may need to click "Download Pictures" for emails from the new domain. Once approved, images should display normally for that specific email.

Microsoft Outlook (New/Standard v2025)

Behavior: The newer version of Outlook (2025) has more lenient image handling policies.

User Action Required:

• Images typically load automatically without user intervention
• No manual approval needed in most cases
• Seamless experience for users

Why This Happens: Outlook 2025 uses improved security algorithms and sender reputation systems that allow trusted senders to display images automatically.

Best Practice: Users on Outlook 2025 should experience minimal disruption. If images don't load automatically, they may need to add the sender to their trusted contacts list.

Gmail

Behavior: Gmail has sophisticated image handling that typically allows images to load automatically.

User Action Required:

• Images usually load automatically without user intervention
• Gmail's proxy system helps ensure images display safely
• Minimal user action required

Why This Happens: Gmail uses a proxy system that serves images through Google's servers, which provides both security and automatic image loading. This approach protects users while maintaining a seamless experience.

Verification Note: If Gmail users report issues with image loading after migration, it may be due to:

• Temporary caching of the old domain
• Gmail's spam filters flagging the new domain
• Account-specific security settings

Best Practice: Gmail users should generally see images automatically. If issues persist, check spam folder placement and ensure the new domain is not being filtered.

Mozilla Thunderbird

Behavior: Thunderbird uses a per-sender permission system for remote content.

User Action Required:

• Users are prompted once per sender to allow remote content
• After granting permission, images will load automatically for all future emails from that sender
• One-time approval per sender domain

Why This Happens: Thunderbird balances security with user convenience by remembering user preferences per sender, reducing repeated prompts while maintaining security.

Best Practice: Inform Thunderbird users that they'll need to approve remote content once for the new domain. After the initial approval, all future emails from that domain will display images automatically.

Post-Migration Image Display Workflow

For Users

1. First Email from New Domain:

   • Some clients may prompt for image approval
   • Click "Download Pictures," "Load Remote Content," or similar option
   • Images should display immediately

2. Subsequent Emails:

   • Behavior varies by client (see breakdown above)
   • Outlook Classic: Requires approval per email
   • Outlook 2025: Automatic loading
   • Gmail: Automatic loading
   • Thunderbird: Automatic after first approval

3. If Images Don't Load:

   • Check spam/junk folder placement
   • Verify sender is in trusted contacts
   • Review email client security settings
   • Contact IT support if issues persist

For Administrators

1. Pre-Migration Communication:

   • Notify users about the upcoming domain change
   • Provide instructions for their specific email client
   • Set expectations for temporary image loading behavior

2. Post-Migration Monitoring:

   • Monitor spam folder placement rates
   • Track user reports of image loading issues
   • Verify email deliverability metrics

3. Domain Reputation:

   • Ensure proper SPF, DKIM, and DMARC records
   • Warm up the new domain gradually
   • Monitor sender reputation scores

Email Compliance and Security

Standard Email Delivery Compliance

It's important to note that emails from the migrated domain are fully compliant with standard email delivery and anti-spam policies. The image blocking behavior is a client-side security feature, not an indication of email deliverability issues.

Indicators of Compliance:

• ✅ Emails are not being redirected to Spam folders
• ✅ Emails are reaching inboxes successfully
• ✅ No bounce messages or delivery failures
• ✅ Proper authentication records (SPF, DKIM, DMARC) in place

If Emails Were Non-Compliant:

• Emails would be redirected to Spam folders
• Delivery rates would drop significantly
• Bounce messages would indicate policy violations
• Sender reputation would be negatively impacted

Troubleshooting Common Issues

Issue: Images Not Loading in Gmail

Possible Causes:

• Gmail's proxy system may need time to recognize the new domain
• Temporary caching of old domain settings
• Account-specific security settings

Solutions:

1. Wait 24-48 hours for Gmail's systems to update
2. Check if emails are in the Spam folder
3. Verify domain authentication records
4. Add sender to contacts if needed

Issue: Outlook Classic Requires Approval Every Time

This is Expected Behavior: Outlook Classic (2024) requires approval per email as a security feature.

Solutions:

1. Inform users this is normal behavior
2. Provide quick instructions for "Download Pictures" action
3. Consider recommending Outlook 2025 upgrade if feasible
4. Document this as expected behavior, not a bug

Issue: Thunderbird Not Remembering Permission

Possible Causes:

• Thunderbird settings reset
• Profile corruption
• Permission not properly saved

Solutions:

1. Re-approve remote content for the sender
2. Check Thunderbird's remote content settings
3. Verify sender address matches exactly
4. Clear and re-add permission if needed

Conclusion

Email client image handling after a server and domain migration is a normal security behavior, not a deliverability issue. Different email clients implement varying levels of security controls:

• Outlook Classic (2024): Requires approval per email (strictest)
• Outlook 2025: Automatic loading (most lenient)
• Gmail: Automatic loading via proxy system
• Thunderbird: One-time approval per sender (balanced approach)

Understanding these behaviors helps set proper expectations and provides users with clear guidance. The key is communication: inform users about the migration, explain what to expect, and provide simple instructions for their specific email client.

Remember, if emails are reaching inboxes (not spam folders), the migration is successful from a deliverability perspective. Image blocking is a client-side security feature that protects users while maintaining email functionality.

Note: If you're experiencing issues with Gmail specifically, please verify the behavior as it may differ from the general patterns described. Gmail's proxy system and spam filtering algorithms are continuously updated, which may affect image loading behavior.