📋 Prerequisites

• An AWS Account.
• A domain name managed on Cloudflare (we will use yourdomain.com as the example).
• Basic familiarity with DNS records.

Phase 1: Create Identity & DKIM Setup

To send emails as newsletter@yourdomain.com, you must prove to AWS that you own the domain.

1. Navigate to AWS SES:
2. Create Identity:

Phase 2: DNS Configuration (Cloudflare)

AWS will now provide you with CNAME records. These are the “handshake” that proves ownership and sets up DKIM (email signatures).

1. Get the Records:
2. Add to Cloudflare:
3. Add DMARC (Optional but Recommended):

Verification typically takes a few minutes, but can take up to 72 hours.

Phase 3: Configure Custom MAIL FROM Domain

By default, emails come from amazonses.com. To improve deliverability and look professional (e.g., mail.yourdomain.com), set up a custom MAIL FROM.

1. In AWS SES:
2. Update Cloudflare DNS:
3. Wait for Verification:

Phase 4: Get SMTP Credentials

To use tools like Listmonk, WordPress, or custom scripts, you need SMTP credentials (username/password), not your standard AWS login.

1. Generate Credentials:
2. Save Them Immediately:

Phase 5: Exiting the “Sandbox” (Production Access)

All new SES accounts start in “Sandbox Mode”.

• Restriction: You can only send 200 emails/day, and only to verified email addresses (your own).
• Goal: Move to Production to send to anyone.

1. Request Production Access:
2. Fill the Form (Best Practices):
3. Wait for Review: usually takes 24 hours.

Phase 6: Using Your Setup (Example: Listmonk)

Now that the infrastructure is ready, you can plug these details into any mailing software.

Example Configuration:

• SMTP Host: email-smtp.ap-southeast-2.amazonaws.com
• Port: 587
• Username: [Your SMTP Username from Phase 4]
• Password: [Your SMTP Password from Phase 4]
• Encryption: TLS or STARTTLS

💰 Cost Analysis (Free Tier)

AWS SES is highly cost-effective for developers:

• First 3,000 messages/month: Free (for the first 12 months).
• Thereafter: ~$0.10 per 1,000 emails.
• Data Transfer: Standard EC2 rates apply (negligible for text emails).

Your professional email infrastructure is now ready!

This document summarizes our experience integrating CopilotKit with LangGraph.js for Human-in-the-Loop (HITL) workflows. It covers critical bugs, failed approaches, and the final working solution.

Tech Stack:

• Frontend: Next.js 16, React 19, CopilotKit 1.x
• AI Runtime: CopilotKit SDK
• AI Agent: LangGraph.js 1.0
• Deployment: Vercel (frontend) + Railway (agent)

The Problem

When implementing HITL approval flows (e.g., user approves AI-generated content before proceeding), we encountered a critical incompatibility between CopilotKit and LangGraph.js.

Symptom

ZodError: [
  {
    "code": "invalid_type",
    "expected": "string",
    "received": "undefined",
    "path": ["toolCallId"],
    "message": "Required"
  }
]

Root Cause

Field naming mismatch between LangGraph.js and CopilotKit:

| Framework | Field Name | Format |

| — — — — — -| — — — — — -| — — — — |

| LangGraph.js / OpenAI | tool_call_id | snake_case |

| CopilotKit | toolCallId | camelCase |

When LangGraph.js creates a ToolMessage, it uses tool_call_id. When CopilotKit tries to parse the message, it expects toolCallId and fails with ZodError.

Failed Approaches

Approach 1: Add toolCallId dynamically

const toolMessage = new ToolMessage({
  content: result,
  name: toolName,
  tool_call_id: toolCall.id!,
});
// Try to add CopilotKit-compatible field
(toolMessage as any).toolCallId = toolCall.id!;

Result: FAILED

LangChain’s serialization mechanism ignores dynamically added properties. When the message is serialized for storage/transmission, only declared class fields are included.

Approach 2: Use emitMessages: false

const customConfig = copilotkitCustomizeConfig(config, {
  emitMessages: false  // Don't emit ToolMessage to frontend
});

Result: FAILED

emitMessages: false only prevents messages from being streamed during execution. The ToolMessage is still stored in LangGraph’s checkpointer and returned when CopilotKit fetches the state later.

Approach 3: Route back to chatNode after tool execution

function routeAfterTool(state) {
  if (toolCall.name === "generate_outline") {
    return "chat_node";  // Generate AIMessage to "consume" ToolMessage
  }
  return END;
}

Result: FAILED

The ToolMessage still exists in the conversation history. When CopilotKit reconstructs the history for subsequent requests, it parses all messages including the ToolMessage → ZodError.

Approach 4: State-only approach (no messages)

// Don't add any messages, only emit state
if (toolName === "generate_outline") {
  pendingContent = { type: "outline", content: result };
  // NO resultMessages.push() - avoid ToolMessage entirely
}
await copilotkitEmitState(config, { ...state, pendingContent });
return { pendingContent };  // No messages

Result: FAILED

OpenAI’s API requires that every tool_call must have a corresponding ToolMessage response. Without the ToolMessage, subsequent API calls fail:

Error: 400 An assistant message with 'tool_calls' must be followed by
tool messages responding to each 'tool_call_id'.

The Working Solution: Dedicated Graph Node

The solution is to completely bypass tool calling for HITL operations by using a dedicated graph node instead of a tool.

Architecture Comparison

Before (Tool-based — BROKEN):

User Request → chatNode → LLM calls tool → toolNode → ToolMessage → ZodError

After (Node-based — WORKS):

User Request → routeFromStart → isOutlineRequest? → outline_node → AIMessage → Success

Implementation

1. Create a detection function

function isOutlineRequest(state: FanficAgentState): boolean {
  // Check if we're in the outline step
  const context = extractContextFromReadable(state);
  const currentStep = state.wizardSession?.step || context?.step;

  if (currentStep !== "outline") {
    return false;
  }

  // Check if the message contains outline-related keywords
  const lastMessage = state.messages[state.messages.length - 1];
  if (!lastMessage || lastMessage._getType() !== "human") {
    return false;
  }

  const content = typeof lastMessage.content === "string"
    ? lastMessage.content.toLowerCase()
    : "";

  const outlinePatterns = [
    /write|create|make|generate|outline|story/i,
    /romance|adventure|action|drama/i,
  ];

  return outlinePatterns.some(p => p.test(content));
}

2. Create a dedicated node

async function outlineNode(
  state: FanficAgentState,
  config: RunnableConfig
): Promise<Partial<FanficAgentState>> {
  // Extract context from CopilotKit readable state
  const context = extractContextFromReadable(state);
  const sourceName = context?.sourceName || "Unknown";
  const characters = context?.characters || [];

  // Generate outline directly with LLM (no tool calling)
  const model = new ChatOpenAI({ model: "gpt-4o-mini" });
  const response = await model.invoke([
    new SystemMessage(buildOutlinePrompt(sourceName, characters)),
    new HumanMessage(userRequest),
  ]);

  const outlineContent = response.content as string;

  // Set pendingContent for HITL - frontend will detect this
  const pendingContent = {
    type: "outline" as const,
    content: outlineContent,
  };

  // Emit state for frontend HITL detection
  await copilotkitEmitState(config, { ...state, pendingContent });

  // Return AIMessage (NOT ToolMessage) - CopilotKit compatible
  return {
    messages: [new AIMessage({
      content: "I've created your story outline! Please review it above.",
    })],
    pendingContent,
  };
}

3. Update routing from START

function routeFromStart(state: FanficAgentState): string {
  // Check for research request first
  if (isResearchRequest(state)) {
    return "research_node";
  }

  // Check for outline request
  if (isOutlineRequest(state)) {
    return "outline_node";  // Skip chat_node entirely
  }

  // Default to chat node
  return "chat_node";
}

4. Add node to graph

const workflow = new StateGraph(FanficAgentStateAnnotation)
  .addNode("chat_node", chatNode)
  .addNode("tool_node", toolNode)
  .addNode("research_node", researchNode)
  .addNode("outline_node", outlineNode)  // NEW
  .addConditionalEdges(START, routeFromStart)
  .addConditionalEdges("chat_node", routeAfterChat)
  .addConditionalEdges("tool_node", routeAfterTool)
  .addConditionalEdges("research_node", routeAfterResearch)
  .addConditionalEdges("outline_node", routeAfterOutline);  // NEW

5. Remove tool from available tools

// tools/index.ts
// Exclude generateOutlineTool - handled by outline_node
export const allBackendTools = [
  continueStoryTool,
  expandSceneTool,
  polishProseTool,
  ...characterTools,
  ...imageTools,
  // generateOutlineTool - REMOVED
];

6. Frontend: Detect pendingContent with useCoAgentStateRender

// wizard/page.tsx
useCoAgentStateRender<{
  pendingContent?: { type: string; content: string } | null;
}>({
  name: "fanfic_agent",
  render: ({ state }) => {
    if (state?.pendingContent?.type === "outline" && state.pendingContent.content) {
      return (
        <OutlineApprovalCard
          outline={state.pendingContent.content}
          onApprove={() => handleOutlineApproved(state.pendingContent!.content)}
          onReject={(feedback) => console.log("Rejected:", feedback)}
          onEdit={(editedOutline) => handleOutlineApproved(editedOutline)}
        />
      );
    }
    return null;
  },
});

Key Takeaways

1. Avoid ToolMessage for HITL Operations

Rule: If an operation requires human approval before proceeding, do NOT implement it as a tool. Use a dedicated graph node instead.

Why: ToolMessage format is incompatible between LangGraph.js and CopilotKit. This is a known bug (see CopilotKit issue #2897).

2. Use State Emission for HITL Detection

Instead of relying on CopilotKit actions (useCopilotAction with renderAndWaitForResponse), use:

• copilotkitEmitState() on the backend to emit state with pendingContent
• useCoAgentStateRender() on the frontend to detect and render HITL UI

3. Pattern for Dedicated Nodes

When creating a dedicated node for HITL operations:

async function myHITLNode(state, config) {
  // 1. Extract context from CopilotKit readable state
  const context = extractContextFromReadable(state);

  // 2. Perform the operation directly (no tool calling)
  const result = await performOperation(context);

  // 3. Set pendingContent for frontend detection
  const pendingContent = { type: "myType", content: result };

  // 4. Emit state to frontend
  await copilotkitEmitState(config, { ...state, pendingContent });

  // 5. Return AIMessage (not ToolMessage)
  return {
    messages: [new AIMessage({ content: "Please review above." })],
    pendingContent,
  };
}

4. CopilotKit Readable Context Format

CopilotKit’s useCopilotReadable stringifies values with JSON.stringify(). On the backend, you must parse them:

function extractContextFromReadable(state) {
  const copilotState = state.copilotkit;

  if (copilotState?.context?.length > 0) {
    const contextItem = copilotState.context[0];

    // Value is a JSON string, not an object
    if (typeof contextItem.value === "string") {
      try {
        return JSON.parse(contextItem.value);
      } catch {
        return null;
      }
    }
  }
  return null;
}

5. Graph Routing Pattern

For HITL operations, route from START directly to the dedicated node:

function routeFromStart(state) {
  if (isResearchRequest(state)) return "research_node";
  if (isOutlineRequest(state)) return "outline_node";
  if (isImageRequest(state)) return "image_node";
  return "chat_node";  // Default for regular conversation
}

Summary Table

| Operation Type | Implementation | Message Type | HITL Detection |

| — — — — — — — -| — — — — — — — — | — — — — — — — | — — — — — — — — |

| Regular chat | chat_node | AIMessage | N/A |

| Tool execution | tool_node | ToolMessage | ❌ Avoid for HITL |

| Research | research_node | AIMessage | useCoAgentStateRender |

| Outline | outline_node | AIMessage | useCoAgentStateRender |

| Image generation | image_node | AIMessage | useCoAgentStateRender |

Related Issues

• CopilotKit Issue #2897: ToolMessage format mismatch with LangGraph.js
• LangChain serialization: Dynamic properties are ignored

Files Modified in This Solution

| File | Purpose |

| — — — | — — — — -|

| src/agent/agent.ts | Add isOutlineRequest(), outlineNode(), update routing |

| src/agent/tools/index.ts | Remove generateOutlineTool from exports |

| src/app/(main)/(protected)/wizard/page.tsx | Add useCoAgentStateRender for HITL |

| src/components/hitl/OutlineApprovalCard.tsx | HITL approval UI component |

Conclusion

The CopilotKit + LangGraph.js integration has a critical ToolMessage format incompatibility. The solution is to avoid ToolMessage entirely for HITL operations by using dedicated graph nodes that:

1. Route directly from START (bypass chat_node)
2. Perform operations with direct LLM calls (no tool calling)
3. Emit state with pendingContent for frontend detection
4. Return AIMessage (not ToolMessage)

This pattern has been successfully tested and deployed in production.

Background

This document records the debugging process and lessons learned from fixing a mobile sidebar navigation issue in a Docusaurus 3.8.1 project. The issue was caused by a single CSS property that broke the entire mobile navigation experience.

Project Configuration

• Docusaurus Version: 3.8.1
• Navbar Style: dark (configured in docusaurus.config.js)
• Features Enabled:

The Problem

After a homepage redesign commit, the mobile sidebar navigation became broken:

1. Symptom: Clicking the hamburger menu button would open the sidebar, but only the header/brand section was visible
2. The sidebar content was invisible — users could not see or scroll through the navigation links
3. Affected Devices: All mobile devices and screens under 996px width

What Users Experienced

┌─────────────────────────┐
│  🍔  AI Programming     │  ← Header visible
├─────────────────────────┤
│                         │
│     (Empty space)       │  ← Content invisible!
│                         │
│                         │
└─────────────────────────┘

Root Cause Analysis

The Culprit: backdrop-filter

The issue was traced to a single line of CSS added to the .navbar class:

/* ❌ This caused the sidebar to break */
.navbar {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  border-bottom: 1px solid var(--color-light-gray);
  background-color: var(--color-background);
  backdrop-filter: blur(var(--glass-blur));  /* ← THE PROBLEM */
}

Why backdrop-filter Breaks the Sidebar

1. Creates a New Stacking Context: The backdrop-filter property creates a new stacking context, similar to transform, opacity < 1, or filter.
2. Affects Child Element Positioning: When applied to the navbar, it interferes with how the mobile sidebar (a child/sibling element) is positioned and rendered.
3. Browser-Specific Behavior: The effect can vary across browsers and devices, making it particularly insidious to debug.
4. Silent Failure: The sidebar doesn’t show an error — it simply renders invisibly or gets clipped.

The Git Bisect That Found It

# The problematic commit
git show 505695c74c6b5120dad82e6a8306b01448ba3d28

# The last working commit
git show def1cace40147421bbdaf3df3bf5a7145f867c30

The Solution

Step 1: Remove backdrop-filter from Navbar

/* ✅ Fixed navbar styling */
.navbar {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  border-bottom: 1px solid var(--color-light-gray);
  background-color: var(--color-background);
  /* backdrop-filter removed */
}

Step 2: Restore Essential Navigation Styles

After fixing the sidebar visibility, we discovered that cleaning up CSS during debugging had removed important styling. The following styles needed to be restored:

Brand/Title Styling

.navbar__brand {
  font-weight: 700;
  font-size: 1.2rem;
  color: var(--ifm-color-primary);
}

.navbar__logo {
  height: 2rem;
  margin-right: 0.5rem;
}

Hamburger Menu Icon Styling

/* Light mode */
.navbar__toggle {
  color: var(--color-text-primary);
}

.navbar__toggle svg path {
  fill: var(--color-text-primary);
}

/* Dark mode */
[data-theme='dark'] .navbar__toggle {
  color: rgba(255, 255, 255, 0.9);
}

[data-theme='dark'] .navbar__toggle svg path {
  fill: rgba(255, 255, 255, 0.9);
}

Sidebar Styling

/* Base sidebar styles */
.navbar-sidebar {
  background-color: var(--color-background);
  border-right: 1px solid var(--color-light-gray);
}

.navbar-sidebar__brand {
  border-bottom: 1px solid var(--color-light-gray);
  padding: 1rem;
  background-color: var(--color-background);
}

/* Sidebar links */
.navbar-sidebar__items .menu__link,
.navbar-sidebar__items .navbar__link {
  color: var(--color-text-primary);
  font-weight: 500;
  padding: 0.5rem 1rem;
  border-radius: 4px;
}

/* Dark mode sidebar */
[data-theme='dark'] .navbar-sidebar {
  background-color: var(--color-background);
  border-right-color: rgba(255, 255, 255, 0.1);
}

[data-theme='dark'] .navbar-sidebar__items .menu__link,
[data-theme='dark'] .navbar-sidebar__items .navbar__link {
  color: rgba(255, 255, 255, 0.9);
}

Key Lessons Learned

1. ⚠️ Avoid backdrop-filter on Navigation Elements

Rule: Never use backdrop-filter on .navbar or parent elements of .navbar-sidebar.

/* ❌ DON'T do this */
.navbar {
  backdrop-filter: blur(10px);
}

/* ✅ If you need blur effect, apply it differently */
.navbar::before {
  content: '';
  position: absolute;
  inset: 0;
  backdrop-filter: blur(10px);
  z-index: -1;
}

2. 🎨 Always Style Both Light and Dark Modes

When customizing navigation, always provide styles for both themes:

/* Light mode */
.navbar__toggle {
  color: var(--color-text-primary);
}

/* Dark mode - MUST be explicitly defined */
[data-theme='dark'] .navbar__toggle {
  color: rgba(255, 255, 255, 0.9);
}

3. 📱 Test Mobile Views After Every CSS Change

The mobile sidebar uses different rendering than the desktop navbar. Always test:

• Hamburger menu visibility
• Sidebar opening animation
• Sidebar content scrollability
• Theme switching within sidebar

4. 🔍 Use Git Bisect for CSS Bugs

CSS bugs can be hard to trace. Use git bisect to find the exact commit:

git bisect start
git bisect bad HEAD
git bisect good <last-known-working-commit>
# Test each commit until you find the culprit

5. 🎯 Be Careful with Stacking Context Properties

These CSS properties create new stacking contexts and can break navigation:

6. 📋 Docusaurus Navbar Configuration Matters

If you set style: ‘dark’ in docusaurus.config.js:

navbar: {
  style: 'dark',  // This affects default colors
  // ...
}

You MUST provide explicit color overrides for both themes to ensure visibility.

Best Practices for Navbar Styling

DO ✅

1. Use CSS custom properties for colors to maintain theme consistency
2. Test on real mobile devices, not just browser dev tools
3. Provide complete dark mode styles for all navigation elements
4. Use specific selectors to avoid conflicts with Docusaurus defaults
5. Document your custom styles for future maintenance

DONT ❌

1. Don’t use backdrop-filter on navbar or its ancestors
2. Don’t remove Docusaurus default styles without replacement
3. Don’t forget mobile-specific styles in media queries
4. Don’t assume CSS changes are isolated — always test navigation
5. Don’t use !important excessively — it makes debugging harder

Complete Working Example

Here’s a complete, tested navbar styling setup:

/* ===========================================
   Navbar Base Styles
   =========================================== */

.navbar {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  border-bottom: 1px solid var(--color-light-gray);
  background-color: var(--color-background);
  /* NO backdrop-filter here! */
}

.navbar__brand {
  font-weight: 700;
  font-size: 1.2rem;
  color: var(--ifm-color-primary);
}

.navbar__link {
  color: var(--ifm-color-primary);
  font-weight: 600;
  padding: 0.5rem 0.75rem;
  border-radius: 4px;
}

/* ===========================================
   Hamburger Menu & Theme Toggle
   =========================================== */

.navbar__toggle,
.clean-btn {
  color: var(--color-text-primary);
}

.navbar__toggle svg path,
.clean-btn svg path {
  fill: var(--color-text-primary);
}

/* ===========================================
   Mobile Sidebar
   =========================================== */

.navbar-sidebar {
  background-color: var(--color-background);
  border-right: 1px solid var(--color-light-gray);
}

.navbar-sidebar__brand {
  border-bottom: 1px solid var(--color-light-gray);
  background-color: var(--color-background);
}

.navbar-sidebar__items .menu__link,
.navbar-sidebar__items .navbar__link {
  color: var(--color-text-primary);
  font-weight: 500;
}

/* ===========================================
   Dark Mode Overrides
   =========================================== */

[data-theme='dark'] .navbar {
  background-color: var(--color-background);
  border-bottom-color: rgba(255, 255, 255, 0.1);
}

[data-theme='dark'] .navbar__toggle,
[data-theme='dark'] .clean-btn {
  color: rgba(255, 255, 255, 0.9);
}

[data-theme='dark'] .navbar__toggle svg path,
[data-theme='dark'] .clean-btn svg path {
  fill: rgba(255, 255, 255, 0.9);
}

[data-theme='dark'] .navbar-sidebar {
  background-color: var(--color-background);
  border-right-color: rgba(255, 255, 255, 0.1);
}

[data-theme='dark'] .navbar-sidebar__items .menu__link,
[data-theme='dark'] .navbar-sidebar__items .navbar__link {
  color: rgba(255, 255, 255, 0.9);
}

/* ===========================================
   Mobile-Specific Styles
   =========================================== */

@media screen and (max-width: 996px) {
  .navbar__toggle {
    color: var(--color-text-primary) !important;
  }
  
  .navbar__toggle svg path {
    fill: var(--color-text-primary) !important;
  }
  
  [data-theme='dark'] .navbar__toggle {
    color: rgba(255, 255, 255, 0.9) !important;
  }
  
  [data-theme='dark'] .navbar__toggle svg path {
    fill: rgba(255, 255, 255, 0.9) !important;
  }
}

Debugging Checklist

When navbar/sidebar issues occur, check these in order:

• Is backdrop-filter used on .navbar or ancestors?
• Are both light and dark mode styles defined?
• Are mobile-specific styles in @media (max-width: 996px) block?
• Is the hamburger icon visible (check SVG fill color)?
• Does the sidebar have proper background-color?
• Are z-index values conflicting?
• Is position: fixed/absolute being affected by stacking context?

References

• Docusaurus Styling Documentation
• MDN: backdrop-filter
• MDN: Stacking Context

Overview

This project implements two distinct approaches for AI-powered voice conversations:

Sequential Recording (/practice/nzcel/conversation)

• Turn-based conversation with manual recording control
• Uses separate API calls for transcription, response generation, and TTS
• Best for structured practice scenarios

Realtime Streaming (/speaking)

• Natural, free-flowing conversation with automatic turn detection
• Uses OpenAI Realtime API with WebRTC for bidirectional streaming
• Best for realistic speaking practice

Implementation #1: Sequential Voice Recording

Architecture

User Speaks → Record Audio → Stop Recording → Transcribe (Whisper)
    ↓
Display Transcript → Generate Response (GPT-4) → Convert to Speech (TTS)
    ↓
Play Audio → Wait for User → Repeat

Core Files

src/
├── app/(main)/practice/nzcel/conversation/page.tsx
├── components/conversation/realtime-conversation.tsx
├── hooks/use-voice-recorder.ts
└── app/api/openai/
    ├── transcribe/route.ts    # Whisper API
    ├── conversation/route.ts  # GPT-4 Chat
    └── tts/route.ts          # Text-to-Speech

Key Technologies

• Audio Recording: MediaRecorder API (audio/webm)
• Transcription: OpenAI Whisper (whisper-1)
• AI Response: GPT-4 Turbo (gpt-4-turbo-preview)
• Text-to-Speech: OpenAI TTS (tts-1)

Implementation Pattern

1. Voice Recording Hook (use-voice-recorder.ts)

export function useVoiceRecorder() {
  const [state, setState] = useState<VoiceRecordingState>({
    isRecording: false,
    audioBlob: null,
    transcription: null,
  });
​
  const startRecording = async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
    const mediaRecorder = new MediaRecorder(stream, { mimeType: "audio/webm" });
    
    mediaRecorder.ondataavailable = (event) => {
      chunks.push(event.data);
    };
    
    mediaRecorder.onstop = () => {
      const blob = new Blob(chunks, { type: "audio/webm" });
      setState(prev => ({ ...prev, audioBlob: blob }));
    };
    
    mediaRecorder.start();
  };
​
  return { state, startRecording, stopRecording, transcribe, assess };
}

2. Conversation Flow (realtime-conversation.tsx)

const processUserSpeech = async () => {
  // 1. Transcribe audio
  const formData = new FormData();
  formData.append("audio", new File([audioBlob], "recording.webm"));
  
  const transcribeResponse = await fetch("/api/openai/transcribe", {
    method: "POST",
    body: formData,
  });
  const { text } = await transcribeResponse.json();
  
  // 2. Generate AI response
  const aiResponse = await fetch("/api/openai/conversation", {
    method: "POST",
    body: JSON.stringify({
      messages: [
        { role: "system", content: scenarioContext },
        ...conversationHistory,
        { role: "user", content: text }
      ],
    }),
  });
  const { response } = await aiResponse.json();
  
  // 3. Convert to speech
  const ttsResponse = await fetch("/api/openai/tts", {
    method: "POST",
    body: JSON.stringify({ text: response }),
  });
  const audioBlob = await ttsResponse.blob();
  
  // 4. Play audio
  const audio = new Audio(URL.createObjectURL(audioBlob));
  await audio.play();
};

3. API Routes

// Transcription (transcribe/route.ts)
export async function POST(request: NextRequest) {
  const formData = await request.formData();
  const audioFile = formData.get("audio") as File;
  
  const transcription = await openai.audio.transcriptions.create({
    file: audioFile,
    model: "whisper-1",
    language: "en",
  });
  
  return NextResponse.json({ text: transcription.text });
}
​
// Conversation (conversation/route.ts)
export async function POST(request: NextRequest) {
  const { messages } = await request.json();
  
  const completion = await openai.chat.completions.create({
    model: "gpt-4-turbo-preview",
    messages,
    temperature: 0.8,
    max_tokens: 300,
  });
  
  return NextResponse.json({ response: completion.choices[0].message.content });
}

Implementation #2: OpenAI Realtime API

Architecture

User Speaks (continuously) ←→ WebRTC Connection ←→ OpenAI Realtime API
         ↓                           ↓                        ↓
  VAD Detection              Auto-transcription        AI Response (voice)
         ↓                           ↓                        ↓
    Turn Detection  →  Save to Database  ←  Stream Audio Back

Core Files

src/
├── app/(main)/speaking/page.tsx
├── components/speaking/ai-coach.tsx
└── app/api/openai/realtime-client-secret/route.ts

Key Technologies

• SDK: @openai/agents/realtime
• Transport: WebRTC with bidirectional streaming
• Voice Activity Detection: Server-side VAD (threshold: 0.5, silence: 500ms)
• Transcription: Built-in (gpt-4o-mini-transcribe)
• Response: Real-time audio streaming

Implementation Pattern

1. Session Initialization

import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
​
const startSession = async () => {
  // Get ephemeral client secret
  const response = await fetch("/api/openai/realtime-client-secret", {
    method: "POST",
    body: JSON.stringify({
      voice: "verse",
      instructions: ESOL_COACH_INSTRUCTIONS,
    }),
  });
  const { clientSecret } = await response.json();
  
  // Create agent and session
  const agent = new RealtimeAgent({
    name: "ESOL Coach",
    instructions: ESOL_COACH_INSTRUCTIONS,
  });
  
  const session = new RealtimeSession(agent, {
    transport: "webrtc",
    config: {
      audio: {
        input: {
          transcription: { model: "gpt-4o-mini-transcribe" },
        },
      },
      turn_detection: {
        type: "server_vad",
        threshold: 0.5,
        silence_duration_ms: 500,
      },
    },
  });
  
  // Connect to OpenAI
  await session.connect({ apiKey: clientSecret });
  
  // Setup event handlers
  setupEventHandlers(session);
};

2. Event Handlers

const setupEventHandlers = (session: RealtimeSession) => {
  // Handle message history updates
  session.on("history_updated", (history) => {
    const messages = history
      .filter(item => item.type === "message")
      .map(item => ({
        role: item.role === "user" ? "user" : "assistant",
        content: extractTranscript(item.content),
        timestamp: new Date(),
      }));
    
    setMessages(messages);
    saveToDatabase(messages);
  });
  
  // Handle voice activity detection
  session.on("transport_event", (event) => {
    if (event.type === "input_audio_buffer.speech_started") {
      setIsSpeaking(true);
      startRecordingUserAudio();
    } else if (event.type === "input_audio_buffer.speech_stopped") {
      setIsSpeaking(false);
      stopRecordingUserAudio();
    }
  });
  
  // Handle errors
  session.on("error", (error) => {
    console.error("Session error:", error);
    toast.error("Conversation error occurred");
  });
};

3. Client Secret Generation

// realtime-client-secret/route.ts
export async function POST(request: NextRequest) {
  const { voice, instructions } = await request.json();
  
  const sessionConfig = {
    session: {
      type: "realtime" as const,
      model: "gpt-realtime",
      audio: { output: { voice } },
      instructions,
    },
  };
  
  const response = await fetch(
    "https://api.openai.com/v1/realtime/client_secrets",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(sessionConfig),
    }
  );
  
  const data = await response.json();
  return NextResponse.json({
    clientSecret: data.value,
    expiresAt: data.expires_at,
  });
}

4. Audio Recording Synchronization

// Track user audio for database persistence
const mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });
const userAudioChunks = {};
const recordingToMessageMap = new Map();

session.on("transport_event", (event) => {
  if (event.type === "input_audio_buffer.speech_started") {
    const recordingIndex = userRecordingCounter++;
    const currentUserMessageCount = session.history
      .filter(item => item.type === "message" && item.role === "user").length;
    
    recordingToMessageMap.set(recordingIndex, currentUserMessageCount);
    
    mediaRecorder.ondataavailable = (e) => {
      if (!userAudioChunks[recordingIndex]) {
        userAudioChunks[recordingIndex] = [];
      }
      userAudioChunks[recordingIndex].push(e.data);
    };
    
    mediaRecorder.start();
  } else if (event.type === "input_audio_buffer.speech_stopped") {
    mediaRecorder.stop();
  }
});

Comparison Matrix

| Feature | Sequential Recording | Realtime Streaming |
| — — — — -| — — — — — — — — — — -| — — — — — — — — — -|
| **Latency** | 3–5 seconds per turn | <1 second |
| **User Experience** | Manual button clicks | Natural conversation flow |
| **Implementation Complexity** | Medium (3 API calls) | High (WebRTC + events) |
| **API Usage** | 3 separate calls per turn | Single persistent connection |
| **Cost Model** | Pay per API call | Pay per minute ($0.06/min input, $0.24/min output) |
| **Browser Support** | Wide (MediaRecorder API) | Modern browsers (WebRTC) |
| **Turn Detection** | Manual (user clicks stop) | Automatic (Voice Activity Detection) |
| **Audio Format** | WebM → uploaded | PCM streaming |
| **Conversation Style** | Turn-based (structured) | Free-flowing (natural) |
| **Setup Time** | ~1 hour | ~3–4 hours |
| **Debugging** | Easy (inspect each step) | Moderate (event-driven) |
| **Interruption Handling** | Not supported | Built-in (barge-in) |
| **Best For** | Practice exercises, assessments | Conversational fluency, immersion |

Quick Implementation Guide

Prerequisites

npm install openai @openai/agents sonner

Environment Variables

OPENAI_API_KEY=sk-...

Sequential Recording Setup (30 mins)

Create voice recorder hook

• Copy src/hooks/use-voice-recorder.ts
• Handles MediaRecorder lifecycle

Create API routes

• /api/openai/transcribe - Whisper transcription
• /api/openai/conversation - GPT-4 responses
• /api/openai/tts - Text-to-speech

Build conversation component

• Use useVoiceRecorder() hook
• Chain: record → transcribe → respond → speak
• Display conversation history

Test workflow

• Request microphone permission
• Record → transcribe → respond
• Verify audio playback

Realtime Streaming Setup (2 hours)

Install Realtime SDK

npm install @openai/agents

Create client secret endpoint

• Copy src/app/api/openai/realtime-client-secret/route.ts
• Generates ephemeral tokens

Build coach component

• Initialize RealtimeAgent and RealtimeSession
• Setup WebRTC transport
• Configure VAD parameters

Implement event handlers

• history_updated - Update conversation transcript
• transport_event - Handle speech detection
• error - Handle connection issues

Add audio recording (optional for persistence)

• Setup parallel MediaRecorder
• Sync recordings with message indices
• Upload to storage

Test real-time flow

• Verify WebRTC connection
• Test voice activity detection
• Confirm natural turn-taking

When to Use Each Approach

Choose Sequential Recording When:

✅ Budget is a primary concern

• Pay only for API calls used
• Predictable costs per conversation

✅ You need full control

• Explicit start/stop recording
• Validate each step separately
• Custom processing between steps

✅ Implementing structured practice

• Question-answer format
• Assessment-focused exercises
• Clear turn boundaries

✅ Supporting older browsers

• Requires only MediaRecorder API
• Broader compatibility

✅ Debugging is critical

• Easy to inspect each pipeline stage
• Clear error boundaries

Choose Realtime Streaming When:

✅ User experience is paramount

• Natural, free-flowing conversations
• Minimal latency (<1 second)
• Interrupt and respond (barge-in)

✅ Simulating real conversations

• Speaking fluency practice
• Interview preparation
• Casual dialogue

✅ Users have modern browsers

• WebRTC support required
• Chrome, Edge, Safari (recent versions)

✅ Volume justifies setup time

• Higher upfront complexity
• Better UX for frequent use

✅ You want built-in features

• Automatic transcription
• Voice activity detection
• Turn management included

Common Pitfalls & Solutions

Sequential Recording

Issue: Audio blob is null after stopping recording

// ❌ Wrong: Process immediately
stopRecording();
processAudio(state.audioBlob); // blob is still null!

// ✅ Correct: Use effect to wait for blob
useEffect(() => {
  if (!state.isRecording && state.audioBlob) {
    processAudio(state.audioBlob);
  }
}, [state.audioBlob, state.isRecording]);

Issue: Microphone stays active after component unmounts

// ✅ Always cleanup
useEffect(() => {
  return () => {
    if (streamRef.current) {
      streamRef.current.getTracks().forEach(track => track.stop());
    }
  };
}, []);

Realtime Streaming

Issue: Message and audio recording out of sync

// ✅ Map recording index to expected message index
const recordingToMessageMap = new Map();

session.on("transport_event", (event) => {
  if (event.type === "input_audio_buffer.speech_started") {
    const recordingIndex = userRecordingCounter++;
    const expectedMessageIndex = getCurrentUserMessageCount();
    recordingToMessageMap.set(recordingIndex, expectedMessageIndex);
  }
});

Issue: Session not cleaning up properly

// ✅ Comprehensive cleanup
const stopSession = async () => {
  // Stop all recordings
  if (mediaRecorder?.state === "recording") {
    mediaRecorder.stop();
  }
  
  // Stop media streams
  mediaRecorder?.stream?.getTracks().forEach(track => track.stop());
  
  // Close session
  session?.close();
  
  // Clear refs
  sessionRef.current = null;
  mediaRecorderRef.current = null;
};

Best Practices

Security

// ✅ Never expose API keys in client code
// Use API routes to proxy requests
const response = await fetch("/api/openai/realtime-client-secret", {
  method: "POST"
});

// ❌ Never do this
const session = new RealtimeSession(agent, {
  apiKey: process.env.OPENAI_API_KEY // Exposed to client!
});

Performance

// ✅ Cache TTS audio for repeated questions
const getQuestionAudio = async (questionId: string, text: string) => {
  // Check cache first
  const cached = await db.query.questionAudioCache.findFirst({
    where: eq(schema.questionAudioCache.questionId, questionId)
  });
  
  if (cached) return cached.audioUrl; // 90% cost reduction
  
  // Generate and cache
  const audio = await generateTTS(text);
  await cacheAudio(questionId, audio);
  return audio;
};

User Experience

// ✅ Provide clear feedback at each stage
toast.info("Transcribing your response...");
toast.info("AI is thinking...");
toast.success("Ready for your next response!");

// ✅ Show recording indicator
{state.isRecording && (
  <div className="flex items-center gap-2">
    <div className="h-3 w-3 rounded-full bg-red-500 animate-pulse" />
    <span>Recording... ({state.recordingDuration}s)</span>
  </div>
)}

Error Handling

// ✅ Graceful degradation
try {
  const transcription = await transcribe();
  const response = await generateResponse(transcription);
  await speakResponse(response);
} catch (error) {
  if (error.message.includes("microphone")) {
    toast.error("Microphone access denied. Please check permissions.");
  } else if (error.message.includes("API")) {
    toast.error("Service temporarily unavailable. Please try again.");
  } else {
    toast.error("An error occurred. Please refresh the page.");
  }
}

Advanced Topics

Custom AI Instructions

const INSTRUCTIONS = `You are an ESOL speaking coach.

- Adapt to CEFR level: ${userLevel}
- Focus areas: ${focusSkills.join(", ")}
- Provide feedback on: fluency, accuracy, coherence
- Keep responses under 20 seconds
- Encourage learner after each turn`;

Audio Persistence Strategy

// Sequential: Simple - save after each turn
await saveUserRecording({
  sessionId,
  audioBlob,
  transcription,
  timestamp: new Date(),
});

// Realtime: Complex - sync with message history
// Map recording index → message index → upload when message saved

Session Analytics

interface SessionMetrics {
  duration: number;           // Total session time
  turnCount: number;          // Number of exchanges
  userSpeakingTime: number;   // Active speaking time
  avgResponseLatency: number; // Sequential only
  completionRate: number;     // % of target turns reached
}

Conclusion

Both approaches have their place in ESOL learning platforms:

Sequential Recording: Reliable, cost-effective, and easier to implement. Perfect for structured practice, assessments, and budget-conscious applications.

Realtime Streaming: Premium experience with natural conversation flow. Ideal for advanced learners, fluency practice, and applications where UX justifies the complexity.

Consider implementing both: use Sequential Recording for structured exercises and Realtime Streaming for conversational practice. This hybrid approach provides flexibility for different learning contexts and user needs.

Resources

Project Files

Sequential Implementation:

• src/components/conversation/realtime-conversation.tsx - Main component
• src/hooks/use-voice-recorder.ts - Recording logic
• src/app/api/openai/transcribe/route.ts - Whisper API
• src/app/api/openai/conversation/route.ts - GPT-4 API
• src/app/api/openai/tts/route.ts - Text-to-speech API

Realtime Implementation:

• src/components/speaking/ai-coach.tsx - Main component
• src/app/api/openai/realtime-client-secret/route.ts - Authentication

External Documentation

• OpenAI Realtime API Guide
• OpenAI Whisper API
• MediaRecorder API (MDN)
• WebRTC API (MDN)

The Problem

I was using CSS @import to load Google Fonts:

@import url('https://fonts.googleapis.com/css2?family=Press+Start+2P&display=swap');

Result? All fonts failed to load. The browser’s document.fonts showed nothing. My pixel-art aesthetic was ruined.

Why CSS @import Fails in Next.js

Next.js 13+ has a built-in font optimization system that doesn’t play well with traditional CSS imports. Using @import:

• Bypasses Next.js optimizations
• Creates unnecessary external requests
• Can cause Flash of Unstyled Text (FOUT)
• May not load reliably during build

The Solution: Use next/font/google

Here’s the proper approach in 3 simple steps:

Step 1: Import Fonts in app/layout.tsx

import { Press_Start_2P, VT323, Pixelify_Sans } from "next/font/google";

const pressStart2P = Press_Start_2P({
  weight: "400",
  subsets: ["latin"],
  variable: "--font-press-start",
  display: "swap",
});

const vt323 = VT323({
  weight: "400",
  subsets: ["latin"],
  variable: "--font-vt323",
  display: "swap",
}); 

Step 2: Apply Font Variables to HTML

export default function RootLayout({ children }) {
  return (
    <html className={`${pressStart2P.variable} ${vt323.variable}`}>
      <body className={pressStart2P.className}>
        {children}
      </body>
    </html>
  );
}

Step 3: Update CSS to Use Variables

Remove the @import statements and use CSS variables instead:

body {
  font-family: var(--font-press-start), 'Courier New', monospace;
}

.font-pixel-display {
  font-family: var(--font-press-start), 'Courier New', monospace;
} 

Bonus: Update your Tailwind config for utility classes:

fontFamily: {
  'pixel-display': ['var(--font-press-start)', 'monospace'],
  'pixel-content': ['var(--font-vt323)', 'monospace'],
}

Why This Works Better

✅ Self-hosted: Fonts are served from your domain, not Google’s ✅ Zero layout shift: No flash of unstyled text ✅ Better performance: Automatic optimization and preloading ✅ Privacy-friendly: No external tracking ✅ Type-safe: TypeScript support out of the box

Testing Your Fix

After implementing these changes:

1. Restart your dev server (important!)
2. Hard refresh your browser (Ctrl+Shift+R / Cmd+Shift+R)
3. Check DevTools: Inspect any text element and verify the computed font-family shows your custom font
4. Look for font files in the Network tab with status 200

Troubleshooting

If fonts still don’t appear:

# Clear Next.js cache
rm -rf .next
npm run dev

Then hard refresh your browser again.

Key Takeaway

Don’t use CSS @import for fonts in Next.js 13+. Always use next/font/google or next/font/local for optimal performance and reliability.

This approach transforms font loading from a potential bottleneck into a strength, giving you:

• Faster page loads
• Better user experience
• Zero configuration optimization

Resources:

• Next.js Font Optimization Docs
• next/font API Reference

This document provides a comprehensive guide on how the AI chatbot was integrated into the She Sharp website. It covers the technical implementation, challenges encountered, and solutions applied during the development process.

Table of Contents

1. Project Context
2. Technology Stack
3. Implementation Steps
4. Key Features
5. Challenges and Solutions
6. Streaming Response Implementation
7. Environment Configuration
8. Deployment Considerations
9. Best Practices and Lessons Learned

Project Context

She Sharp is a non-profit organization dedicated to bridging the gender gap in STEM fields. The AI chatbot was integrated to provide instant assistance to website visitors, answering questions about:

• Organization programs and services
• Mentorship opportunities
• Events and workshops
• How to get involved

Technology Stack

Core Technologies

• Framework: Next.js 15.4.0 with App Router
• Language: TypeScript
• AI SDK: Vercel AI SDK v4.3.19
• AI Provider: Google Gemini Pro (via @ai-sdk/google v1.2.22)
• Additional SDK: @google/generative-ai v0.24.1
• UI Animation: Framer Motion v12.23.9
• UI Components: shadcn/ui with Radix UI
• Styling: Tailwind CSS v4

Key Dependencies

{
  "@ai-sdk/google": "^1.2.22",
  "@google/generative-ai": "^0.24.1",
  "ai": "^4.3.19",
  "framer-motion": "^12.23.9"
}

Implementation Steps

1. Initial Setup

First, install the required dependencies:

pnpm add ai @ai-sdk/google framer-motion

2. Component Structure

The chatbot implementation consists of several modular components:

components/chatbot/
├── chatbot.tsx              # Main chatbot component
├── chat-message.tsx         # Individual message component
├── typing-indicator.tsx     # Animated typing indicator
├── quick-actions.tsx        # Preset questions panel
├── preset-questions.ts      # Preset Q&A data
├── types.ts                # TypeScript interfaces
└── chatbot-provider.tsx    # Client-side wrapper

3. API Route Implementation

Create the chat API endpoint at app/api/chat/route.ts:

import { google } from '@ai-sdk/google';
import { convertToCoreMessages, streamText } from 'ai';
​
export async function POST(req: Request) {
  const { messages } = await req.json();
  
  // Clean messages and filter system messages
  const cleanedMessages = messages
    .filter((msg: any) => msg.id !== 'system')
    .map((msg: any) => ({
      role: msg.role,
      content: msg.content
    }));
  
  const model = google('gemini-1.5-flash');
  
  const result = await streamText({
    model,
    system: 'You are a helpful assistant for She Sharp...',
    messages: convertToCoreMessages(cleanedMessages),
    temperature: 0.7,
    maxTokens: 500,
  });
  
  return result.toDataStreamResponse();
}

4. Integration into Layout

Add the chatbot to the root layout (app/layout.tsx):

import { ChatbotProvider } from '@/components/chatbot/chatbot-provider';
​
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <ChatbotProvider />
      </body>
    </html>
  );
}

Key Features

1. Streaming Responses

• Real-time AI responses with character-by-character display
• Visual typing indicator during response generation

2. Preset Questions System

• 8 pre-configured common questions
• Categorized by topic (About, Events, Mentorship, Support, General)
• Instant responses without API calls

3. Chat History Persistence

• LocalStorage implementation
• Stores up to 50 messages
• Survives page refreshes

4. User Experience Features

• Keyboard shortcuts (⌘K to open/close)
• Auto-focus on input field
• Smooth animations with Framer Motion
• Responsive design for mobile and desktop
• Clear chat history functionality

Challenges and Solutions

Challenge 1: TypeScript Type Errors

Error:

Type error: Type '"user" | "data" | "system" | "assistant"' is not assignable to type '"user" | "assistant"'

Solution: Add type assertion when passing role prop:

role={message.role as 'user' | 'assistant'}

Challenge 2: Missing Tailwind CSS Classes

Error:

[Error: Cannot apply unknown utility class: md:text-3xl]

Solution: Define responsive text utilities in globals.css:

@media (min-width: 768px) {
  .md\:text-3xl { font-size: var(--font-size-3xl); }
  .md\:text-4xl { font-size: var(--font-size-4xl); }
  /* ... other sizes */
}

Challenge 3: Environment Variable Issues

Problem: API key not being recognized by the SDK

Solution:

1. Ensure correct environment variable name: GOOGLE_GENERATIVE_AI_API_KEY
2. Add to .env.local (not .env)
3. Restart the development server after changes

Streaming Response Implementation

Initial Problem

The initial implementation using GoogleGenerativeAIStream and StreamingTextResponse failed with import errors:

Export GoogleGenerativeAIStream doesn't exist in target module
Export StreamingTextResponse doesn't exist in target module

Investigation Process

1. First Attempt: Direct Google Generative AI SDK integration

• Created custom streaming implementation
• Encountered format compatibility issues with Vercel AI SDK

2. Second Attempt: Simple test API

• Created /api/chat-simple endpoint to verify frontend functionality
• Confirmed frontend could handle streaming responses correctly

3. Final Solution: Correct Vercel AI SDK Usage

The key was using the correct imports and methods from Vercel AI SDK v4:

import { google } from '@ai-sdk/google';
import { convertToCoreMessages, streamText } from 'ai';
​
// Create model instance
const model = google('gemini-1.5-flash');
​
// Use streamText with proper configuration
const result = await streamText({
  model,
  system: systemPrompt,
  messages: convertToCoreMessages(cleanedMessages),
  temperature: 0.7,
  maxTokens: 500,
});
​
// Return the stream response
return result.toDataStreamResponse();

Critical Fixes for Streaming

1. Import Corrections: Used streamText instead of non-existent GoogleGenerativeAIStream
2. Message Format: Used convertToCoreMessages() to ensure proper message format
3. Response Method: Used result.toDataStreamResponse() for proper streaming format
4. Error Scope: Fixed variable scope issue where result was defined inside try block but used outside

Environment Configuration

Required Environment Variables

Add to .env.local:

GOOGLE_GENERATIVE_AI_API_KEY=your_api_key_here

Important Notes:

• Use .env.local for Next.js projects (not .env)
• The SDK automatically reads GOOGLE_GENERATIVE_AI_API_KEY
• Never commit API keys to version control

Deployment Considerations

Vercel Deployment

1. Environment Variables: Add GOOGLE_GENERATIVE_AI_API_KEY in Vercel project settings
2. Build Errors: Ensure all TypeScript errors are resolved
3. Tailwind CSS: Verify all utility classes are properly defined

Performance Optimization

1. Dynamic Import: Chatbot is lazy-loaded to improve initial page load

const Chatbot = dynamic(() => import('./chatbot').then(mod => ({ default: mod.Chatbot })), {
  ssr: false,
  loading: () => null
});

2. Message Limits: Store only last 50 messages to prevent localStorage bloat

Best Practices and Lessons Learned

1. API Integration

• Always verify API key configuration before debugging other issues
• Use proper error handling and logging for debugging
• Test with simple implementations first to isolate problems

2. Streaming Responses

• Understand the specific requirements of your AI SDK version
• Verify import statements match the actual SDK exports
• Use browser developer tools to monitor network requests

3. Type Safety

• Define clear TypeScript interfaces for all data structures
• Use type assertions sparingly and only when necessary
• Leverage TypeScript’s type inference where possible

4. User Experience

• Provide visual feedback during AI response generation
• Include preset questions for common queries
• Implement keyboard shortcuts for power users
• Ensure responsive design works on all devices

5. Error Handling

• Display user-friendly error messages
• Log detailed errors for debugging
• Implement retry mechanisms for transient failures

Conclusion

The AI chatbot integration demonstrates the power of modern web technologies in creating interactive user experiences. By leveraging Vercel AI SDK with Google’s Gemini model, we created a responsive, intelligent assistant that enhances the She Sharp website’s ability to serve its community.

Key takeaways:

• Proper SDK usage and understanding documentation is crucial
• Iterative debugging and testing helps identify root causes
• Modular component design improves maintainability
• User experience should be the primary focus

For questions or improvements, refer to the codebase or contact the development team.

Implementing a “Download PDF Report” feature with user data collection in a Docusaurus website presents unique challenges, especially when integrating with external services like Notion. This article documents our journey building this functionality for the FemTech Weekend website, covering the obstacles we faced and the solutions we implemented. By the end, you’ll understand how to create a PDF download component that collects user information and stores it in a Notion database, working seamlessly in both local development and Vercel deployment.

Project Overview

Our goal was to create a component that would:

1. Display a “Download Full PDF Report” button on blog posts
2. Show a form modal when clicked to collect user information
3. Submit this information to a Notion database
4. Allow the user to download the PDF after form submission
5. Work in both development and production environments

The Architecture

The final solution involved several key components:

1. A DownloadPdfButton React component
2. An API route handler in src/api/pdf-form-submit.js
3. A forwarding API endpoint in api/pdf-form-submit/index.js
4. A custom Docusaurus plugin for API route handling
5. Development scripts to run both Docusaurus and API servers

Challenge 1: Understanding the Docusaurus API Route System

The Problem

Unlike Next.js, Docusaurus doesn’t have a built-in API routes system. Our initial attempts to create API endpoints failed because we didn’t understand how API routes are handled in Docusaurus.

The Solution

We discovered that Docusaurus requires a custom plugin to handle API routes. This plugin sets up a proxy in development mode that forwards API requests to a separate Node.js server running on port 3001.

// src/plugins/api-routes.js
module.exports = function apiRoutesPlugin(context, options) {
  return {
    name: 'docusaurus-api-routes-plugin',
    configureWebpack(config, isServer) {
      if (!isServer && process.env.NODE_ENV === 'development') {
        return {
          devServer: {
            proxy: {
              '/api': {
                target: 'http://localhost:3001',
                secure: false,
                changeOrigin: true,
                // Additional configuration...
              },
            },
          },
        };
      }
      return {};
    },
    // Additional plugin configuration...
  };
};

This plugin must be registered in docusaurus.config.ts to work properly.

Challenge 2: CORS and Request Handling

The Problem

Even after setting up the API routes plugin, we encountered CORS errors when submitting the form, particularly in the development environment.

The Solution

We added proper CORS headers to our API server configuration and ensured that the proxy settings correctly handled both OPTIONS preflight requests and actual POST requests:

// In the plugin's proxy configuration
onProxyRes: (proxyRes, req, res) => {
  // Add CORS headers to the response
  proxyRes.headers['Access-Control-Allow-Origin'] = '*';
  proxyRes.headers['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS';
  proxyRes.headers['Access-Control-Allow-Headers'] = 'Content-Type';
},

Challenge 3: API Server Configuration

The Problem

We needed a separate API server to handle requests when in development mode, but weren’t sure how to structure it properly.

The Solution

We created an api-server.js file that:

1. Sets up a Node.js HTTP server on port 3001
2. Loads environment variables from .env.local
3. Routes API requests to the appropriate handlers in the src/api directory
4. Provides proper error handling and logging

For Vercel deployment, we created a parallel structure in the api folder that forwards requests to the main implementation.

Challenge 4: Notion Database Integration

The Problem

Connecting to Notion and storing form submissions required specific configuration and error handling to work reliably.

The Solution

We implemented a comprehensive Notion integration in our pdf-form-submit.js handler:

// src/api/pdf-form-submit.js
const { Client } = require('@notionhq/client');
​
// Initialize Notion client
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});
​
async function handler(req, res) {
  // Validation and error handling
  
  // Create Notion page properties
  const properties = {
    Name: {
      title: [{ text: { content: fullName } }],
    },
    // Additional properties...
  };
​
  // Create the page in Notion
  const response = await notion.pages.create({
    parent: { database_id: process.env.PDF_FORM_DATABASE_ID },
    properties: properties,
  });
  
  // Return success response
}

Challenge 5: Development Environment Setup

The Problem

Running both the Docusaurus server and the API server simultaneously was cumbersome and error-prone.

The Solution

We created a custom start-dev.js script that:

1. Checks if required environment variables are present
2. Creates a default .env.local if it doesn't exist
3. Checks if necessary ports are available
4. Starts both servers in the correct order
5. Provides clear console logging for debugging

// start-dev.js
async function startServers() {
  // Start API server first
  const apiProcess = spawn('node', ['api-server.js'], { 
    stdio: 'inherit',
    shell: true 
  });
  
  // Wait a moment for API server to initialize
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // Start Docusaurus server
  const docusaurusProcess = spawn('npm', ['run', 'start'], { 
    stdio: 'inherit',
    shell: true,
    env: { ...process.env, BROWSER: 'none' }
  });
​
  // Handle process errors and shutdown
  // ...
}

Challenge 6: Environment Variables

The Problem

Managing environment variables between development and production environments was challenging, especially for the Notion integration.

The Solution

We implemented a system that:

1. Uses .env.local for local development
2. Relies on Vercel environment variables for production
3. Exposes necessary variables to client-side code through the plugin

// In the plugin's injectHtmlTags method
injectHtmlTags() {
  return {
    headTags: [
      {
        tagName: 'script',
        innerHTML: `
          window.ENV = {
            NOTION_DATABASE_ID: '${process.env.NOTION_DATABASE_ID || ''}',
            // Other variables...
          };
        `,
      },
    ],
  };
},

The Final Implementation

Component Structure

Our final DownloadPdfButton component:

1. Shows a button that triggers a modal form
2. Collects user information
3. Submits the form to our API endpoint
4. Provides feedback on submission status
5. Opens the PDF link after successful submission

API Handler Structure

The API handler follows these steps:

1. Validates incoming request data
2. Formats the data for Notion
3. Creates a new page in the Notion database
4. Returns appropriate success/error responses

Development Setup

To run the project locally:

1. Create a .env.local file with required Notion credentials
2. Run node start-dev.js to start both servers
3. The Docusaurus site runs on port 3000, while the API server runs on port 3001

Production Deployment

For Vercel deployment:

1. Configure environment variables in the Vercel project settings
2. Vercel’s serverless functions automatically handle the API routes
3. The same code works in both environments thanks to our API forwarding structure

Key Lessons Learned

1. Understand the Platform: Docusaurus handles API routes differently than frameworks like Next.js
2. Dual Server Architecture: Running separate servers for frontend and API in development provides flexibility
3. Error Logging: Comprehensive logging helps identify issues quickly
4. Environment Consistency: Ensuring development and production environments are configured similarly prevents deployment surprises
5. API Forwarding: Creating a forwarding structure ensures the same code works in both environments

Conclusion

Building a PDF download component with Notion integration in Docusaurus requires understanding both the limitations of the platform and how to work around them. By setting up a custom plugin, implementing proper API handlers, and ensuring consistent environment configuration, we successfully created a solution that works both locally and in production.

This approach can be extended to other external integrations beyond Notion, making it a valuable pattern for any Docusaurus project that needs to handle form submissions or other API interactions.

This document details the process of implementing Chinese/English language switching for a Docusaurus-based website showcasing FemTech companies. The primary goal was to enable user interface elements on the /showcase page to be properly translated between English and Chinese.

Initial Requirements

• Enable language switching between English (default) and Chinese (zh-Hans) for the /showcase page
• Translate all UI elements including:

Page headers and descriptions

Filter section title and buttons

Company card elements (founder/funding labels)

Category tags

Testing Environment

• Docusaurus version: 3.x
• Development server: localhost:3000
• Chinese version accessed via: localhost:3000/zh-Hans/showcase
• English version accessed via: localhost:3000/showcase

Attempted Approaches

1. Standard Docusaurus i18n Translation Files

The initial approach followed Docusaurus’s official internationalization method:

1. Creating translation JSON files in the appropriate directories:

• i18n/zh-Hans/docusaurus-plugin-content-pages/showcase.json
• i18n/zh-Hans/docusaurus-theme-common.json
• i18n/zh-Hans/theme.json

2. Using Docusaurus’s built-in translation functions:

import {translate} from '@docusaurus/Translate';

translate({
  id: 'showcase.filters.title',
  message: 'Filters',
});

Results: Despite proper file placement and correct usage of the translation functions, translations were not applied. Debugging showed that while the locale was correctly detected as zh-Hans, the translation system returned English text.

2. Modifying Translation Keys

We attempted to modify the translation keys to match different patterns:

1. Using theme-prefixed keys: theme.showcase.filters.title
2. Using plugin-specific directories: i18n/zh-Hans/docusaurus-theme-common/common.json

Results: These approaches didn’t resolve the issue. The translation mechanism still failed to pick up the correct translations.

Successful Solution

After several unsuccessful attempts with the built-in translation system, we implemented a direct conditional rendering approach:

const {i18n: {currentLocale}} = useDocusaurusContext();
​
{currentLocale === 'zh-Hans' ? '筛选' : translate({
  id: 'theme.showcase.filters.title',
  message: 'Filters'
})}

This approach:

1. Uses useDocusaurusContext to detect the current locale
2. Renders Chinese text when the locale is zh-Hans
3. Falls back to English text via the translation function for other locales

For component-specific translations like tags, we implemented a custom translation hook:

export function useTranslatedTags() {
  const {i18n: {currentLocale}} = useDocusaurusContext();
  
  return useMemo(() => {
    // Function to get translation for a tag
    const getTranslatedTag = (tagKey: TagType) => {
      // Direct translations for Chinese locale
      if (currentLocale === 'zh-Hans') {
        const zhTranslations: Record<TagType, {label: string; description: string}> = {
          '女性疾病': {
            label: '女性疾病',
            description: '专注于女性疾病的诊断、治疗和管理的公司'
          },
          // Additional translations...
        };
        return zhTranslations[tagKey];
      }
      
      // Default to English for other locales
      return {
        label: translate({
          id: `femtech-tags.${tagKey}.label`,
          message: TagDefaults[tagKey].defaultLabel,
        }),
        description: translate({
          id: `femtech-tags.${tagKey}.description`,
          message: TagDefaults[tagKey].defaultDescription,
        }),
      };
    };
    
    // Create Tags object with translations...
  }, [currentLocale]);
}

File Structure Overview

Final Effective Files

src/
  components/
    ShowcaseFilters/index.tsx        # Contains filters with i18n support
    ShowcaseCards/index.tsx          # Displays company cards with i18n
    ClearAllButton/index.tsx         # Filter clearing button with i18n
    OperatorButton/index.tsx         # Filter operator with i18n
    ShowcaseCard/index.tsx           # Individual company card with i18n
  data/
    femtech-companies.ts             # Contains useTranslatedTags for tag i18n
  pages/
    showcase.tsx                     # English showcase page
i18n/
  zh-Hans/
    docusaurus-plugin-content-pages/
      showcase.tsx                   # Chinese version of showcase page

Deleted Unused Files

i18n/zh-Hans/docusaurus-theme-common.json      # Unused translation file
i18n/en/docusaurus-theme-common.json           # Unused translation file
i18n/zh-Hans/theme-common.json                 # Unused translation file
i18n/zh-Hans/theme.json                        # Unused translation file
i18n/zh-Hans/docusaurus-plugin-content-pages/showcase.json   # Unused translation file
i18n/en/docusaurus-plugin-content-pages/showcase.json        # Unused translation file
i18n/zh-Hans/docusaurus-theme-common/femtech-tags.json       # Unused translation file
i18n/en/docusaurus-theme-common/femtech-tags.json            # Unused translation file

Implementation Details

1. Page Header and Description Translations

English Version (src/pages/showcase.tsx):

function ShowcaseHeader() {
  const {i18n: {currentLocale}} = useDocusaurusContext();
  
  return (
    <section className="margin-top--lg margin-bottom--lg text--center">
      <Heading as="h1">
        {translate({
          id: 'header.title',
          message: 'FemTech Companies Showcase',
        })}
      </Heading>
      <p>
        {translate({
          id: 'header.description',
          message: 'Directory of innovative companies in the women\'s health industry in China',
        })}
      </p>
    </section>
  );
}

Chinese Version (i18n/zh-Hans/docusaurus-plugin-content-pages/showcase.tsx):

function ShowcaseHeader() {
  return (
    <section className="margin-top--lg margin-bottom--lg text--center">
      <Heading as="h1">
        中国女性健康公司展示
      </Heading>
      <p>
        中国女性健康领域的创新企业列表
      </p>
    </section>
  );
}

2. UI Element Translations

Filters Title:

function HeadingText() {
  const {i18n: {currentLocale}} = useDocusaurusContext();
  
  return (
    <div className={styles.headingText}>
      <Heading as="h2">
        {currentLocale === 'zh-Hans' ? '筛选' : translate({
          id: 'theme.showcase.filters.title',
          message: 'Filters',
        })}
      </Heading>
      <span>{companyCountPlural(filteredCompanies.length)}</span>
    </div>
  );
}

Clear Filters Button:

function ClearAllButton() {
  const {i18n: {currentLocale}} = useDocusaurusContext();

  return (
    <button
      type="button"
      className="button button--sm button--outline button--danger"
      onClick={clearAll}>
      {currentLocale === 'zh-Hans' ? '清除筛选' : translate({
        id: 'theme.showcase.filters.clearAll',
        message: 'Clear filters',
      })}
    </button>
  );
}

Operator Button:

function OperatorButton() {
  const [operator, toggleOperator] = useOperator();
  const {i18n: {currentLocale}} = useDocusaurusContext();
  
  return (
    <button
      type="button"
      className={`button button--sm button--${
        operator === 'OR' ? 'secondary' : 'primary'
      }`}
      onClick={toggleOperator}>
      {currentLocale === 'zh-Hans' ? `筛选条件: ${operator}` : translate(
        {
          id: 'theme.showcase.filters.operator',
          message: 'Filter criteria: {operator}',
        },
        {
          operator,
        }
      )}
    </button>
  );
}

Company Card Labels:

// In ShowcaseCard component
{company.founders && (
  <div className={styles.showcaseCardDetail}>
    <strong>
      {currentLocale === 'zh-Hans' ? '创始人:' : translate({
        id: 'theme.showcase.card.founder',
        message: 'Founder:',
      })}
    </strong> {company.founders}
  </div>
)}
        
{latestFunding && (
  <div className={styles.showcaseCardDetail}>
    <strong>
      {currentLocale === 'zh-Hans' ? '融资:' : translate({
        id: 'theme.showcase.card.funding',
        message: 'Funding:',
      })}
    </strong> {latestFunding.round} ({latestFunding.date}) {latestFunding.amount && `- ${latestFunding.amount}`}
  </div>
)}

Challenges Encountered

1. Translation File Loading Issues

Despite following Docusaurus documentation, the translation files weren’t being properly loaded. The system would acknowledge the correct locale but wouldn’t use the translated strings from JSON files.

2. Inconsistent Behavior

Some translation keys would work with certain prefixes (theme. vs no prefix), while others wouldn't work regardless of the prefix used.

3. Debugging Difficulties

It was challenging to debug the translation system as there was limited feedback on why translations weren’t being applied. We added extensive debug logging to track:

• Current locale
• Translation keys being used
• Results of translation function calls

4. File Encoding

At one point, a file displayed as garbled text, suggesting potential encoding issues with Chinese characters.

Lessons Learned

1. Docusaurus i18n Complexity: Docusaurus’s internationalization system requires precise file structure and naming conventions that may not be immediately intuitive.
2. Conditional Rendering as an Alternative: Direct conditional rendering based on locale can be more reliable than the built-in translation system for complex use cases.
3. Component-Level vs. Page-Level i18n: For page-level content, using separate files (showcase.tsx in each language folder) works well, while component-level UI elements benefit from inline conditional rendering.
4. Translation Key Specificity: The translation key format is critical — using the wrong format or missing prefixes can cause translations to fail silently.
5. Testing on Real Devices: What works in development may behave differently in production, so thorough testing across environments is essential.

Best Practices and Recommendations

1. Choose the Right Approach:

• For complete page translations: use separate language-specific files
• For UI elements and components: use conditional rendering based on locale
• For complex dynamic content (like tags): consider custom translation hooks

2. Simplify When Necessary:

• Don’t hesitate to bypass complex translation systems if direct approaches are more reliable
• Hardcode translations directly in components when the standard i18n approach isn’t working

3. Consistent Implementation:

• Use the same approach across similar components for better maintainability
• Document your chosen approach clearly for future developers

4. Clean Up Unused Files:

• Remove any unused translation files to prevent confusion and maintenance issues
• Document which files are actually being used vs. which are legacy attempts

5. Proper Debugging:

• Add temporary logging to verify locale detection and translation lookups
• Remove debug code once implementation is stable

6. Consider User Experience:

• Ensure all visible text is translated, including dynamic content like error messages
• Test thoroughly with actual users of each supported language

By following these guidelines and learning from the experiences documented here, future developers should be able to implement internationalization more effectively in Docusaurus projects.

This guide will walk you through the complete process of setting up Algolia DocSearch in your Docusaurus project. Algolia DocSearch provides powerful search capabilities for your documentation website, allowing users to quickly find relevant content.

Prerequisites

• A Docusaurus website (v2.x or v3.x)
• An Algolia account (free tier is available)
• Your website deployed and accessible online

Step 1: Sign Up for Algolia

1. Go to Algolia’s website and create an account
2. Once registered, you’ll receive an Application ID and API keys
3. Note down your Application ID, Search API Key, and Write API Key

Step 2: Configure Docusaurus

In your Docusaurus project, open the docusaurus.config.ts (or docusaurus.config.js) file and add the Algolia configuration:

// docusaurus.config.ts
export default {
  // ... existing configuration
  themeConfig: {
    // ... other theme config
    algolia: {
      // The application ID provided by Algolia
      appId: 'YOUR_APP_ID',
​
      // Public API key: it is safe to commit it
      apiKey: 'YOUR_SEARCH_API_KEY', // Use the Search API Key, not the Write API Key
​
      indexName: 'YOUR_INDEX_NAME', // Choose a meaningful name for your index
​
      // Optional: see doc section below
      contextualSearch: true,
​
      // Optional: Specify domains where the navigation should occur through window.location instead on history.push
      externalUrlRegex: 'external\\.com|domain\\.com',
​
      // Optional: Algolia search parameters
      searchParameters: {},
​
      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',
​
      // Optional: whether the insights feature is enabled or not on Docsearch
      insights: false,
    },
  },
};

Replace the placeholder values with your actual Algolia credentials.

Step 3: Verify Domain Ownership

Algolia requires verification of domain ownership before crawling your site:

1. Go to the Algolia dashboard
2. Navigate to Crawler > New Crawler
3. During setup, you’ll be asked to verify your domain
4. Choose the “robots.txt” verification method
5. Add the provided verification line to your robots.txt file

If you don’t have a robots.txt file, create one in the static directory of your Docusaurus project:

User-agent: *
Allow: /
​
# Algolia-Crawler-Verif: YOUR_VERIFICATION_CODE
​
Sitemap: https://your-website-url.com/sitemap.xml

Step 4: Create and Configure the Crawler

1. In the Algolia dashboard, go to Crawler > New Crawler
2. Enter a crawler name (this will be your index name)
3. Set your website URL as the start URL
4. Choose “Technical documentation” as the content type
5. Select “Docusaurus v2.x or v3.x” as the template
6. Click “Create”

After creating the crawler, you’ll need to configure it:

1. Verify your crawler settings match your website structure
2. Ensure the index name in the crawler matches the one in your Docusaurus configuration
3. Save your configuration

Step 5: Run the Crawler

1. In the Algolia dashboard, navigate to your crawler
2. Click “Run Crawler”
3. Wait for the crawling process to complete
4. Check that records have been added to your index

Step 6: Deploy Your Website

Deploy your Docusaurus site with the updated configuration:

git add .
git commit -m "Add Algolia DocSearch configuration"
git push

Step 7: Test the Search Functionality

1. Visit your deployed website
2. Click on the search icon in the header
3. Type a query related to your content
4. Verify that search results appear and links work correctly

Troubleshooting

No Search Results

If you don’t see any search results:

1. Check if your crawler has successfully indexed your site
2. Verify that the index name in your configuration matches the crawler’s index name
3. Ensure your API keys are correct

Broken Links in Search Results

If clicking on search results leads to “Page Not Found” errors:

1. Remove or adjust the replaceSearchResultPathname configuration in your docusaurus.config.ts:

// Comment out this section if it's causing issues
/*
replaceSearchResultPathname: {
  from: '/docs/',
  to: '/',
},
*/

2. Re-deploy your website

3. Re-run the crawler if necessary

Empty Index (0 Records)

If your index shows “No records yet”:

1. Check the crawler logs for any errors
2. Verify that your site is accessible to the crawler
3. Ensure your crawler configuration is correct
4. Try running the crawler again

Additional Tips

1. Contextual Search: Keep contextualSearch: true to ensure search results are relevant to the current language and version of your docs.
2. Custom Styling: You can customize the appearance of the search modal by adding CSS variables to your custom.css file.
3. Regular Updates: Re-run your crawler periodically to keep your search index updated with new content.
4. Multiple Indexes: If you have different types of content (docs, blog, etc.), you might need multiple indexes or a unified search approach.

Conclusion

You’ve successfully set up Algolia DocSearch for your Docusaurus website! Your users can now quickly find relevant content using the powerful search functionality. Remember to update your search index regularly by re-running the crawler whenever you add significant new content.

For more advanced configurations, refer to the Algolia DocSearch documentation and the Docusaurus search documentation.

The pursuit of a minimalist living space is more than just an aesthetic choice — it’s a pathway to inner peace and clarity. Drawing inspiration from Yamashita Eiko’s transformative work “The Art of Discarding”, let’s explore how to create a living space that nurtures both body and soul.

The Philosophy of Letting Go

At its core, the minimalist living philosophy isn’t simply about discarding items — it’s about maintaining a healthy flow of energy in your living space. As Yamashita teaches, there are three fundamental aspects to this practice:

• Cutting: Breaking free from material desires
• Discarding: Letting go of unnecessary items
• Separating: Detaching from emotional connections to objects

The Three-Space Principle

A truly minimalist home recognizes three essential types of spaces:

Hidden Storage Spaces (70% Rule)

• Closets, drawers, and cabinets should be only 70% full
• Allows for easy access and natural flow
• Creates breathing room for items

Visible Storage Spaces (50% Rule)

• Display cabinets and open shelving
• Keep only half full for aesthetic balance
• Maintains visual harmony

Display Spaces (10% Rule)

• Countertops and surface areas
• Minimal decoration creates maximum impact
• Follows the principle of “less is more”

Creating a Breathing Space

A key insight from Yamashita’s work is the concept of creating a “breathing space.” This means:

• Removing stagnant energy by eliminating unused items
• Maintaining clear pathways for movement
• Allowing natural light to flow freely
• Creating spaces between objects

The Practice of Mindful Selection

When deciding what to keep in your space, apply these three criteria:

1. Necessity: Is this item truly needed?
2. Functionality: Does it serve a current purpose?
3. Joy: Does it bring genuine happiness?

Implementation Steps

Assessment

• Survey your entire living space
• Identify problem areas
• Document current state

Categorization

• Sort items into distinct categories
• Apply the three-space principle
• Group similar items together

Decision Making

• Use the mindful selection criteria
• Be honest about each item’s value
• Consider the space’s overall harmony

Organization

• Implement storage solutions
• Maintain proper spacing
• Create sustainable systems

Benefits of a Minimalist Space

The rewards of creating a minimalist living environment extend beyond the physical:

• Mental Clarity: Reduced visual clutter leads to clearer thinking
• Reduced Stress: Organized spaces lower anxiety levels
• Increased Productivity: Everything has its place and purpose
• Better Sleep: Peaceful environments promote better rest
• Enhanced Creativity: Clear spaces foster creative thinking

Maintaining the Balance

Remember that minimalism is not about deprivation — it’s about optimization. The goal is to create a space that supports your life rather than complicating it. Regular maintenance includes:

• Daily quick tidying sessions
• Weekly organization reviews
• Monthly decluttering practices
• Seasonal deep cleaning

Conclusion

Creating a minimalist living space is a journey, not a destination. As Yamashita Eiko teaches, it’s about developing a new relationship with our possessions and our space. By implementing these principles, we can create homes that not only look beautiful but feel deeply nurturing to our well-being.

The key is to start small, be consistent, and remember that every item you choose to keep should earn its place in your space. Through this practice, we can create living environments that truly support our best lives.

Remember, the goal isn’t to create a spartan environment devoid of personality, but rather to craft a space where every item has purpose and meaning. In doing so, we create not just a minimalist space, but a sanctuary for modern living.