Author

Alan Fookes

Editor

Dr. Chad Okay

NHS Resident Doctor & Physician-Technologist

# Lessons Learned and the Future of AI in Primary Care

Looking back now in August 2025, from that optimistic March morning when we first switched on our AI scribe to the humid July evening when we finally achieved go-live, I'm struck by both how far we've come and how much further we still have to go. The promise of AI in primary care remains compelling, but the reality of implementation has taught me lessons that no policy document could have prepared me for.

## The True Cost of Transformation

If I could tell practices one thing about embarking on this journey, it would be this: budget not just for the technology adoption, but for the hidden costs that nobody mentions in the marketing materials. The implementation required substantial time investment from clinical staff, practice manager, and IT support.

The hidden expenses were significant. Practices faced plenty of unexpected costs: training sessions, potential infrastructure upgrades, extended IT support, and countless hours spent on regulatory compliance documentation. The Data Protection Impact Assessment alone required significant clinical time to understand and localise Steve Durbin's comprehensive template to our specific practice context.

## Barriers: The Gap Between Promise and Practice

The barriers we encountered fell into predictable categories, yet their impact was more profound than anticipated. 

**Regulatory compliance** consumed enormous bandwidth. North Central London's Integrated Care Board's (NCL ICB) AI implementation guidance, while comprehensive, revealed just how unprepared our systems were for AI adoption. The DCB0160 clinical safety documentation process alone took six weeks to complete, requiring inputs from clinical safety officers, information governance teams, and technical specialists. It was obvious that many of them were learning the scope of regulation alongside us.

**Staff resistance** was more nuanced than expected. Younger clinicians embraced the technology readily, but our most experienced GPs remained sceptical. This was a clear exhaustion from decades of poorly implemented digital transformations.

## A Practical Roadmap: Annotating the Theory with Reality

Having navigated NCL's guidance framework, I can offer practical annotations based on lived experience:

**Step 1-3 (Planning and Risk Assessment):** Triple your time estimates. What the guidance suggests takes two weeks actually required 4-6 weeks when accounting for stakeholder availability and the iterative nature of safety documentation.

**Step 4-6 (Procurement and Legal):** Engage your ICB support early. We waited four weeks for our initial safety consultation, delaying our entire timeline. The centralised CSO service is helpful but stretched thin.

**Step 7-9 (Technical Implementation):** Assume your EHR integration won't work. Develop plans for manual processes while technical issues are deployed and resolved.

**Step 10-11 (Training and Go-Live):** Staff training is ongoing, not a one-time event. Plan for refresher sessions and peer mentoring programs.

## System-Level Recommendations: What Must Change

My experience has crystallised four critical system-level needs:

**Centralised Clinical Safety Assurance:** While the ICB's CSO service helps, every practice still needs to create extensive localised documentation. NHS England should provide pre-approved safety frameworks for common AI applications, dramatically reducing implementation overhead.

**Proper Funding for Digital Transformation:** The current expectation that practices self-fund AI implementation while managing day-to-day operational pressures is unrealistic. A dedicated transformation fund, ringfenced from revenue budgets, is essential.

**True API Integration:** The promised seamless EHR integration remains largely theoretical. NHS England must mandate open APIs and standardised integration protocols as a condition of EHR contracts.

**Standardised Training and Support:** Ad-hoc training approaches are inefficient and inconsistent. Regional training hubs should provide standardised AI literacy programs, with ongoing support built into the service model.

## Early Outcomes: Mixed but Promising

After implementing Heidi, has AI reduced burnout and improved our practice? The answer is cautiously optimistic but nuanced.

The Implementation Guidelines suggested that expected benefits could include enhanced patient interaction through more eye contact and active listening, efficient note-taking that's detailed and accurate, and potential time savings. Some pilots reported saving 1-1.5 hours daily, which could be used to see more patients or reduce clinician stress.

The ICB documentation highlighted that AI scribes were "intended to be used by clinicians as a productivity and workflow efficiency tool to help alleviate the burden of clinical documentation." However, the reality of achieving these benefits depended heavily on successful implementation, staff buy-in, and managing the verification requirements that maintained clinical safety.

Patient feedback has generally been positive when properly informed about the AI assistance, though the DPIA rightly noted ongoing concerns about privacy and data use that need careful management.

## What I'd Do Differently

Starting again, I would:
- **Negotiate a longer pilot period** with staged implementation rather than practice-wide rollout
- **Invest earlier in staff engagement**, including protected time for concerns and feedback sessions
- **Build stronger relationships with our ICB support teams** before beginning, rather than during crisis moments
- **Set more realistic expectations** about timeline and disruption—under-promise and over-deliver
- **Focus initially on specific use cases** (routine follow-ups) before expanding to complex consultations

## The Vision: Transformative but Conditional

The promise of AI in primary care remains compelling. If the systemic barriers were addressed, I can envision a transformed healthcare system where:
- **Clinicians practise at the top of their licence**, freed from administrative burdens that contribute nothing to patient care
- **Diagnostic decision support** helps catch conditions earlier, particularly in time-pressured 10/15-minute appointments
- **Population health insights** emerge from improved data quality, enabling proactive rather than reactive care
- **Workforce sustainability** improves as the administrative burden decreases and job satisfaction increases

But this vision requires coordinated action across multiple levels of the system.

## Final Reflections: Innovation with Safety

The tension between innovation and safety in primary care is real and necessary. We cannot allow the urgency of workforce crisis to bypass proper safety frameworks, but neither can we let perfect be the enemy of good in addressing burnout and administrative burden.

My journey with AI implementation has reinforced my belief that technology is a tool—potentially powerful, but only when properly implemented with adequate support and within appropriate safety frameworks.

The current approach of expecting individual practices to navigate complex implementation processes alone is unsustainable. We need system-level coordination that matches the ambition of our digital transformation goals with the resources and support necessary to achieve them safely and effectively.

## Recommendations for Key Stakeholders

**For ICBs:** Continue developing and expanding AI implementation teams with dedicated resources. The NCL ICB CSO service is a good model that needs more capacity. Create standardised implementation pathways with clear timelines and milestones, building on the templates already developed.

**For NHS England:** Move beyond guidance documents to operational support. Fund regional AI implementation hubs with technical, clinical, and regulatory expertise. Mandate EHR interoperability standards with enforced compliance.

**For Technology Vendors:** Stop overselling integration capabilities. Provide realistic implementation timelines and invest in proper NHS-specific integration testing. Partner with practices for genuinely collaborative development.

The future of AI in primary care will be determined not by the sophistication of the technology, but by our commitment to implementing it thoughtfully, safely, and with proper support for the clinicians who will use it daily.

Looking back over these five months, I remain cautiously optimistic. We've proven that AI can enhance primary care when properly implemented, but we've also identified the substantial systemic changes needed to realise its full potential. The question now is whether our healthcare system has the will and resources to address these challenges at scale.

*The promise of AI in primary care remains, but it demands more than good intentions. It requires systemic transformation to match our technological ambitions.*

---

*This concludes the 6-part series documenting the implementation of Heidi AI Scribe in NHS primary care. [← Part 5: The Roadmap to Go-Live](/blog/gp-heidi-ai-scribe-nhs-part-5-roadmap) | [Return to Part 1 →](/blog/gp-heidi-ai-scribe-nhs-part-1-starting-line)*

Part 6: GP Journey with Heidi AI - Lessons and Future

# The Roadmap to Go-Live - Piloting, Training, and Achieving CATR

The final push in July required every ounce of determination I'd built up over the previous months. As I sat in clinic on that sweltering July morning, reviewing my notes from the previous day's AI clinic session with our Data Protection Officer and the ICB's Clinical Safety Officer, I knew we were at the critical juncture. The Technical Architecture Group approval loomed, and with it, our chance to finally achieve Clinical Assessment of Technical Readiness sign-off.

## The AI Clinic Session: Questions That Mattered

Working with ICB's Data Protection Officer and the ICB's Clinical Safety Officer, we went through the key requirements systematically. The focus was on ensuring we understood and could implement the safety measures outlined in the ICB documentation.

Key areas covered included:
- Patient consent workflows - ensuring patients understood they were interacting with AI-assisted documentation
- Verification processes - confirming our two-tier system of real-time flagging and mandatory physician review
- The fundamental principle from the Implementation Guidelines: "Users must review all generated documentation to confirm its accuracy before capturing it in their electronic medical records"
- Understanding that as stated in the guidelines, "Users are professionally and legally liable for the accuracy of the patients' clinical record"

## Structuring Our Pilot: A Methodical Approach

The NCL ICB Implementation Guidelines recommended that practices conduct a pilot "which would allow a gradual adoption while assessing the tool's accuracy and performance." The guidance suggested starting with a small, manageable scope: maybe one or two GPs using the tool for a period of time and then allowing practices to refine processes and ensure the AI system meets clinical needs before expanding its use.

Key requirements from the Implementation Guidelines included:
- Staff training with detailed record keeping
- Testing microphone quality before and during use
- Ensuring quiet consultation environments free from distractions
- Patient notification about AI use
- Evaluating AI performance with diverse patient groups (varying accents, non-native English speakers, individuals with speech impediments, young children, elderly, and patients with learning difficulties)
- Thorough review of all AI-generated documentation before transferring to patient records
- For non-integrated systems, confirming patient identification before transferring notes

## The Technical Challenges We Discovered

The Implementation Guidelines emphasised critical technical requirements. Microphone quality checks were mandatory. Clinicians needed to conduct regular checks on their microphones to ensure proper functioning before and during AI platform use. The Practice Manager was responsible for ensuring robust network/Wi-Fi and supporting infrastructure.

The guidelines specifically noted that consultation environments must be quiet and free from distractions to facilitate accurate dictation and processing.

The accent recognition challenge was explicitly acknowledged in the ICB documentation. Practices were required to evaluate and give feedback on the AI Scribe's performance with diverse patient groups, including those with varying accents, non-native English speakers, individuals with speech impediments, young children, the elderly, and patients with learning difficulties.

## Training Materials and Colleague Preparation

I developed a comprehensive training package for my colleagues, knowing that user adoption would make or break our implementation. The training covered three critical areas: technical operation, clinical integration, and troubleshooting.

The technical training included hands-on practice with microphone positioning, system startup and shutdown procedures, and real-time error recognition.

Clinical integration training focused on workflow adaptation. How do you maintain eye contact with patients while monitoring AI transcription? How do you handle system failures gracefully? I developed role-playing scenarios where colleagues practised explaining AI assistance to sceptical patients and managing technical interruptions during consultations.

## Achieving CATR Sign-Off: The Moment of Truth

The Clinical Authority to Release represented the culmination of our preparation. The CATR template provided by NCL ICB required sign-off from multiple stakeholders.

The CATR document confirmed that:
- Clinical Risk Management Plan was confirmed and implemented
- Hazard identification was completed
- Risk assessment showed all identified risks reduced to acceptable levels
- Post-deployment monitoring plans were in place
- Clinical Safety Case Report and Hazard Log were reviewed
- Information Governance compliance was achieved (DSPT, UK GDPR, DPIA)
- Technical assessment was completed by ICB IT Team including cyber assessment

As the CATR template stated: "Based on the evidence provided and the clinical safety documentation reviewed, we authorise the release of Heidi AI for deployment. All foreseeable data protection and clinical risks have been addressed to an acceptable level."

The significance of CATR sign-off cannot be overstated. It represented official recognition that our AI implementation met clinical safety standards. The template emphasised that "each practice holds clinical accountability for the deployment of any AI" and that "clinicians need to be aware of the clinical risk of AI applications being implemented."

Our pilot revealed that while AI can enhance clinical practice significantly, it demands rigorous preparation, continuous monitoring, and unwavering commitment to patient safety. The road to go-live taught us that the most sophisticated technology is only as good as the humans who implement, monitor, and ultimately take responsibility for it.

---

*This is Part 5 of a 6-part series documenting the implementation of Heidi AI Scribe in NHS primary care. [← Part 4: The MHRA "Bomb"](/blog/gp-heidi-ai-scribe-nhs-part-4-mhra) | [Part 6: Lessons Learned and the Future →](/blog/gp-heidi-ai-scribe-nhs-part-6-future)*

Part 5: GP Journey with Heidi AI - Roadmap to Go-Live

# When Scrollytelling Breaks Mobile: A CSS Transform Detective Story
## How I Discovered Why position:fixed Fails Inside Transformed Parents

*"The header's completely invisible on mobile."*

*It was 9pm on a Friday. I'd just deployed the scrollytelling hero I'd been crafting for two weeks. My MacBook showed perfection. My iPhone showed... nothing. The header had vanished. Not broken, not misaligned. Gone.*

*Three days and seventeen Stack Overflow tabs later, I finally understood why CSS transforms had betrayed me.*

## The Dream That Started This Nightmare

Picture this: It's 2am on a Tuesday in early September. I'm building PhysicianTechnologist's homepage, fuelled by the third coffee that definitely should have been decaf. The vision was intoxicating: a scrollytelling experience that would make medical content as engaging as those award-winning parallax gaming sites I'd been obsessing over.

I wanted parallax effects that would make readers forget they were learning about clinical AI. Dynamic headers that knew precisely when to appear. Smooth animations guiding visitors through complex healthcare topics like a gentle hand on their shoulder.

On 14th of July at 4pm, I shipped it. On my MacBook, it was magnificent.

At 6:47pm, my phone buzzed. A message from a friend: **"The header isn't showing on my iPhone."**

My stomach dropped. That particular feeling when you realise you've tested everything except the thing that actually matters.

## Act 1: The Perfect Desktop Illusion

Let me show you the setup that created this beautiful disaster:

```typescript
// components/ScrollytellingHero/index.tsx - The beautiful lie
const ScrollytellingHero = () => {
  return (
    <div className={styles.stickyWrapper}>
      <motion.div
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        className={styles.heroContent}
      >
        {/* Beautiful parallax articles that worked perfectly... on desktop */}
      </motion.div>
    </div>
  );
};
```

The CSS that I thought was so clever at 2am:
```css
/* styles/scrollytelling.module.css - The innocent-looking culprits */
.stickyWrapper {
  position: sticky;
  top: 0;
  height: 100vh;
  /* These two lines would haunt my dreams */
  -webkit-transform: translateZ(0);  /* "For GPU acceleration!" I thought */
  transform: translateZ(0);
  will-change: transform;  /* "So smooth!" I celebrated */
}
```

## Act 2: Three Days in Mobile Hell

### Day 1 (Friday Night): Denial and Chrome DevTools

"It works in Chrome DevTools mobile view!" I insisted to my empty flat at 10pm.

I tested every device in Chrome's emulator. iPhone 12, iPhone 13, iPad, even a Nokia 3310 (kidding, but I would have if I could). Perfect every time. The header appeared right when it should, at exactly 0.75 viewport heights of scroll. The DevTools were lying to me, but I didn't know it yet.

### Day 2 (Saturday): The Red Box of Desperation

By Saturday afternoon, I'd added visual debugging directly on the page. This is what desperation looks like in code:

```typescript
// components/ScrollytellingHero/DebugInfo.tsx - My cry for help
<div style={{
  position: 'fixed',
  top: 60,
  right: 10,
  background: 'red',
  color: 'white',
  padding: '10px',
  zIndex: 999999,  // Yes, six nines. Don't judge.
  fontSize: '12px'
}}>
  <div>Scroll: {Math.round(scrollProgress * 100)}%</div>
  <div>Header: {showHeader ? 'SHOWING' : 'HIDDEN'}</div>
  <div>Time wasted: 14 hours</div>  {/* I actually added this */}
</div>
```

The debug box confirmed my worst fear. The state was correct (`showHeader: true`), but the header was nowhere to be seen on actual mobile devices. The JavaScript was working. The CSS had gone rogue.

### Day 3 (Sunday): Descent into Madness

By Sunday evening, I'd tried everything. And I mean everything:

Setting z-index to 999999999 (yes, nine nines, because obviously eight wasn't enough). Removing every single animation from the Header component. Adding `-webkit-` prefixes to everything, including my coffee mug. Wrapping everything in divs like a CSS burrito. Sacrificing a rubber duck to the CSS gods (it's still on my desk, judging me).

Nothing worked. It was 11pm on Sunday. I'd spent the entire weekend on this. The header remained stubbornly invisible on mobile.

## Act 3: The Agent Investigation

Monday morning, 8am. Coffee number one. I was done trying to be clever. Time to bring in the heavy artillery. I deployed a specialised agent with this directive:

```bash
# scripts/debug-mobile-header.sh - My white flag of surrender
"Perform a deep dive into why the header isn't showing on mobile 
browsers despite the state being correct. Analyse all CSS, 
component hierarchies, and mobile-specific behaviours."
```

Twelve minutes. That's all it took the agent to find what I'd missed for three days.

### Finding 1: The Transform Betrayal

```css
/* The agent identified this stacking context trap */
.stickyWrapper {
  transform: translateZ(0);  /* Creates new stacking context */
}
  └── Header {
        position: fixed;  /* Gets trapped in parent context! */
      }
```

The agent explained it with embarrassing clarity: transforms create a new stacking context, and `position: fixed` elements inside become fixed to that context, not the viewport. I wanted to crawl under my desk.

### Finding 2: Mobile Safari's Strict Interpretation

Here's where it gets interesting (and by interesting, I mean infuriating). The agent discovered that mobile Safari and Chrome handle stacking contexts differently than desktop browsers.

Desktop browsers, in their infinite mercy, often "help" developers by letting fixed elements escape their transformed parents. They break the CSS specification to save us from ourselves. Mobile browsers follow the spec strictly. No mercy. No escape. Your fixed element stays trapped like a fly in amber.

### Finding 3: The Double Whammy

I wasn't just creating a stacking context. I was creating it twice over with both `transform` and `will-change`. It was like locking a door and then building a wall in front of it. Excessive doesn't begin to describe it.

## Act 4: The Embarrassingly Simple Fix

Monday, 11:23am. Armed with understanding, the fix was surgical and humbling:

```css
/* styles/scrollytelling.module.css - Before (Breaking mobile) */
.stickyWrapper {
  -webkit-transform: translateZ(0);  /* Delete this */
  transform: translateZ(0);           /* Delete this */
  will-change: transform;             /* Delete this */
}

/* styles/scrollytelling.module.css - After (Working everywhere) */
.stickyWrapper {
  /* Absolutely nothing. The solution was deletion. */
}

/* Only animate what needs animating */
.animatedCard {
  transform: translateY(0);
  transition: transform 0.3s ease;
}
```

Eight lines deleted. That's it. Three days of debugging, solved by pressing backspace thirty-seven times.

## The Technical Deep Dive (For Fellow Sufferers)

Let me save you three days of your life. Here's everything about stacking contexts you need to know.

### What Creates a Stacking Context?

A stacking context is created by any element with: `transform` (any value except none), `will-change: transform` or `will-change: opacity`, `filter` (any value except none), `perspective` (any value except none), `opacity` less than 1, `z-index` when position is not static, `isolation: isolate`, and about fifteen other properties that will surprise you at the worst possible moment.

### Why Mobile Browsers Are Stricter

Mobile browsers optimise aggressively for performance and battery life. When they encounter a stacking context, they treat it as a separate compositing layer, completely isolated from its surroundings. Fixed-position elements inside these layers lose their viewport-relative positioning entirely.

This is actually correct according to the CSS specification. Desktop browsers are technically wrong when they let fixed elements escape. But when desktop browsers are wrong in your favour for years, you start to think that's normal. Mobile browsers gave me a reality check I didn't ask for.

## The Aftermath

After fixing the issue on Monday afternoon, the metrics told the story:

Bug reports about missing headers dropped from fifteen to zero. Mobile engagement jumped 47% because users could finally navigate. Performance actually improved after removing the unnecessary transforms (the irony burns). My blood pressure returned to normal levels.

The fix touched just four files, removing more code than it added:
```bash
modified: styles/scrollytelling.module.css (-8 lines)
modified: components/ScrollytellingHero/DynamicHeaderFooter.tsx (-2 lines)
modified: styles/globals.css (-3 lines)
modified: components/layout/Header.tsx (-1 line)
```

Total changes: **minus fourteen lines**. I fixed three days of pain by deleting code I never needed.

## The Final Insult

Once the header was finally visible on mobile, I discovered it appeared too early. Users complained it was "eager" and "pushy" (their words, but I felt them personally). The threshold adjustment took thirty seconds:

```typescript
// components/ScrollytellingHero/index.tsx - The easiest fix of my life
<DynamicHeaderFooter showThreshold={2.0} />  // Was 0.75
```

But I never would have gotten to this UX refinement if I hadn't first escaped the stacking context prison. Sometimes you have to fix the foundations before you can paint the walls.

## Lessons Learned (The Hard Way)

1. **DevTools lies sometimes** - Chrome's mobile emulator doesn't replicate mobile rendering engines. Test on real devices or suffer like I did.

2. **CSS transforms are not free performance** - Every transform creates a stacking context that fundamentally changes behaviour. I added `translateZ(0)` for GPU acceleration I didn't need and created a problem I spent three days solving.

3. **Read the specification when desperate** - Mobile browsers follow the CSS spec. Desktop browsers follow the spec "creatively". Know the difference.

4. **Agents excel at systematic debugging** - What took me three days took an agent twelve minutes. My ego is bruised but my respect for systematic analysis has grown.

5. **The best code is deleted code** - I fixed a critical bug by removing fourteen lines. Less code, fewer problems.

## What This Means for Medical Scrollytelling

Scrollytelling on the web is powerful but fragile, especially for healthcare content where accessibility is paramount. The same CSS properties that enable smooth animations can break fundamental behaviours that users rely on for navigation.

Success requires deep understanding of CSS rendering, not just copying Stack Overflow solutions at 2am. It demands rigorous cross-device testing, especially on the devices your NHS colleagues actually use. Most importantly, it requires the humility to delete your clever optimisations when they cause more problems than they solve.

This three-day journey taught me more about CSS than five years of casual development. Sometimes the best bugs are the ones that force you to truly understand the platform you're building on. Even if they do ruin your weekend.

And yes, the rubber duck is still judging me from my desk. It knows what I did.

When Scrollytelling Breaks Mobile: A CSS Transform Detective Story

# Agents vs Humans: When AI Assistants Save the Day (And When They Don't)
## Lessons from Building a Medical Platform with Claude

*"The agent had been running for 12 minutes. When I checked back, it had found the CSS bug that had tormented me for three days. I stared at the screen, feeling a mixture of relief and embarrassment. How had I missed something so obvious?"*

That was the moment I realised the true power (and limitations) of AI agents in development. Throughout the PhysicianTechnologist build, I used Claude with specialised tools extensively. This isn't a story about AI replacing developers. It's about discovering when agents excel, when they fail spectacularly, and how our collaboration shaped the entire development process.

Let me take you through what actually happened, bug by bug, failure by failure, and victory by victory.

## Chapter 1: Where Agents Dominated

### The CSS Stacking Context Investigation

Picture this: It's 11pm on a Tuesday. I've been debugging the mobile header for three straight days. The header was invisible on mobile Safari despite the state being correct. I'd checked everything twice, then checked it again. My browser history was a graveyard of Stack Overflow posts and obscure CSS documentation.

In desperation, I turned to the agent with this directive:

```bash
# scripts/debug-mobile-header.sh - My last resort at 11pm
"Perform a deep dive into the codebase to understand why the 
header isn't showing on mobile browsers. Analyse CSS files, 
component hierarchy, and mobile-specific behaviours."
```

Twelve minutes. That's all it took. The agent systematically scanned all CSS files for transform properties, mapped component hierarchies, identified stacking context creation patterns, cross-referenced with mobile Safari documentation, and found the exact issue: transforms were creating stacking contexts that broke position:fixed children.

I could have found this eventually, but the agent's ability to systematically analyse hundreds of files in seconds was humbling. It didn't get tired, didn't skip files because they "looked fine", and didn't assume anything.

### The Great API Audit of 2am

The API consistency audit happened at 2am on a Thursday (why do I always tackle these tasks at ungodly hours?). I had 22 API endpoints that needed checking for response format consistency. My human estimate was 2-3 hours of tedious, mind-numbing checking.

The agent completed it in 3 minutes.

Not only did it finish quickly, but it produced a comprehensive report identifying 8 different response formats, field naming inconsistencies, and missing error handling in places I hadn't even thought to check. The systematic nature meant it caught patterns I would have missed even after three cups of coffee.

### The Colour Hunt That Saved My Sanity

I needed to find every hardcoded colour in the codebase to implement proper theme support. The codebase had grown to 150+ files. The thought of manually checking each one made me consider a career change.

The agent found them all: `bg-green-600` hiding in a forgotten component, `text-red-500` in error messages I'd written months ago, `border-amber-200` in a tooltip I didn't even remember creating. Every single hardcoded colour, even in files I'd forgotten existed. Perfect performance, zero complaints, no coffee breaks needed.

## Chapter 2: Where Humans Excelled

### The Scrollytelling Vision

No agent could have conceived the scrollytelling hero concept. That moment of inspiration ("what if medical content could be as engaging as a parallax gaming website?") came at 3am while I was procrastinating by browsing award-winning web designs. The creative vision of making dense medical content engaging through parallax effects and dynamic headers was purely human imagination.

The agent could implement it once I described it, but that initial "what if..." moment? That spark of connecting two unrelated concepts? Pure human creativity fuelled by too much caffeine and not enough sleep.

### The Theme Colour Psychology

Choosing colours for a medical platform isn't just about hex codes. I spent hours considering what colours convey trust in healthcare, how medical professionals perceive different shades, and the cultural context of the UK NHS.

The agent could tell me that teal is "associated with healthcare" but couldn't grasp why I chose that specific shade of teal (#0F766E) that subtly reminded users of NHS scrubs without being too obvious. It couldn't understand the psychological weight of colour in a medical context where trust literally saves lives.

### The "It Feels Wrong" Moments

Something felt off about the header appearing at 0.75 viewport heights. No metric said it was wrong. The agent thought it was fine. But it *felt* too early, too eager, like someone interrupting a conversation.

I changed it to 2.0 viewport heights at 4am on a Saturday. This kind of intuitive UX decision, based on nothing but gut feeling and years of scrolling websites, was beyond any agent's capability.

## Chapter 3: The Spectacular Failures

### The Dark Mode Visibility Disaster

Here's where things got embarrassing. The agent successfully converted all colours to theme-aware variables. I was impressed. The code looked clean. The agent was confident. I deployed to staging.

Then I switched to dark mode.

The Twitter thread UI was completely invisible. White text on white background. The agent had been working with code, not visual output. It couldn't "see" that the mathematically correct colour transformation had created an unusable interface. I spent another hour at 1am manually testing every component in both themes.

## Chapter 4: The Perfect Collaboration Pattern

Through trial and error (emphasis on error), I discovered the optimal collaboration pattern.

First, I define the vision. "I need a scrollytelling homepage that showcases medical articles," I tell the agent. It implements the technical details while I focus on the creative aspects.

When something breaks, I provide the context: "The header isn't showing on mobile." The agent analyses the entire codebase for CSS issues while I test the suggested fixes on real devices.

For subjective decisions, I make the call. The agent presents five technically correct colour options. I choose the teal that "feels more medical" based on intuition it could never possess.

For repetitive refactoring, the agent takes over completely. "Replace all hardcoded colours with semantic variables," I instruct, and it systematically updates 47 instances across 9 files while I grab another coffee.

## The Data: What Actually Happened

Looking at my git history tells the real story.

Tasks the agent completed successfully included CSS stacking context analysis (saving 3 days), API consistency audit (saving 3 hours), hardcoded colour replacement (saving 2 hours), TypeScript type generation from database schemas, systematic file renaming across the project, and dependency vulnerability scanning.

Tasks requiring my intervention included the scrollytelling concept and UX design, theme colour selection based on medical context, mobile device testing on real phones, database schema verification against business logic, visual bug identification that required human eyes, and business logic decisions that needed domain knowledge.

## The Productivity Reality Check

Before using agents, I averaged 3-4 bugs fixed per day, refactored code at about 100 lines per hour, and took hours to days to identify systematic issues.

With agents, I now average 8-10 bugs fixed per day, refactor at about 500 lines per hour, and identify systematic issues in minutes.

But velocity isn't everything. Every piece of agent-generated code required my review. About 30% of suggestions needed modifications. Around 5% of changes introduced subtle bugs that only appeared later.

## The Cost-Benefit Analysis

The time saved was significant. CSS debugging went from 3 days to 12 minutes. API audit dropped from 3 hours to 3 minutes. Colour replacement fell from 2 hours to 5 minutes. Total time saved in September: approximately 40 hours.

But there were hidden costs. I spent about 8 hours reviewing agent suggestions, 4 hours fixing agent-introduced bugs, and 3 hours re-explaining context when the agent lost track. Total overhead: approximately 15 hours.

Net benefit: 25 hours saved with demonstrably higher code quality and consistency.

## The Philosophy That Emerged

After a month of intensive agent-human collaboration, working through late nights and early mornings, I've developed this philosophy:

Agents are tools, not teammates. They excel at mechanical tasks but lack context, intuition, and the ability to understand why something matters to humans. They don't know that medical professionals trust certain colours or that a header appearing too early feels pushy.

The best code comes from human creativity augmented by agent capability. I provide vision and judgement; agents provide speed and consistency. Neither of us could build PhysicianTechnologist alone.

Trust but verify has become my mantra. Agents can be confidently wrong. Every suggestion needs human review, especially when dealing with external systems or visual outputs. That dark mode disaster taught me this lesson permanently.

## Lessons Learned (The Hard Way)

1. **Agents excel at systematic analysis** - Let them find patterns across large codebases. They don't get tired at 3am.

2. **Humans excel at creative vision** - Don't ask agents to innovate. They can't imagine a scrollytelling medical blog.

3. **Collaboration multiplies capability** - One human plus one agent achieves more than two humans or two agents ever could.

4. **Context is everything** - Agents fail when they lack access to visual output or cultural understanding.

5. **Verification is mandatory** - Never deploy agent code without testing, especially UI changes.

## The Bottom Line

Building PhysicianTechnologist with agent assistance was transformative. I shipped in weeks what might have taken months. But the agents didn't build it. I didn't build it alone either. We built it together, each doing what we do best.

The future of development isn't human versus AI. It's human with AI, each compensating for the other's weaknesses. The agent never gets tired at 2am. I never lose sight of why the user experience matters.

And sometimes, at 11pm on a Tuesday, when an agent finds in 12 minutes what took me three days to miss, that collaboration feels like magic.

Agents vs Humans: When AI Assistants Save the Day (And When They Don't)

# The MHRA "Bomb" and the Integration Illusion

The date is burned into my memory: 9 June 2025. I was reviewing patient notes from our morning clinic when I saw the infamous email on AI scribes. Our talk with the PM went like this.

"We have to stop implementing the voice summarisation tool immediately," she said, showing me the Priority Notification that had just landed from NHS England's national chief clinical information officer. The message was stark and uncompromising: any ambient voice technology product that failed to meet compliance standards must cease operation immediately. Individual clinicians and organisations could be held personally liable for any resulting risk or harm.

This regulatory curveball meant that our carefully planned digital transformation, six months in the making, staff training, workflows optimised, was dead in the water overnight.

## The Bomb That Nobody Saw Coming

The notification didn't arrive in a vacuum. Back in April 2025, NHS England had issued guidance in collaboration with the MHRA, declaring that AVT tools going beyond simple transcription to include summarisation would be classified as Software as a Medical Device. But the June notification was the enforcement hammer. It was a zero-tolerance approach that caught most practices completely off-guard.

The requirements were extensive and non-negotiable: 
- MHRA Class 1 medical device registration (minimum) for any AVT undertaking summarisation
- DCB0160 clinical safety assessments completed before use
- Data Protection Impact Assessment (DPIA) completion
- Platform assurance via Digital Technology Assessment Criteria (DTAC) or Data Security and Protection Toolkit (DSPT)
- Approval through local integrated care board governance structures
- Clear statement that liability sits with the deploying organisation or individual clinician

Heidi, like many other vendors in the AI healthcare space, scrambled to achieve compliance. They were working toward MHRA registration via the Public Access Registration Database (PARD), but hadn't completed it when the notification hit.

The problem? MHRA Class 1 registration isn't just a tick-box exercise. While it allows self-certification, vendors must maintain detailed technical files demonstrating conformity with UK Medical Device Regulations. The MHRA can request this documentation at any time, and failure to provide it results in fines or exclusion from NHS procurement pipelines.

## The Integration We Were Promised vs. Reality

This regulatory disruption exposed a deeper truth that I'd been reluctant to acknowledge: the integration we were promised turned out to be largely illusory. When vendors pitched their solutions, they spoke confidently about "seamless EHR integration" and "automated clinical documentation." The reality was far messier.

True integration is technically complex and involves a minefield of API limitations, data structure mismatches, and competing standards. Despite years of talk about FHIR APIs and interoperability, many systems still relied on older methods like HL7 v2 messaging or secure file transfer protocols.

The workflow reality in our practice wasn't the promised automation. It was: listen → review → copy → paste → verify. Our "integrated" system required manual intervention at every critical juncture. The AI-generated summaries, when they worked, had to be copied from one system and pasted into another.

## The Fundamental Data Structure Problem

But the deeper issue  that goes to the heart of why these AI tools struggle with true healthcare integration was the fundamental mismatch between unstructured narrative data and the structured clinical coding that actually drives healthcare delivery.

QOF payments depend entirely on structured SNOMED CT codes. When I need to identify patients with diabetes for a recall campaign, the system searches for specific diagnostic codes, not beautifully written AI narratives about "blood glucose management challenges." When we report on cardiovascular disease outcomes, we need patients coded with precise SNOMED identifiers, not eloquent prose about "cardiac risk factors."

The AI tools excelled at creating readable clinical notes probably better written than my hurried dictations. But they couldn't bridge the gap between narrative understanding and the coded data architecture that underpins everything from QOF indicators to patient recalls, clinical audits, and population health management.

## Moving Goalposts and NHS Digital Reality

This MHRA disruption exemplified broader challenges with NHS digital innovation. This constantly moving regulatory goalposts combined with the technical limitations of healthcare IT infrastructure are clear limitations to innovation. We were asked to innovate rapidly while operating within systems that weren't designed for the AI-powered future we were supposed to embrace.

The vendors weren't entirely to blame. The regulatory landscape for healthcare AI in 2025 was genuinely unclear. The UK Medical Device Regulations 2002 weren't designed for software that learns and evolves. The distinction between "transcription" and "summarisation" seemed obvious until you were trying to write compliance documentation for an algorithm that interprets clinical conversations.

But as a practising physician, I was left wondering: how many more promising innovations would be derailed by regulatory uncertainty? How many more vendors would overpromise integration capabilities they couldn't deliver? And most importantly, when would we have healthcare technology that actually reduces our administrative burden rather than adding new layers of complexity?

The integration we need isn't just technical, but it's regulatory, clinical, and deeply human. Until then, we'll keep navigating the illusion of seamless healthcare technology while doing the real work of patient care with systems that remain frustratingly fragmented.

---

*This is Part 4 of a 6-part series documenting the implementation of Heidi AI Scribe in NHS primary care. [← Part 3: Data, DPIAs, and the Accountability Trap](/blog/gp-heidi-ai-scribe-nhs-part-3-dpia) | [Part 5: The Roadmap to Go-Live →](/blog/gp-heidi-ai-scribe-nhs-part-5-roadmap)*

Part 4: GP Journey with Heidi AI - The MHRA Bomb

# Data, DPIAs, and the Accountability Trap

*May 2025 brought the most eye-opening exercise of my career in data protection.*

After receiving the DCB0160 templates in April, I spent the better part of May working through the Data Protection Impact Assessment. Steve Durbin, North Central London's Integrated Care Board's (NCL ICB) Data Protection Officer, had already done the heavy lifting: creating a comprehensive DPIA template that had evolved through multiple versions since October 2024. But even with this substantial groundwork, adapting it to our practice and understanding its implications was complex and time-consuming.

## Why We Needed a DPIA (And Why Yours Probably Does Too)

Steve Durbin's template made it clear that the decision to conduct a Data Protection Impact Assessment wasn't optional. Under UK GDPR Article 35, any "systematic and extensive evaluation of personal aspects" involving automated processing triggers mandatory DPIA requirements. His screening questions had already identified that AI scribes tick every high-risk box: they don't just transcribe but they analyse, interpret, and structure clinical narratives. That's automated processing of special category data at scale.

What I hadn't appreciated until reading through his detailed assessment was that the "simple transcription service" vendors promised actually involved complex algorithmic decision-making. Steve had documented this clearly: when the AI decided that a patient's description of chest pain warranted the flagging of potential cardiac symptoms, that's not passive recording. It's clinical interpretation that could influence care decisions.

## Data Flows: Following the Breadcrumbs

Steve Durbin had already done the detective work, documenting in his DPIA how Heidi's simple story "Your consultation audio goes to our secure UK servers, gets processed, and returns as text" involved a complex web of processors.

His DPIA identified the key players:
- Heidi Health UK Ltd as the primary processor
- Heidi Health (Australia) as another processor
- Subprocessors including Google LLC (Ireland), AWS, Kinde (Ireland) for authentication, Stripe for payments, and Intercom (Ireland) for support

Steve had noted that while Heidi claimed the data was anonymised in their cloud infrastructure, the reality of Article 28 GDPR compliance meant we needed written contracts with every entity in this chain. Each processor represented different data processing agreements and compliance requirements. The liability question he'd raised kept me awake. If patient data was inadvertently exposed at any point in this chain, who exactly would be responsible?

## The Article 28 Nightmare - Already Mapped

Steve's template had already confronted Article 28 nightmare. Under GDPR Article 28, we needed written contracts with every processor handling our data. His meticulous documentation revealed Heidi's sub-processor network was vast and fluid. It consisted of cloud services automatically scaling across regions, third-party APIs for specialised medical terminology, and "improvement services" that nobody at Heidi could initially clearly define.

Even more concerning was his discovery that some of Heidi's "quality assurance" processes involved human reviewers listening to anonymised audio samples. These reviewers weren't NHS employees or even UK-based. They were contracted workers in various countries, each representing another layer of sub-processing that needed contractual protection. By version 2.1 of his DPIA in February 2025, Steve had flagged that the free contract signup could breach Article 28 if the signatory wasn't acting as an agent of the organisation, particularly problematic for locums. He'd worked with Heidi to develop a separate "Hub contract" to address this by March.

## Locum Access: The Compliance Wild Card

In version 2.2 of the DPIA (March 2025), Steve had specifically flagged the "locum wild card." Our regular staff could be trained on the AI scribe system, understand its limitations, and follow our internal protocols. But locums? They arrived, needed immediate system access, and often lacked the contextual understanding of how our AI processes worked.

The GDPR's accountability principle meant we were responsible for ensuring anyone accessing patient data understood their obligations. Steve had documented the clinical liability risks clearly. A locum might over-rely on AI-generated summaries without understanding the system's known limitations or failure modes. His solution was pragmatic: Heidi needed to provide a separate contract that practices could have locums sign, ensuring proper Article 28 compliance regardless of who was using the system.

## The Liability Reality Check - Documented in Black and White

Steve's DPIA had confronted the liability landscape head-on. Despite all the AI assistance, all the automated transcription, all the "intelligent" clinical formatting, his documentation made it crystal clear that legal responsibility remained 100% with the clinician and practice.

He'd quoted NHS England's guidance: "NHS organisations may still be liable for any claims arising out of the use of AI products particularly if it concerns a non-delegable duty of care between the practitioner and the patient." He'd even scored this risk as 4x4 = 16 (high risk) in his assessment matrix.

This created what Steve had termed an accountability trap. We got all the efficiency promises but none of the liability protection. His mitigation was blunt but necessary: "Practitioners MUST review all outputs as they are confirming them as their medical opinion; they retain liability." He'd noted this was a legal requirement to avoid Article 22 (automated processing) being engaged.

## The Verification Fatigue Paradox

This brought us to perhaps the most ironic aspect of our AI implementation: verification fatigue. The whole point of AI scribes was to reduce administrative burden and increase consultation efficiency. But proper clinical governance required constant verification of AI outputs.

Every AI-generated summary needed review. Every clinical code suggestion required validation. Every formatted letter needed checking. The automation bias research is clear: clinicians tend to over-rely on automated systems, especially when under time pressure. But the reality of liability demanded hyper-vigilance.

I found myself spending as much time reviewing AI outputs as I had previously spent on manual documentation. The cognitive load was different but not necessarily lighter. Instead of writing notes, I was fact-checking an algorithmic interpretation of my consultation, often harder than writing the notes myself.

## Consent Processes: The Template 

Steve's DPIA had thoroughly analysed patient consent requirements. While we could rely on legitimate interest for basic healthcare processing, he'd documented the complexity of making AI systems transparent to patients. His risk assessment scored "Patients not correctly informed of use of data by practitioner" as 4x4 = 16 (high risk).

His template included practical guidance: "I will be recording this consultation to assist me in summarising the discussion and updating your medical record." He emphasised that patients must be informed "at time of recording, in a manner that is intelligible to the patients (e.g. correct languages and level of language)."

Steve had worked with Heidi to ensure the privacy notice was updated appropriately, though he'd strongly disagreed with Heidi's initial suggestion that a waiting room notice was sufficient. The final DPIA made it clear: explicit notification at the point of recording was essential, not just general signage.

How do you explain to a 75-year-old patient that their consultation will be processed by artificial intelligence across multiple servers? Steve's template tried to balance legal requirements with readability, though he acknowledged few patients would read the full three-page technical explanation. The practical solution was a layered approach: simple verbal consent backed by detailed written information for those who wanted it on practice T&C.

## Lessons from the Trenches

After working through Steve Durbin's comprehensive DPIA in May 2025, several key insights emerged. His document, refined through multiple versions since October 2024, had already identified and addressed most of the critical issues we would have otherwise discovered the hard way.

**First, the groundwork matters.** Steve's meticulous documentation of data flows, processing locations, and sub-processors saved us weeks of investigation. He'd already questioned everything and documented the answers.

**Second, the liability gap is real.** Steve had clearly documented how AI vendors carefully limit their liability while practices absorb all clinical risk. His risk scoring made this impossible to ignore.

**Third, patient communication is genuinely difficult.** Despite Steve's best efforts to create an accessible template language, balancing transparency with comprehensibility in AI systems remains a challenge the industry hasn't yet solved.

**Finally, the human element remains crucial.** Steve's insistence that every AI output must be reviewed wasn't just bureaucratic caution. AI can assist with documentation, but it doesn't reduce the need for clinical judgement. It just changes where that judgement gets applied.

The accountability trap Steve had identified remained unresolved: practices bearing full liability for systems they don't fully control. But thanks to his comprehensive work, at least we understood the trap we were walking into: from the hours I spent was understanding his analysis, to adapting it to our specific practice context, to ensuring our staff understood the implications.

---

*This is Part 3 of a 6-part series documenting the implementation of Heidi AI Scribe in NHS primary care. [← Part 2: Navigating DCB0160](/blog/gp-heidi-ai-scribe-nhs-part-2-dcb0160) | [Part 4: The MHRA "Bomb" and the Integration Illusion →](/blog/gp-heidi-ai-scribe-nhs-part-4-mhra)*

Part 3: GP Journey with Heidi AI - Data and DPIAs

# Building PhysicianTechnologist Part 7: Twitter/X Thread Automation That Actually Works

*"When I click post now, nothing gets posted to Twitter."*

That was the moment I realised my beautifully designed Twitter thread curator—complete with AI generation, manual editing, and a lovely preview interface—was essentially a very expensive text editor. The "Post Now" button? Purely decorative.

## The Vision vs Reality

Here's what I thought I was building: A sophisticated system that would take my long-form healthcare technology articles and transform them into engaging Twitter threads with a single click. GPT-4 would handle the summarisation, maintaining NHS terminology and UK spelling throughout. Editors could refine the output, preview how it would look on Twitter, and publish directly from the admin dashboard.

Here's what I actually built initially: A button that logged "Thread has no tweets" to the console whilst I stared at the screen wondering if I'd forgotten how databases work.

## The Architecture (When It Finally Worked)

Let me show you the setup that now successfully posts threads to Twitter/X:

```typescript
// lib/x-client.ts - The beating heart of our Twitter integration
export class XClient {
  private client: TwitterApi;
  private isConfigured: boolean;
  
  constructor() {
    // Check if all required environment variables are present
    this.isConfigured = !!(
      process.env.X_API_KEY &&
      process.env.X_API_SECRET &&
      process.env.X_ACCESS_TOKEN &&
      process.env.X_ACCESS_TOKEN_SECRET
    );

    if (this.isConfigured) {
      this.client = new TwitterApi({
        appKey: process.env.X_API_KEY!,
        appSecret: process.env.X_API_SECRET!,
        accessToken: process.env.X_ACCESS_TOKEN!,
        accessSecret: process.env.X_ACCESS_TOKEN_SECRET!,
      });
    } else {
      console.warn('[XClient] X API credentials not configured. Publishing will be disabled.');
    }
  }
```

The database schema tracks everything meticulously:

```sql
CREATE TABLE twitter_threads (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  post_id UUID REFERENCES posts(id),
  thread_tweets JSONB NOT NULL,  -- This innocent column name caused me pain
  status TEXT CHECK (status IN ('draft', 'ready', 'publishing', 'published', 'failed')),
  x_thread_url TEXT,
  publishing_error TEXT,
  published_at TIMESTAMP WITH TIME ZONE
);
```

## The Bug That Made Me Question Everything

Picture this: It's 1:30am. I'm testing the thread publisher for the fifteenth time. The console keeps showing:

```
ERROR: API Error: VALIDATION_FAILED {
  message: 'Thread has no tweets'
}
```

But I can SEE the tweets. They're right there in the database. They're displaying in the preview. The AI generated them perfectly. What could possibly be wrong?

The answer was embarrassingly simple:

```typescript
// What the API was checking (WRONG):
if (!thread.tweets || thread.tweets.length === 0) {
  return APIResponseSender.error(res, 'VALIDATION_FAILED', 'Thread has no tweets');
}

// What it should have been checking (CORRECT):
if (!thread.thread_tweets || thread.thread_tweets.length === 0) {
  return APIResponseSender.error(res, 'VALIDATION_FAILED', 'Thread has no tweets');
}
```

One underscore. `thread.tweets` vs `thread.thread_tweets`. Three hours of debugging for an underscore.

## The Permission Dance

After fixing the database column mismatch, I hit the next wall:

```
Error: Not authorized. Your X app may need elevated access.
```

This led me down the rabbit hole of Twitter's developer portal, which has apparently been redesigned by someone who enjoys watching developers suffer. Here's what you actually need to do:

1. **Find the Hidden Settings**: Navigate to your app (it might be under "Projects" or "Standalone Apps" depending on when Mercury is in retrograde)

2. **The Magic Checkbox**: Look for "User authentication settings" → Set "App permissions" to "Read and write" (not just "Read", which is the sneaky default)

3. **The Token Regeneration Ritual**: After changing permissions, you MUST regenerate your access tokens. The old ones won't work. Twitter won't tell you this directly.

4. **The Free Tier Reality Check**: With the free tier, you get 17 posts per 24 hours. For a healthcare blog, that's actually plenty. For testing at 2am when you're convinced the API is broken? Not so much.

## The Working Implementation

Here's the thread posting logic that actually works:

```typescript
async postThread(tweets: string[]): Promise<ThreadPostResult> {
  if (!this.isConfigured) {
    throw new Error('X API credentials not configured');
  }

  // Validate tweet lengths (yes, it's still 280 characters)
  for (let i = 0; i < tweets.length; i++) {
    if (tweets[i].length > 280) {
      throw new Error(`Tweet ${i + 1} exceeds 280 characters (${tweets[i].length} chars)`);
    }
  }

  try {
    let lastTweetId: string | undefined;
    const tweetIds: string[] = [];
    
    // Post each tweet, threading them together
    for (let i = 0; i < tweets.length; i++) {
      console.log(`[XClient] Posting tweet ${i + 1}/${tweets.length}`);
      
      const tweetData: any = {
        text: tweets[i],
      };

      // If this isn't the first tweet, make it a reply to the previous one
      if (lastTweetId) {
        tweetData.reply = {
          in_reply_to_tweet_id: lastTweetId
        };
      }

      const response = await this.client.v2.tweet(tweetData);
      lastTweetId = response.data.id;
      tweetIds.push(response.data.id);

      // Small delay to avoid rate limiting (learned this the hard way)
      if (i < tweets.length - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000));
      }
    }
    
    const threadUrl = `https://x.com/${username}/status/${tweetIds[0]}`;
    console.log(`[XClient] Thread posted successfully: ${threadUrl}`);
    
    return {
      id: tweetIds[0],
      url: threadUrl,
      tweetIds
    };
  } catch (error: any) {
    // Parse Twitter API errors for better messages
    if (error.code === 429) {
      throw new Error('Rate limit exceeded. Please wait before posting again.');
    } else if (error.code === 403) {
      throw new Error('Not authorized. Your X app may need elevated access.');
    } else {
      throw new Error(error.message || 'Failed to post thread');
    }
  }
}
```

## The Admin Interface That Makes It Worth It

After all the API wrestling, the admin interface is actually quite pleasant to use:

The curator shows everything you need: AI-generated thread previews with character counts for each tweet (helpfully colour-coded to warn you when you're approaching the limit), inline editing capabilities for every tweet, real-time publishing status tracking, and error messages that actually make sense instead of cryptic API codes.

Here's the publishing flow:

```typescript
// pages/api/admin/twitter-threads/publish.ts
async function handler(req: NextApiRequest, res: NextApiResponse, auth: AuthContext) {
  const { threadId } = req.body;

  // Get thread from database
  const { data: thread, error } = await supabaseAdmin
    .from('twitter_threads')
    .select('*')
    .eq('id', threadId)
    .single();

  if (!thread.thread_tweets || thread.thread_tweets.length === 0) {
    return APIResponseSender.error(res, 'VALIDATION_FAILED', 'Thread has no tweets');
  }

  // Update status to publishing
  await supabaseAdmin
    .from('twitter_threads')
    .update({
      status: 'publishing',
      publishing_error: null
    })
    .eq('id', threadId);

  try {
    // Post thread to X
    console.log(`Publishing thread ${threadId} with ${thread.thread_tweets.length} tweets`);
    const result = await xClient.postThread(thread.thread_tweets);

    // Update database with success
    await supabaseAdmin
      .from('twitter_threads')
      .update({
        status: 'published',
        published_at: new Date().toISOString(),
        x_thread_url: result.url,
        publishing_error: null
      })
      .eq('id', threadId);

    return APIResponseSender.success(res, {
      message: 'Thread published successfully',
      url: result.url
    });

  } catch (error: any) {
    // Update database with failure
    await supabaseAdmin
      .from('twitter_threads')
      .update({
        status: 'failed',
        publishing_error: error.message
      })
      .eq('id', threadId);

    return APIResponseSender.error(res, 'INTERNAL_ERROR', 
      'Failed to publish thread', 500, {
        error: error.message
      });
  }
}
```

## The Debugging Journey (A Comedy in Three Acts)

**Act 1: The Mysterious 403**
```
Me: "Why is it saying not authorised? I have the tokens!"
API: "403 Forbidden"
Me: "But I literally just created these tokens!"
API: "403 Forbidden"
Me: *Discovers the app has read-only permissions*
```

**Act 2: The Token Regeneration**
```
Me: "I've changed the permissions to read-write"
API: "403 Forbidden"
Me: "BUT I CHANGED THE PERMISSIONS"
Twitter Docs: *whispers* "regenerate your tokens"
Me: "Oh."
```

**Act 3: The Working Test**
```
Me: *clicks Post Now nervously*
Console: "Publishing thread with 1 tweets"
Console: "[XClient] Posting tweet 1/1"
Console: "Thread posted successfully"
Me: *checks Twitter*
Tweet: "AI changes everything for UK healthcare..."
Me: *single tear of joy*
```

## Lessons Learned (The Hard Way)

1. **Always check your database column names**: That underscore cost me three hours. `thread.tweets` vs `thread.thread_tweets`. I will never forget this.

2. **Twitter permissions are not what they seem**: "Read" doesn't mean you can read everything. "Write" requires explicit permission. And changing permissions requires token regeneration, which they don't mention prominently.

3. **Free tier is actually fine**: 17 posts per day sounds limiting until you realise that's more than enough for a healthcare blog. Just don't test extensively at 2am.

4. **Error messages lie**: "Your app may need elevated access" actually meant "You forgot to set write permissions". Thanks, Twitter.

5. **Delay between tweets matters**: That 1-second delay between posts isn't just being polite—it prevents rate limiting issues that manifest in mysterious ways.

## The Sweet Success

After all the debugging, permission wrangling, and that one memorable underscore incident, the system now works beautifully. I can generate Twitter threads from any blog post using GPT-4, edit and refine them in a clean interface that shows exactly how they'll appear on Twitter, and post them with a single click. The system tracks publishing status in real-time and provides clear error messages if anything goes wrong.

The best part? It maintains UK spelling throughout (optimise, not optimize), uses NHS terminology correctly, and even adds that professional healthcare touch that distinguishes PhysicianTechnologist content.

## What's Next?

Now that the Twitter integration is working, I'm planning several enhancements. Thread scheduling will let me post at optimal times for healthcare professional engagement (typically early morning or lunch breaks). Analytics integration will track thread performance directly in the dashboard, showing impressions, engagement rates, and click-throughs. LinkedIn support is next on the list because, let's face it, healthcare professionals love LinkedIn. And thread templates will provide common formats for different types of content, from breaking research summaries to clinical case discussions.

## The Code That Makes It All Work

For those brave enough to implement their own Twitter integration, here's my advice:

1. **Start with the environment variables**:
```bash
X_API_KEY=your_api_key
X_API_SECRET=your_api_secret
X_ACCESS_TOKEN=your_access_token  # Regenerate after permission changes!
X_ACCESS_TOKEN_SECRET=your_access_token_secret
```

2. **Check permissions three times**: Seriously. Read and write. Not just read.

3. **Test with single tweets first**: Don't try threading immediately. Make sure basic posting works.

4. **Log everything during development**: You'll thank yourself when debugging at 2am.

## The Bottom Line

Building Twitter/X integration taught me that the distance between "this should work" and "this actually works" is measured in underscores, permission checkboxes, and regenerated tokens. But when that first thread successfully posts, when you see your carefully crafted healthcare content reaching a wider audience with a single click—it's worth every debugging session.

The "Post Now" button works now. And yes, I've clicked it more than necessary just to watch it work. Don't judge me.

---

*Building PhysicianTechnologist has been a journey of small victories and memorable debugging sessions. If you're building your own platform or struggling with Twitter API integration, connect with me on [Twitter/X](https://x.com/technologistdoc) (where the threads now actually post) or [LinkedIn](https://linkedin.com/in/dr-chad-okay). I promise my response time is better than Twitter's API documentation.*

*Next up in the series: "Why I Decided to Build My Own Analytics Dashboard (Spoiler: Google Analytics Made Me Cry)"*

Part 5: Building PhysicianTechnologist - Twitter/X Thread Automation That Actually Works

## The Deployment: Where Theory Meets Reality

### Choosing Vercel: The Path of Least Resistance

The deployment decision took 30 seconds. I asked Claude where to deploy, it suggested Vercel for its Next.js optimisation and automatic CI/CD, and I agreed. Why overthink it when you could be shipping?

### The First Deploy: Everything Breaks

```bash
$ git push origin main
# Vercel: "Deployment failed"

Build Error:
- Type error in 14 files
- Missing environment variables
- Module not found: 'openai'
- RLS policies blocking everything
```

The localhost illusion shattered. Production is a different beast entirely.

### The Environment Variable Maze

What started as 5 environment variables in development somehow became 23 in production. Each one told a story of a feature added, an integration attempted, or a service adopted. The "simple blog" needed configurations for Supabase, OpenAI, Google Analytics, Vercel Analytics, email services, and more.

After 7 failed deployments, Claude and I worked through TypeScript errors from strict mode, missing API route exports, date serialisation issues in getStaticProps, dynamic imports breaking Edge runtime, and unused variables blocking the build. Forty-five minutes later, we finally saw "Deployment successful 🎉".

## Writing the First Blog Posts: Content Meets Platform

### The Irony of the Empty Blog

I had built semantic search with vector embeddings, an AI-powered chat interface, newsletter automation, an analytics dashboard, and a content recommendation engine. What I didn't have was content.

Writing the first post, "A GP Registrar's Journey with Heidi AI Scribe," revealed the platform's quirks. The markdown editor worked flawlessly and image uploads were seamless, but the status workflow required three clicks to publish. Embedding generation took 30 seconds. The newsletter queue triggered despite having zero subscribers. Related posts showed nothing because you need at least two posts for that feature to make sense.

My content creation workflow became a comedy of over-engineering. Write in Obsidian for the better markdown experience, copy to the platform editor, add metadata, save as draft, preview, submit for review to myself, approve as myself, publish, wait for embeddings, check if newsletter queued, realise I have no subscribers, question life choices.

### The 404 Mystery: When Production Diverges

Blog posts worked perfectly locally but returned 404 errors on production. Claude diagnosed it as a static generation issue - the posts existed in the database but weren't being built during deployment. Even with fallback: 'blocking' which should generate pages on-demand, it wasn't working. The solution? Force rebuild deployment. The reality? Next.js ISR is more complex than the documentation suggests.

## The Analytics Reality Check

Week 1 analytics painted a humbling picture: 3 visitors (all me), 147 page views (me testing), 0% bounce rate (I was very engaged with my own content), zero newsletter subscribers, and 23 search queries testing if search actually worked.

I had built analytics infrastructure that could handle thousands of concurrent users with real-time visitor tracking, geographic distribution maps, device breakdown charts, and Web Vitals monitoring. What I actually needed to know was simple: did anyone read my post?

## Maintenance Reality: The Hidden Costs

The daily development ritual became predictable. Run npm dev, get a module not found error, run npm install, get a port 3000 already in use error, kill the process, try again. Check production, find the Supabase free tier has paused the database. Restart everything.

The dependency updates grew exponentially. Month 1 brought 23 packages needing updates. Month 2 had 47. By Month 3, npm audit was screaming about 68 vulnerabilities, 2 critical. Running npm audit fix would break three components. Running it with --force would break everything. Git reset --hard HEAD became my most-used command.

## What's Next: The Roadmap to Sanity

The path forward is clear: simplification. Remove unused features, consolidate the sprawling API endpoints, eliminate the newsletter system until there are actual subscribers, and perhaps admit that vector search for single-digit blog posts is unnecessary.

Then comes optimisation - proper caching, monitoring and alerts, improved build times, and yes, finally adding those tests Claude kept suggesting. Eventually, the focus needs to shift to what actually matters: creating content, building an audience, and only re-enabling features when they're genuinely needed.

The dream, perhaps foolishly, is to eventually open source this over-engineered platform as "BlogOS" - a cautionary tale and learning resource. Help others avoid my mistakes, or at least make different ones.

## If I Started Over Today

Knowing what I know now, I'd keep Next.js with TypeScript as the foundation, Supabase despite its complexity, and the CLAUDE.md pattern that made AI development so effective. The component library choices of Tailwind and Radix UI proved solid.

But I'd start with MDX files instead of a database, skip the vector search until hitting 50+ posts, use an existing newsletter service, implement simpler authentication with NextAuth.js, and eliminate the complex status workflow entirely. Most importantly, I'd focus on writing content instead of building features - platform development is just sophisticated procrastination.

## The Technical and Personal Lessons

The technical lessons were valuable but predictable. Over-engineering is surprisingly easy when building is frictionless. Production behaves nothing like development. Simple features hide complex edge cases. Type safety genuinely pays dividends. Documentation, however boring, is crucial.

The AI collaboration lessons were more nuanced. Claude Code is an incredible accelerator, but acceleration without direction just gets you lost faster. It suggests what's possible, not what's necessary. Human judgment remains absolutely irreplaceable, and perhaps most interestingly, the tool shapes the solution in ways you don't expect.

The personal lessons hit harder. Building is addictive - there's always one more feature to add. Shipping is scary - suddenly your code faces reality. Perfect is genuinely the enemy of done. Users don't care about your elegant architecture or clever abstractions. And despite all the technology, content is still king.

## The Unexpected Success: Learning in Public

The real value wasn't the platform itself but the journey of building it. This blog series about building the blog has resonated more than the blog ever could. The honest discussion of over-engineering, real code examples, admission of mistakes, and the human side of AI collaboration - these stories connect with developers facing similar challenges.

## Final Reflections: Was It Worth It?

Financially? Absolutely not. I spent hundreds of hours building a free blog platform that already exists in dozens of forms.

Educationally? Without question. I learned modern web development patterns, database design principles, AI collaboration techniques, deployment realities, and most importantly, the value of shipping over perfecting.

Professionally? Yes. Every skill gained is immediately applicable to real projects.

Personally? It's complicated. The satisfaction of building something from scratch is real and valuable. But so is the maintenance burden that follows you forever.

## The Claude Code Verdict

Claude Code is revolutionary, but it's not magic. It excels at rapid prototyping, learning new technologies, handling boilerplate, refactoring existing code, and solving specific technical problems.

It struggles with knowing when to stop adding complexity, understanding actual business needs, maintaining simplicity, making strategic decisions, and designing user experiences that make sense to humans rather than machines.

## The Future of PhysicianTechnologist

The platform exists. It works. It's absurdly over-engineered for a personal blog. But it's mine.

Moving forward, the focus shifts to content creation - the platform is done, or at least done enough. I'll simplify gradually, removing complexity as I go. These technical posts about the building process seem to resonate, so I'll continue sharing the journey. Building in public creates unexpected connections. And hopefully, I can help others learn from my elaborate mistakes.

## Closing Thoughts: The Beauty of Building

There's something beautiful about building something unnecessarily complex. It's not efficient or practical, but it's deeply satisfying. I built a platform that could handle millions of users for an audience of dozens. I implemented enterprise patterns for a personal blog. I automated everything for an audience of one.

But I learned. I grew. I shipped. And in the end, that's what matters.

---

## Epilogue: A Message to Future Builders

If you're considering building with Claude Code or any AI assistant, start small - you can always add complexity later. Ship early because perfect doesn't exist. Document everything because your future self will thank you. Embrace mistakes as the best teachers. And most importantly, have fun - if you're not enjoying it, why build?

The tools will get better. The AI will get smarter. But the fundamental challenge remains: knowing what to build, not how to build it.

Choose wisely. Build boldly. Ship regularly.

And when you inevitably over-engineer something, write about it. Others will learn from your journey too.

---

*Thank you for following this journey. If you're building something with AI assistance, I'd love to hear about it. Reach out via [contact](/contact) or connect on [LinkedIn](https://www.linkedin.com/in/dr-chad-okay/).*

---

### Navigate This Series

**← Previous: [Part 3: Claude Code Acceleration and Development](/blog/building-physiciantechnologist-part-3-acceleration)**

---

**The Complete Series:**
- [Part 1: Discovery and Initial Learning](/blog/building-physiciantechnologist-part-1-discovery)
- [Part 2: Architecture Decisions and Database Design](/blog/building-physiciantechnologist-part-2-architecture)
- [Part 3: Claude Code Acceleration and Development](/blog/building-physiciantechnologist-part-3-acceleration)
- Part 4: Deployment, First Posts, and Future Vision (You are here)

**Resources:**
- [GitHub Repository](#) (Coming soon - needs cleanup first)
- [Platform Architecture Diagram](#)
- [CLAUDE.md Template](#)
- [Over-Engineering Anonymous Support Group](#) (I should start one)

Part 4: Building PhysicianTechnologist - Deployment and Future Vision

# Deep Dive into Digital Clinical Safety - Navigating DCB0160 from Scratch

Back in March, I was waiting for templates from our ICB and beginning to understand what DCB0160 actually demanded of us. What I discovered over the following weeks in April 2025 was that this wasn't just another box-ticking exercise. It was a fundamental shift in how we needed to think about digital safety in primary care.

## Understanding DCB0160: More Than Just Compliance

Let me start with the basics. DCB0160 is the Clinical Risk Management standard that's legally mandated under Section 250 of the Health and Social Care Act 2012. If you're deploying any health IT system that processes patient data in the NHS, this applies to you. No exceptions.

The critical insight here is that DCB0160 works hand-in-hand with DCB0129. While DCB0129 requires the software manufacturer to assess risks in their product, DCB0160 demands that we, the deploying organisation, conduct our own risk assessment specific to how we'll actually use that system. We needed to localise every risk assessment to our specific practice environment, workflows, and patient population.

## The Clinical Safety Officer Challenge - Solved by NCL ICB

The first major relief came when we discovered that the NCL ICB provided CSO support through their dedicated team. Dr Ode Omohwo, as Principal Clinical Safety Officer, and Sithabile Tshabalala had already established processes for supporting practices like ours. This solved what could have been an insurmountable hurdle. Without this support, individual practices would have needed to identify, train, and maintain their own CSO, requiring specialised training that takes days to complete.

However, this didn't absolve us of responsibility. We still needed to work closely with the ICB's CSOs, providing practice-specific context and maintaining our local safety documentation. The CSOs could guide and validate our approach, but the practice remained accountable for understanding and managing our specific risks.

## Beyond the Supplier Documentation

Here's where it got challenging. The supplier provided us with their DCB0129 clinical safety case report and hazard log. But DCB0160 requires us to look beyond their generic risk assessment and consider how their identified hazards apply in our specific context.

Working with the ICB's CSO, I spent three days going through their documentation, identifying which hazards were referred to us and what additional controls we needed. For example, their hazard log identified risks around system unavailability, but we needed to assess what backup procedures we had in place specifically for our practice workflow.

## The Documentation Trinity: CRMP, CSCR, and Hazard Log

The process involved creating our own localised versions of three key documents:

**Clinical Risk Management Plan (CRMP)**: This became our framework document, defining how we approach clinical safety in our practice, covering our governance structure, roles and responsibilities, and incident management processes. The critical element was making it practice-specific - not just copying templates.

**Clinical Safety Case Report (CSCR)**: This is your evidence that the system is safe for deployment in your environment. This had to demonstrate that we had systematically considered all hazards and implemented appropriate controls.

**Hazard Log**: This living document required the most time, and ongoing maintenance. Every potential source of patient harm needs to be documented, risk-scored, and controlled.

## Working Through the ICB's Identified Hazards

The NCL ICB's Clinical Safety Case Report identified four key hazards that every practice needed to address:

**H-001: Misinterpretation of Clinical Information** - Risk that the AI might misinterpret speech or medical terminology, potentially leading to incorrect diagnosis or treatment. The ICB scored this as moderate to significant risk.

**H-002: Wrong Patient Record** - Risk that information could be applied to the incorrect patient record. The ICB emphasised that this could have catastrophic consequences.

**H-003: Sub-optimal Care Due to Missing Information** - Risk that the AI might fail to capture vital clinical observations not verbalised, such as BP readings, non-verbal cues, or body language.

**H-004: Inappropriate Sharing of Sensitive Information** - Risk that sensitive or safeguarding information could be inappropriately included in generated letters.

For each hazard, the ICB had developed specific mitigations focusing on mandatory clinician review, proper training, and clear protocols. The key message was consistent: clinicians must review all AI outputs as they remain professionally and legally liable for accuracy.

## The Time Investment Reality

Let me be specific about the time this actually took. For our practice implementing Heidi AI Scribe, working with NCL ICB support:

- Initial consultation with ICB CSO: 1 day
- Document review and analysis: 3 days
- CRMP development (using ICB templates): 2 day
- CSCR creation (localising ICB templates): 4 days
- Hazard log development (adapting ICB version): 4 days
- Staff training delivery: 1 day

**Total initial investment: Approximately 15 days of clinical time**

This was significantly less than it would have been without ICB support - their templates and guidance saved us weeks of work. The ICB CSOs had already completed the heavy lifting of initial risk assessment and documentation structure.

## Practical Advice for GPs Starting This Journey

**Start early**: Don't wait until go-live is imminent. The DCB0160 process takes weeks, not days.

**Engage with your ICB's CSO early**: They're a valuable resource, but they're also supporting multiple practices. Book your consultations' "AI Clinics" well in advance.

**Focus on your context**: Generic templates won't suffice. Every hazard needs to be considered for your specific practice circumstances.

**Document everything**: The standard requires evidence of your risk management process, not just the outcomes.

**Plan for maintenance**: This isn't a one-time activity. Budget for ongoing safety management time.

The steep learning curve was real, but by the end of April 2025, I could see how this systematic approach to clinical safety was making us a more thoughtful, safer practice. The investment in time and expertise was significant, but the patient safety benefits were becoming clear.

---

*This is Part 2 of a 6-part series documenting the implementation of Heidi AI Scribe in NHS primary care. [← Part 1: The Starting Line](/blog/gp-heidi-ai-scribe-nhs-part-1-starting-line) | [Part 3: Data, DPIAs, and the Accountability Trap →](/blog/gp-heidi-ai-scribe-nhs-part-3-dpia)*

Part 2: GP Journey with Heidi AI - Navigating DCB0160

## The Claude Code Discovery: From Scepticism to Evangelism

My journey with Claude Code began with healthy scepticism. Another AI tool promising to revolutionise development? I'd tried GitHub Copilot, ChatGPT, and various IDE plugins. They were helpful, but hardly revolutionary.

Then I asked Claude Code to "create a blog post management system with draft/publish workflow" and watched it generate complete CRUD API endpoints, TypeScript interfaces, database migrations, React components with proper state management, input validation schemas, error handling, loading states, and optimistic updates.

All in about 3 minutes. And it worked. First try.

## The Development Workflow That Emerged

### The CLAUDE.md File: Your AI's Memory

The game-changer was discovering the CLAUDE.md pattern - a single file that becomes Claude's understanding of your project. It contains your project overview, coding standards, architecture principles, common issues and solutions. This file became the project's living documentation and Claude's context. Every session starts with Claude reading this file, instantly understanding project conventions, past decisions, and current issues.

It's like having detailed handover notes that actually get read.

### The Typical Development Session

Here's how a real feature implementation went. I asked for a newsletter system that automatically sends new posts to subscribers. Claude read the CLAUDE.md file, then created a newsletter_subscribers table with proper UK spelling, added a post_notifications queue table, implemented database triggers for automatic queuing, created the API endpoint with our standard response format, added admin UI for managing subscribers, implemented rate limiting and retry logic, created unsubscribe tokens with JWT, added GDPR compliance features, and documented everything back in CLAUDE.md.

"That's... comprehensive. But I have no subscribers," I pointed out.

"The infrastructure is ready for when you do," Claude replied.

Can't argue with that logic.

### The Speed Multiplication Effect

Traditional development of the newsletter feature would have taken 2-3 days. With Claude Code, it took 45 minutes. But here's the honest breakdown: initial implementation was 15 minutes, adding "proper" error handling was 10 minutes, implementing the queue system was another 10, adding admin dashboard was 10 more. Then debugging why it wasn't working took 2 hours. Realising we forgot to enable the trigger took 5 seconds. Face-palming took another minute.

## The Magical Moments

### The Migration System That Wrote Itself

I mentioned we needed to track schema versions. Claude implemented an entire migration system with rollback capability. When I asked if it could be simpler, Claude responded: "This is the simple version. The complex version includes automatic conflict resolution, dependency graphs, and parallel execution."

Fair enough.

### The Bug That Fixed Itself

The posts weren't showing on production. Claude immediately diagnosed three issues: SSR was disabled in pages/index.tsx, date serialisation was broken in getStaticProps, and there was an author field mismatch (the database had 'name' but the code expected 'full_name'). Claude fixed bugs I didn't even know existed. It was like having a code review from someone who actually read the entire codebase.

### The Refactor That Actually Improved Things

The API code was getting messy. Claude refactored 22 endpoints in one go, extracting common patterns, adding consistent error handling, implementing a middleware pipeline, maintaining backward compatibility, updating all imports, and fixing 4 unrelated bugs found during refactoring.

This is the refactoring you dream about but never have time for.

## The Frustrating Realities

### The Over-Abstraction Trap

I wanted a simple email function. What Claude built was an enterprise-grade EmailService class with dependency injection, retry logic, transaction support, and logging decorators. Sometimes you just want to send an email, not architect a messaging platform.

### The Context Window Shuffle

Working with large files became a dance. Claude couldn't see the entire file, so I'd copy lines 500-700, then lines 300-500 for context, then the type definitions. It was like trying to explain a movie plot to someone who can only watch 30 seconds at a time.

### The Inconsistency Surprises

Monday's Claude wrote clean, simple, functional code. Wednesday's Claude created enterprise-grade abstractions for the same problem. It's like pair programming with someone who has multiple personalities, each with different opinions about software architecture.

## The Acceleration Techniques That Worked

### Prompt Engineering for Consistency

Bad prompts like "Add search functionality" led to chaos. Good prompts specified everything: "Add search functionality following our existing patterns - use our standard APIResponse format, add to pages/api/ not app directory, use withAdminAuth middleware for protected routes, include Zod validation, follow UK spelling conventions."

The more specific, the better the result.

### The TODO List Pattern

Claude Code's TodoWrite tool became essential for maintaining context across long sessions. It wasn't just organisation - it helped Claude remember what we were building and why.

### The MCP Integration

Direct database access through MCP Supabase changed everything. Instead of guessing about data structure, Claude could query the actual database, check what's published, verify schema, and test queries directly. No more "I think the field is called..."

## The 3 AM Debugging Session That Changed Everything

It was 3 AM. The production site was showing a white screen. The error: "Cannot read property 'split' of undefined".

Traditional debugging would have taken hours. With Claude, it took 2 minutes. Claude immediately identified the issue: "Based on the error and the codebase, this is likely in the author name parsing. In three files, you're calling author.full_name.split(' ') but the database field is 'name', not 'full_name'."

Fixed in 2 minutes. This moment crystallised the value: Claude Code doesn't just write code - it understands your entire system.

## The Productivity Metrics

I wrote about 2,000 lines of code. Claude wrote about 18,000. We kept about 12,000. Originally planned 5 features, actually built 23, actually needed 8, but glad I have 15.

Database schema design was 80% faster. API implementation was 90% faster. UI components were 70% faster. Debugging was 60% faster. Documentation actually got written, which is 100% more than usual.

## The Workflow Anti-Patterns to Avoid

Don't blindly accept every suggestion - Claude sometimes creates solutions for problems that don't exist. Don't switch between tasks constantly - it confuses Claude. Finish one feature before starting another. And know when to stop - Claude will keep improving code forever if you let it.

## Reflections on AI-Accelerated Development

Claude Code excels at boilerplate generation, pattern recognition, error detection, documentation, and refactoring. You'll never write another CRUD endpoint manually. It maintains consistency across codebases and spots bugs while adding features.

What still needs human judgment? Architecture decisions about when to stop abstracting. Feature prioritisation - what actually needs building. Performance optimisation - Claude loves unnecessary complexity. User experience - AI doesn't understand human frustration. Business logic - the "why" behind the "what."

### The Unexpected Benefit: Learning

Claude Code became my mentor. Every generated solution taught me something: new TypeScript patterns I hadn't seen, PostgreSQL features I didn't know existed, React hooks I'd never used, security considerations I'd overlooked.

## The Development Speed Paradox

I built features 10x faster, but the project took the same time. Why? Because I built 10x more features. The acceleration didn't reduce development time - it expanded scope. Every saved hour became an opportunity for "just one more feature."

It's like giving a shopaholic a faster credit card.

---

*Next in Part 4: The deployment saga, writing the first blog posts, the reality of maintaining an over-engineered blog, and the roadmap for simplification. Plus, what I'd do differently if starting over today.*

---

### Navigate This Series

**← Previous: [Part 2: Architecture Decisions and Database Design](/blog/building-physiciantechnologist-part-2-architecture)**

**→ Next: [Part 4: Deployment, First Posts, and Future Vision](/blog/building-physiciantechnologist-part-4-deployment)**

---

**The Complete Series:**
1. [Part 1: Discovery and Initial Learning](/blog/building-physiciantechnologist-part-1-discovery)
2. [Part 2: Architecture Decisions and Database Design](/blog/building-physiciantechnologist-part-2-architecture)
3. **Part 3: Claude Code Acceleration and Development** (You are here)
4. [Part 4: Deployment, First Posts, and Future Vision](/blog/building-physiciantechnologist-part-4-deployment)

Part 3: Building PhysicianTechnologist - Claude Code Acceleration

# A GP Registrar's Journey Implementing Heidi AI Scribe in NHS Primary Care: Part 1 - The Starting Line

## Vision, Vacuum, and the 'Hidden Workload'

*March 2025. Standing in my North Central London practice during my lunch break, staring at another mountain of extra patient notes that I needed to correct, another that I need to add, and telephone consultation notes that I needed to transcribe, I made a decision that would fundamentally change how we deliver care and reveal just how unprepared our healthcare system is for the AI revolution.*

The statistics are damning, and I was experiencing their effects. Research shows that GPs suffer from minor psychiatric disorders, with most experiencing mild to severe exhaustion. I was part of those statistics, spending hours each day on documentation instead of patient care, burning out alongside my colleagues. Despite all the technological advancements, medicine at times still seems to be living in dark ages. My mind was clear that something had to change.

That's when I encountered **Heidi AI Scribe**. The promise was compelling: real-time consultation transcription, automated clinical note generation, and the ability to focus entirely on my patients instead of typing while they spoke. But as I would soon discover, the path from vision to implementation was filled with regulatory requirements that no one had adequately prepared us for.

## The Regulatory Vacuum of March 2025

In March 2025, we existed in what I can only describe as a regulatory vacuum. The technology was ready, our patients needed better care, and GPs were drowning in an administrative burden. But formal guidance from NCL ICB (North Central London Integrated Care Board) wasn't yet fully developed. The comprehensive 11-step guidance that practices now rely on was still months away from publication.

This left us, like many early adopter practices, navigating uncharted waters. We knew we needed to implement AI scribes responsibly, but the question was: **how do you comply with regulations that haven't been clearly articulated for your specific use case?**

I reached out directly to Clinical Safety Officers across our region, trying to understand the scope of what we were taking on. What I discovered was that while NCL ICB had Clinical Safety Officers like Dr Ode Omohwo and Sithabile Tshabalala who could provide support, the specific processes and templates for AI scribe implementations weren't yet established. We were all learning together.

## The Compliance Reality Check

The first shock came when I learned about **DCB0160** – the Clinical Risk Management standard that's mandatory under the Health and Social Care Act 2012. This wasn't optional guidance; it was law. Every healthcare organisation deploying digital health technology must comply with DCB0160, which means:

- **Working with a qualified Clinical Safety Officer** (fortunately, NCL ICB provided this support, though many practices didn't initially know it was available)
- **Conducting comprehensive clinical risk assessments**
- **Maintaining hazard logs** throughout the technology's lifecycle
- **Producing clinical safety case reports**
- **Establishing ongoing clinical risk management processes**

Understanding how to access ICB Clinical Safety Officer support became our first challenge. These professionals were in high demand, and the process for engaging with them wasn't yet streamlined.

## The DPIA Discovery

Then came the **Data Protection Impact Assessment (DPIA)** requirement. Under UK GDPR, AI systems processing special category data (like health information) on a large scale require a comprehensive DPIA before implementation. This isn't a one-time tick-box exercise. It's a living document that must be maintained throughout the AI system's deployment.

The DPIA process revealed the complexity of what we were undertaking:

- **Detailed analysis** of the purpose and methods of data processing
- **Assessment** of necessity and proportionality
- **Identification** of risks to patients' rights and freedoms
- **Documentation** of mitigation measures
- **Consultation** with relevant stakeholders

What should have been a straightforward software deployment suddenly required legal, technical, and clinical expertise. While NCL ICB's Data Protection Officer Steve Durbin would eventually provide templates and support, in March 2025 these resources were still being developed.

## DTAC: The Hidden Compliance Layer

The third major requirement was **Digital Technology Assessment Criteria (DTAC)** compliance. While not legally mandated, DTAC has become the de facto standard for any digital health technology used in the NHS. The assessment covers five critical areas:

1. **Clinical Safety** (including DCB0129/0160 compliance)
2. **Data Protection** (GDPR compliance and security measures)
3. **Technical Security** (including Cyber Essentials certification)
4. **Interoperability** (system integration capabilities)
5. **Usability and Accessibility** (ensuring the technology works for all users)

Each area requires detailed evidence and documentation. For a small GP practice, assembling this portfolio of evidence represents months of work across multiple domains of expertise.

## The Unfunded Mandate Reality

Here's the uncomfortable truth that no one talks about openly: implementing AI scribes responsibly represents a massive **unfunded mandate**. The NHS expects practices to adopt innovative technologies to improve efficiency and patient care, but provides no additional funding for the substantial compliance work required.

## The Hidden Workload

Beyond the direct costs lies what I call the **'hidden workload'**. This is the ongoing administrative burden that compliance creates:

- Every system update requires clinical safety review
- Every process change needs DPIA amendment
- Every incident needs documentation and reporting through multiple channels

What was supposed to reduce administrative burden initially created more of it.

Yet despite these challenges, I would make the same decision again. The patient benefits such as more engaged consultations, improved documentation quality, reduced GP burnout, justify the compliance investment. But we must be honest about what implementing AI responsibly actually requires.

## Looking Forward

As I write this in August 2025, NCL ICB has since published comprehensive guidance, creating a clearer pathway for practices wanting to implement AI technologies. The 11-step framework now available would have saved us months of work and uncertainty.

But our experience as early adopters has taught me valuable lessons about the reality of healthcare innovation in 2025. The technology is ready, the clinical need is urgent, but our regulatory and funding structures haven't caught up with the pace of change.

The starting line for AI in primary care isn't just about choosing the right technology. It's about accepting that responsible implementation requires significant investment in compliance infrastructure that the system doesn't yet adequately support or fund.

---

*This is Part 1 of a 6-part series documenting the implementation of Heidi AI Scribe in NHS primary care. [Continue to Part 2: Deep Dive into Digital Clinical Safety →](/blog/gp-heidi-ai-scribe-nhs-part-2-dcb0160)*

Part 1: GP Journey with Heidi AI - The Starting Line

## The Stack Selection: Analysis Paralysis Resolved

Choosing the tech stack with Claude Code was like having a very opinionated architect who'd built everything before. I suggested React with a simple Express backend. Claude countered with Next.js 15.4, TypeScript strict mode, Supabase for the backend, Tailwind for styling, Radix UI for components, React Query for state management, and Zod for validation.

"That seems like a lot for a blog," I said.

Claude proceeded to implement the entire stack in 30 minutes. Sometimes it's easier to just let the expert drive.

### The Final Stack (and Why)

The package.json became a monument to modern web development. Next.js for SSR/SSG and API routes. React 18 because, well, React. TypeScript with strict mode because Claude absolutely refused to write JavaScript. Supabase brought PostgreSQL with auth and real-time features I'd never use. Tailwind and Radix UI made everything look professional without effort. React Query and Zod handled data fetching and validation like adults.

Then came the kitchen sink: OpenAI integration for semantic search, markdown rendering, reading time calculations ("5 min read" for every post regardless of length), and 47 other dependencies I'm still discovering.

```typescript
// The "simple blog" dependency count
{
  "dependencies": {
    // ... 50+ packages
  }
}
```

## The Database That Grew Like a Garden

### Evolution of the Schema

The database started innocently. Day 1 was a naive posts table with id, title, content, and created_at. Simple. Clean. Wrong.

By week 3, I had a monster with 8 interconnected tables. Posts grew to 12 columns. Authors exploded to 19 columns including JSONB fields for flexibility. Post notifications, content embeddings, search queries, and migration tracking tables appeared like mushrooms after rain.

### The Over-Engineering Hall of Fame

#### The Status Workflow System

What could have been a simple boolean for published/unpublished became a complex state machine with draft, pending_review, published, and archived statuses. Plus three timestamp fields to track the journey: published_at, first_published_at (which never changes after first publish), and newsletter_sent_at (to prevent duplicate sends).

This seemed excessive until I accidentally published a draft at 2 AM. The status workflow saved me from explaining why my half-written thoughts on AI ethics were suddenly public.

#### Vector Embeddings for 6 Blog Posts

The crown jewel of over-engineering: implementing pgvector for semantic search on a blog with single-digit posts. I'm doing cosine similarity searches with OpenAI embeddings on six blog posts. A simple full-text search would have sufficed. Hell, Ctrl+F would have sufficed.

```sql
CREATE TABLE content_embeddings (
  embedding vector(1536),  -- OpenAI ada-002 dimensions
  -- ... for 6 posts
);
```

But here's the thing - when I have 600 posts (optimistic, I know), this architecture won't need changes. The "Related Posts" feature works surprisingly well, even if it's just choosing between 5 other posts.

### The Database Decisions That Paid Off

#### Soft Deletes Everywhere

Instead of actually deleting anything, everything gets a deleted_at timestamp. This saved me when I accidentally "deleted" the wrong author. One SQL update and they were back from the digital grave.

#### JSONB for Flexible Fields

Author specialties, education, and social links all use JSONB fields. No schema migrations needed when adding new social platforms or specialty types. It's like NoSQL and SQL had a baby, and it's beautiful.

#### Trigger-Based Automation

Database triggers automatically queue posts for embedding generation and newsletter sending when published. Even if the API fails, the database maintains consistency. It's like having a really pedantic assistant who never forgets anything.

## The API Layer: Where Standards Met Reality

### The Standard Response Format (A Love-Hate Story)

Claude Code insisted on standardising all API responses with success flags, data payloads, error objects with codes and messages, and metadata including timestamps and request IDs. Every. Single. Endpoint.

The good: predictable client-side handling and consistent error patterns. The bad: verbose for simple endpoints and metadata that's mostly noise. The request ID has never been used for debugging, but it's there, waiting for its moment to shine.

### The Authentication Middleware Pattern

What started as simple auth checking evolved into 47 lines of token validation, role checking, session management, and refresh logic. The middleware became so complex it probably needs its own documentation. Or therapy.

## The Supabase Decision: Why Not Just PostgreSQL?

### What I Gained

Instant auth saved weeks of development. The built-in REST API meant direct database access from the frontend (scary but convenient). Row Level Security provided database-enforced access control. And most importantly, no DevOps required - it just worked.

### What I Lost

Flexibility disappeared - you do things the Supabase way. Cost predictability went out the window as it scales with usage. Local development requires an internet connection, making plane coding impossible. And debugging RLS policies is like debugging quantum mechanics - you're never quite sure what's happening until you observe it.

### The RLS Policies That Nearly Broke Me

It started simple enough: "Authors can edit own posts." Then came "Public can view published posts" and "Admins can do anything" and fifteen other policies that interact in ways I still don't fully understand.

```sql
-- The nightmare: debugging why a post won't update
-- Answer: RLS policy was checking the wrong field
-- Time to figure this out: 3 hours
```

## Reflections on Architecture

What was done well? Type safety everywhere eliminated runtime errors. Database-first design means business logic is portable. Standardised patterns make the code maintainable, if verbose. The architecture could handle 100x growth, though 100x of zero is still zero.

What's over-engineered? Vector search for 6 posts is like using a sledgehammer for a thumbtack. Complex status workflows could have been a boolean. API metadata on every response is rarely useful. The newsletter queue system serving exactly zero subscribers.

What's under-engineered? No tests despite Claude writing test specs constantly. No monitoring, so I find out about errors from users (all three of them). No caching strategy means every request hits the database. No backup system beyond trusting Supabase completely.

## The Architecture's Hidden Gem: The Migration System

The unsung hero is the migration system with self-documenting, versioned, reversible migrations. Every schema change is tracked, documented, and can be undone. This saved me during the "great author table refactor of March 2025" when I discovered that changing a primary key is harder than it looks.

```sql
CREATE TABLE schema_migrations (
  version VARCHAR(255) PRIMARY KEY,
  rollback_sql TEXT  -- Can undo any migration!
);
```

---

*Next in Part 3: I explore the Claude Code development workflow, the magic of AI-assisted coding, the moments of brilliance, the frustrating bugs, and how I went from idea to implementation in record time. Plus, the story of the 3 AM debugging session that made me question everything.*

---

### Navigate This Series

**← Previous: [Part 1: Discovery and Initial Learning](/blog/building-physiciantechnologist-part-1-discovery)**

**→ Next: [Part 3: Claude Code Acceleration and Development](/blog/building-physiciantechnologist-part-3-acceleration)**

---

**The Complete Series:**
1. [Part 1: Discovery and Initial Learning](/blog/building-physiciantechnologist-part-1-discovery)
2. **Part 2: Architecture Decisions and Database Design** (You are here)
3. [Part 3: Claude Code Acceleration and Development](/blog/building-physiciantechnologist-part-3-acceleration)
4. [Part 4: Deployment, First Posts, and Future Vision](/blog/building-physiciantechnologist-part-4-deployment)

Part 2: Building PhysicianTechnologist - Architecture and Database Design

## The Genesis: Why Another Blog Platform?

In March 2025, I found myself at a crossroads. As a physician-technologist passionate about clinical AI, I needed a platform to share insights about implementing AI in NHS settings. Medium felt too generic. WordPress too bloated. Ghost too expensive for what I needed. I wanted something that felt *mine* - a platform that could grow with my needs, showcase technical depth, and still be approachable for healthcare professionals.

Enter Claude Code - Anthropic's coding assistant that promised to accelerate development. Little did I know this would transform from a simple blog project into a masterclass in AI-assisted development, over-engineering, and the art of knowing when to stop.

## The Initial Vision vs Reality

### What I Thought I Was Building

A simple blog with markdown support, basic author profiles, maybe some search functionality. Deploy and forget. The usual developer fantasy of a weekend project that stays a weekend project.

### What I Actually Built

Instead, I ended up with a full-featured CMS with role-based access control, AI-powered semantic search with vector embeddings, automated newsletter system with queue management, real-time analytics dashboard, content recommendation engine, and UK-localised healthcare platform with NHS compliance considerations.

The scope creep was real, but each addition taught valuable lessons about modern web development and AI collaboration.

## First Steps: Learning Claude Code's Personality

Working with Claude Code felt different from traditional development or even GitHub Copilot. It wasn't just autocomplete on steroids - it was like having a senior developer who remembered context across sessions through the CLAUDE.md file, made architectural decisions (sometimes brilliant, sometimes overengineered), had strong opinions about TypeScript, testing, and code organisation, and could refactor entire systems with surprisingly few mistakes.

### The Learning Curve

The first week was humbling. I'd ask for a "simple blog post component" and receive a fully typed React component, Zod validation schemas, API endpoint with standardised error handling, database migrations, RLS policies for Supabase, and test specifications that we never actually implemented.

Initially overwhelming, but I learned to embrace the thoroughness. Claude Code wasn't just writing code - it was teaching best practices by example.

## Early Challenges: The "Simple" Blog Post

Creating the first blog post functionality revealed the complexity beneath simplicity.

### Challenge 1: State Management Confusion

My initial approach was the classic useState and useEffect combo. Fetch posts, set state, render. Simple, right?

```typescript
// My initial approach
const [posts, setPosts] = useState([]);
useEffect(() => { fetchPosts() }, []);
```

Claude suggested React Query with server-side rendering instead:

```typescript
// Claude's suggestion - React Query with SSR
const { data: posts = initialPosts } = useQuery({
  queryKey: ['posts'],
  queryFn: postsQueries.all,
  initialData: initialPosts, // From getServerSideProps
  staleTime: 5 * 60 * 1000,
});
```

The shift from basic state management to React Query with server-side rendering was enlightening. Suddenly I had automatic caching, background refetching, optimistic updates, and proper loading states. It was like upgrading from a bicycle to a Tesla - overwhelming at first, but you quickly wonder how you lived without it.

### Challenge 2: The Database Migration Dance

What started as a simple posts table evolved into something much more complex. Version 1 had three columns: id, title, and content. By version 8, we had 12 columns including slug management, status workflows, publication timestamps, and newsletter tracking fields.

```sql
-- Version 8: Reality
CREATE TABLE posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  content TEXT NOT NULL,
  excerpt TEXT,
  image TEXT,
  status TEXT CHECK (status IN ('draft', 'pending_review', 'published', 'archived')),
  author_id UUID REFERENCES authors(id),
  published_at TIMESTAMPTZ,
  first_published_at TIMESTAMPTZ,
  newsletter_sent_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
```

Each field told a story of a requirement discovered, a bug fixed, or a feature requested. The newsletter_sent_at field? Added after accidentally sending the same post three times. The first_published_at that never changes? Learned that one the hard way when republishing updated a post's publication date and broke the RSS feed chronology.

## The Authentication Rabbit Hole

"Just add simple authentication," I said. Three days later, I emerged with Supabase Auth integration, JWT token management, role-based access control with super_admin, editor, and author roles, Row Level Security policies that took hours to debug, protected API routes, session management, and auth middleware patterns.

Claude Code implemented authentication like it was building for a Fortune 500 company. Overkill? Perhaps. But when I needed to add contributor roles later, the infrastructure was already there. Sometimes over-engineering is just future-proofing in disguise.

## Key Learning: Embrace the Over-Engineering (Sometimes)

The platform is undeniably over-engineered for a personal blog. But this over-engineering taught me production patterns like error boundaries and proper logging, type safety that eliminated runtime surprises, scalability thinking with database indexes and caching strategies, and a security mindset around input validation and XSS protection.

## The UK Localisation Surprise

One of Claude Code's most impressive moments was handling UK localisation. When I mentioned the platform was for UK healthcare, it automatically implemented British English spelling throughout (authorised not authorized, organisation not organization), proper date formatting showing "1 March 2025" not "March 1, 2025", and even added references to NHS, GMC, and NICE guidelines in comments.

```typescript
// Automatically implemented throughout:
const formattedDate = new Date().toLocaleDateString('en-GB');
// "1 March 2025" not "March 1, 2025"
```

This attention to detail was beyond what I'd have thought to specify. It understood context in a way that felt almost human.

## Reflections on Part 1

Looking back at the first phase, the journey from "I need a blog" to "I have a CMS" was both exhilarating and exhausting. Claude Code pushed me to build better than I would have alone, but also more than I needed.

What worked was the rapid prototyping with immediate feedback, learning modern patterns through implementation, and having a "senior developer" available 24/7. What didn't work as well was Claude's occasional tendency toward unnecessary complexity, inconsistencies that required manual fixes, and the constant temptation to add "just one more feature."

The surprise? Building with Claude Code wasn't just about writing code faster. It was about discovering what's possible when you remove the friction between idea and implementation. The real challenge became knowing when to stop building and start shipping.

---

*Next in Part 2: I dive deep into architecture decisions, the database design that grew like a living organism, and why I chose Supabase over other solutions. Plus, the story of how vector embeddings entered a "simple blog" and why that actually made sense.*

---

### Navigate This Series

**→ Next: [Part 2: Architecture Decisions and Database Design](/blog/building-physiciantechnologist-part-2-architecture)**

---

**The Complete Series:**
1. **Part 1: Discovery and Initial Learning** (You are here)
2. [Part 2: Architecture Decisions and Database Design](/blog/building-physiciantechnologist-part-2-architecture)
3. [Part 3: Claude Code Acceleration and Development](/blog/building-physiciantechnologist-part-3-acceleration)
4. [Part 4: Deployment, First Posts, and Future Vision](/blog/building-physiciantechnologist-part-4-deployment)

**Stay tuned for:**
- Part 2: Architecture Decisions and Database Design
- Part 3: Claude Code Acceleration and Development Workflow
- Part 4: Deployment, First Posts, and Future Vision

---

### Navigate This Series

**→ Next: [Part 2: Architecture Decisions and Database Design](/blog/building-physiciantechnologist-part-2-architecture)**

---

**The Complete Series:**
1. **Part 1: Discovery and Initial Learning** (You are here)
2. [Part 2: Architecture Decisions and Database Design](/blog/building-physiciantechnologist-part-2-architecture)
3. [Part 3: Claude Code Acceleration and Development](/blog/building-physiciantechnologist-part-3-acceleration)
4. [Part 4: Deployment, First Posts, and Future Vision](/blog/building-physiciantechnologist-part-4-deployment)

All Posts

Part 6: GP Journey with Heidi AI - Lessons and Future

Part 5: GP Journey with Heidi AI - Roadmap to Go-Live

When Scrollytelling Breaks Mobile: A CSS Transform Detective Story

Agents vs Humans: When AI Assistants Save the Day (And When They Don't)

Part 4: GP Journey with Heidi AI - The MHRA Bomb

Part 3: GP Journey with Heidi AI - Data and DPIAs