What’s Changed Since Launch

In Part 1, I introduced Mipaka — a free REST API for administrative divisions across 7 East/Central African countries. The focus was the basics: cascading dropdowns, search, filtering, and bulk export.

Since then, the API has grown significantly. Here’s everything new.

By the Numbers

Why did the division count drop? Rwanda’s data was resynced with corrected upstream sources, removing duplicate villages. The data is more accurate now.

47 Historical Eras

Every country now has a complete chain of eras — from pre-colonial kingdoms through colonial occupation to the present day.

GET /api/v1/eras/?country=CD

DRC alone has 7 eras:

Uganda has 10 eras — including 8 pre-colonial kingdoms and chiefdoms with their current rulers:

• Buganda Kingdom (~1300–present) — Kabaka Ronald Muwenda Mutebi II
• Bunyoro-Kitara Kingdom (~1300–present) — Omukama Solomon Gafabusa Iguru I
• Kingdom of Toro (~1830–present) — Omukama Oyo Nyimba Kabamba Iguru Rukidi IV
• Kingdom of Ankole (~1500–1967) — abolished, never restored
• Busoga Kingdom (~1500–present) — Kyabazinga William Wilberforce Gabula Nadiope IV

Each era carries notes, date ranges, colonial power tracking, and links to the divisions that existed during that period.

124 Historical Place Names

Major cities now have their full naming history — indigenous, colonial, and modern names mapped to specific eras and languages.

Kinshasa through the centuries:

GET /api/v1/divisions/{kinshasa_id}/names/

[
  {
    "name": "Nshasa",
    "language": "Kikongo",
    "name_type": "indigenous",
    "era_name": "Kingdom of Kongo",
    "etymology": "Named after Nshasa village on the riverbank"
  },
  {
    "name": "Léopoldville",
    "language": "French",
    "name_type": "colonial",
    "era_name": "Congo Free State",
    "etymology": "Named after King Leopold II by Henry Morton Stanley (1881)"
  },
  {
    "name": "Kinshasa",
    "language": "Lingala",
    "name_type": "official",
    "era_name": "Democratic Republic of the Congo",
    "etymology": "Restored to indigenous name at independence (1966)"
  }
]

Name coverage by country:

229 Historical Divisions

Beyond current administrative boundaries, the API now includes divisions that no longer exist — searchable by country and level:

# Kenya's 8 former provinces (1963–2010)
GET /api/v1/divisions/?country=KE&level=100

# DRC's 11 provinces under Mobutu (1997–2015)
GET /api/v1/divisions/?country=CD&level=100

# South Sudan's 28 states (2015–2020 decree)
GET /api/v1/divisions/?country=SS&level=100

Level 100 is a convention used to separate historical divisions from active administrative data — they won’t appear in standard queries unless you filter explicitly.

What’s available:

Historical divisions use is_active=false so they don’t pollute standard queries. Filter explicitly to find them.

DRC Deep Data: 325 Records Across 6 Administrative Eras

DRC got the biggest upgrade. The original API had 174 records (provinces + territories). It now has 325 records tracing how the country was divided from Leopold’s 15 districts in 1910 to today’s 26 provinces:

Plus 34 cities with coordinates — the first geo-coded data in the API.

What’s Next

This data enrichment sets the foundation for features coming soon:

• Coordinates for all countries — DRC is the pilot, on the roadmap expand to Kenya, Uganda, and others
• GeoJSON boundaries — polygon data for map rendering
• Population data — census figures tied to divisions

Try It

Try the live explorer at mipaka.dev — pick a country, drill through divisions, and see historical eras in action.

Everything above is also available on RapidAPI with a free tier, and the code is open source on GitHub — MIT licensed.

The historical data is the part of Mipaka I’m most proud of. There’s nothing else like it — a structured, queryable dataset of how African cities and borders have changed across centuries. If you’re a historian, genealogist, or just someone who finds African history fascinating, I’d genuinely love your contributions. The data is open source — PRs welcome.

Links

• Website: mipaka.dev
• API Docs: api.mipaka.dev/api/docs/
• API on RapidAPI: rapidapi.com/ceddyville/api/mipaka
• GitHub: github.com/ceddyville/mipaka-api

Coming Next

This is Part 2 of the Mipaka API series. Missed the intro? Start with Part 1: Mipaka: A Free REST API for 100K+ Administrative Divisions Across East Africa.

Next up:

• Part 3: From Léopoldville to Kinshasa — 500 Years of African Border Changes

Follow me to catch the next one!

Mipaka — every border, one API.

Traditional methods for detecting element visibility (like scroll event listeners combined with getBoundingClientRect()) are notoriously inefficient. They force the browser to re-layout the page repeatedly, leading to jank and poor user experience, especially on mobile devices. The Intersection Observer API offers a modern, performant solution to determine when an element enters or exits the viewport, or even intersects with another element. It allows developers to defer loading resources or trigger actions only when necessary, significantly improving web performance. This guide dives into how to effectively leverage Intersection Observer for common use cases like lazy loading and infinite scrolling.

Understanding the Core Concept

At its heart, the Intersection Observer API asynchronously observes changes in the intersection of a target element with an ancestor element or with the document’s viewport (referred to as the “root”). Instead of constantly polling for changes, it only triggers a callback function when the intersection threshold is crossed.

Key concepts:

• Target: The element you want to observe.
• Root: The element that is the ancestor of the target, defining the viewport for intersection checking. If null or undefined, the document’s viewport is used.
• Root Margin: A margin around the root. This value defines how much larger or smaller the root’s bounding box is before calculations. Similar to CSS margin properties (e.g., “10px 20px 30px 40px”).
• Thresholds: A single number or an array of numbers between 0.0 and 1.0, indicating at what percentage of the target’s visibility the observer’s callback should be executed. A value of 0.0 means the callback will fire as soon as a single pixel of the target element is visible. A value of 1.0 means the callback will fire when all of the target element is visible.

Basic Setup and Observation

Setting up an IntersectionObserver involves instantiating a new observer object and defining its callback function. This callback receives a list of IntersectionObserverEntry objects and the observer instance itself.

// 1. Define the callback function
const handleIntersection = (entries, observer) => {
  entries.forEach(entry => {
    // Each 'entry' describes an intersection change for one observed target
    if (entry.isIntersecting) {
      console.log('Element is now visible:', entry.target);
      // Optional: Stop observing once it's visible if it's a one-time action
      // observer.unobserve(entry.target);
    } else {
      console.log('Element is no longer visible:', entry.target);
    }
    console.log('Intersection ratio:', entry.intersectionRatio);
  });
};

// 2. Create an observer instance
// Options object is optional; defaults to viewport root, no root margin, threshold 0.0
const options = {
  root: null, // Use the document viewport as the root
  rootMargin: '0px', // No margin around the root
  threshold: 0.5 // Trigger when 50% of the target is visible
};

const observer = new IntersectionObserver(handleIntersection, options);

// 3. Select target elements and observe them
const targetElements = document.querySelectorAll('.observe-me');
targetElements.forEach(element => {
  observer.observe(element);
});

This code snippet first defines handleIntersection, a function that will be called whenever a target element’s intersection status changes. It iterates through the entries array, checking entry.isIntersecting to determine if the element has entered or exited the root. Next, options are defined; here, root: null means the browser’s viewport is the reference, and threshold: 0.5 means the callback fires when 50% of the target element becomes visible or invisible. Finally, an IntersectionObserver instance is created, and it starts observing all elements matching the .observe-me selector.

Real-world Use Case: Lazy Loading Images

A common and impactful use case is lazy loading images. Instead of loading all images on page load, which consumes bandwidth and impacts Initial Load time, we can load them only when they are about to enter the viewport.

<!-- Example HTML for lazy loading images -->
<img data-src="image1.jpg" alt="Image 1" class="lazy-image">
<img data-src="image2.jpg" alt="Image 2" class="lazy-image">
<img data-src="image3.jpg" alt="Image 3" class="lazy-image">
<!-- ... many more images ... -->

const lazyLoadImages = (entries, observer) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      const img = entry.target;
      const src = img.getAttribute('data-src');

      if (src) {
        img.setAttribute('src', src); // Set the actual src attribute
        img.removeAttribute('data-src'); // Remove data-src to prevent re-loading
        observer.unobserve(img); // Stop observing once loaded
      }
    }
  });
};

const imgOptions = {
  root: null, // Viewport
  rootMargin: '0px 0px 100px 0px', // Load images 100px before they enter the viewport
  threshold: 0 // As soon as any part is visible
};

const imageObserver = new IntersectionObserver(lazyLoadImages, imgOptions);

const imagesToLoad = document.querySelectorAll('.lazy-image');
imagesToLoad.forEach(image => {
  imageObserver.observe(image);
});

This JavaScript code targets all img elements with the class lazy-image and a data-src attribute. The lazyLoadImages callback checks if an image (entry.target) is isIntersecting. If it is, the data-src value is moved to the src attribute, effectively loading the image. Importantly, observer.unobserve(img) is called immediately after loading to prevent unnecessary future observations. The rootMargin: '0px 0px 100px 0px' in imgOptions pre-loads images when they are 100 pixels below the viewport, ensuring a smoother user experience as they scroll.

Real-world Use Case: Infinite Scrolling

Another powerful application is implementing infinite scrolling, where new content loads automatically as the user approaches the end of a page. This typically involves observing a “sentinel” element placed at the bottom of your content list.

// Assume 'contentContainer' is the parent of your dynamically loaded items
// and 'loadingIndicator' is an element at the bottom, initially hidden, acting as the sentinel.
const contentContainer = document.getElementById('content-list');
const loadingIndicator = document.getElementById('loading-spinner'); // Our sentinel

let page = 1; // Track current page for API requests
let isLoading = false; // Prevent multiple simultaneous loads

const loadMoreContent = async () => {
  if (isLoading) return;
  isLoading = true;
  console.log(`Loading page ${page}...`);

  // Simulate an API call
  try {
    const response = await fetch(`/api/items?page=${page}&limit=10`);
    const newItems = await response.json();

    newItems.forEach(item => {
      const div = document.createElement('div');
      div.textContent = `Item ${item.id} - from page ${item.page}`;
      contentContainer.appendChild(div);
    });

    page++;
  } catch (error) {
    console.error('Failed to load more content:', error);
  } finally {
    isLoading = false;
  }
};

const infiniteScrollObserver = new IntersectionObserver((entries, observer) => {
  entries.forEach(entry => {
    if (entry.isIntersecting && !isLoading) {
      // Sentinel is visible, load more content
      loadMoreContent();
    }
  });
}, {
  root: null, // Viewport
  rootMargin: '0px',
  threshold: 0.1 // Trigger when 10% of the sentinel is visible
});

// Start observing the loading indicator
infiniteScrollObserver.observe(loadingIndicator);

// Initial load (optional, or done via server-side rendering)
// loadMoreContent();

This example shows how to set up infinite scrolling. A loadingIndicator (often a spinner or simple div) acts as a sentinel. When this loadingIndicator enters the viewport (determined by entry.isIntersecting), the loadMoreContent function is triggered. This function simulates fetching new data, appends it to contentContainer, and increments the page counter. A isLoading flag is crucial to prevent multiple loadMoreContent calls while an API request is already in flight. The threshold: 0.1 means the observer fires as soon as 10% of the loadingIndicator is visible, giving enough time for new content to load before the user reaches the very bottom.

Common Mistakes and Gotchas

While powerful, Intersection Observer has its nuances:

• Not Unobserving: For one-time actions like lazy loading an image, remember to call observer.unobserve(entry.target) after the action is complete. Failing to do so keeps the observer active, potentially triggering the callback multiple times unnecessarily.
• Misunderstanding intersectionRatio vs. isIntersecting: isIntersecting is a boolean indicating if any part of the target is currently intersecting the root. intersectionRatio gives the percentage (0.0 to 1.0) of the target that is intersecting. For simple visibility checks, isIntersecting is often sufficient and clearer. Use intersectionRatio when you need finer control, e.g., triggering an event only when an element is fully visible (intersectionRatio === 1).
• Over-optimizing threshold: Providing a large array of threshold values (e.g., [0, 0.1, 0.2, ..., 1.0]) will cause the callback to fire frequently. For many use cases, a single threshold value like 0 (any visibility) or 0.1 (10% visible) is sufficient and more performant.
• Root Margin vs. Threshold: rootMargin expands or shrinks the root’s bounding box before intersection calculations. This is useful for “pre-loading” or “pre-triggering” actions (like loading images 200px before they reach the viewport). threshold specifies what percentage of the target must be visible within the (potentially adjusted) root. Don’t confuse their roles.
• Observing Dynamically Added Elements: If you’re adding elements to the DOM after the initial setup (e.g., for infinite scroll), remember to call observer.observe() on these new elements if they also need to be observed. For infinite scroll, typically you only observe the single sentinel element, not all the new items.

Key Takeaways

The Intersection Observer API is a fundamental tool for modern web development, offering a highly performant and efficient way to detect element visibility without blocking the main thread. By offloading intersection checks to the browser’s optimized asynchronous mechanisms, it significantly reduces layout thrashing and improves responsiveness. Its declarative nature simplifies code for common patterns like lazy loading and infinite scrolling, making your applications faster and more user-friendly.

Conclusion

Mastering Intersection Observer is crucial for building high-performance web applications that provide a smooth and engaging user experience. By implementing the techniques discussed, you can dramatically improve your site’s Core Web Vitals, particularly Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS), by loading resources intelligently. Start integrating Intersection Observer into your projects today and unlock a new level of web performance.

For years, my checklist for choosing a React state library was pretty standard:

• developer experience
• TypeScript support
• performance
• ecosystem

Now I use one more filter:

How well can an AI coding assistant understand, continue, and refactor the pattern?

That shift changed what I value, and it is one reason I keep coming back to easy-model instead of defaulting to Redux or even today’s more common lightweight choice, Zustand.

The AI Workflow Changed the Rules

The old assumption was simple: humans write the architecture, then humans maintain it.

That is no longer true for a lot of teams.

A more realistic workflow today looks like this:

• a human defines intent
• AI scaffolds a feature
• a human fixes the edge cases
• AI expands the next iteration

In that loop, architecture becomes communication.

Not just communication between teammates, but communication between humans and models.

If the codebase hides intent behind too many disconnected layers, the AI starts guessing. And when AI starts guessing inside your state layer, things get weird fast.

Redux tends to push that guessing into multiple layers.
Zustand tends to hide it behind a deceptively simple store that keeps absorbing more responsibility over time.

What “AI Compatibility” Actually Means

I do not mean “the model can produce a demo with it.”

Almost every popular library can get a decent hello-world out of an assistant.

Redux can do it.
Zustand can definitely do it.

I mean:

• can the AI find the right place for new logic?
• can it extend existing patterns instead of inventing a new one?
• can it update a feature without scattering logic across files?
• can it read the business model from the code itself?

That is where I think easy-model is unusually strong.

Why easy-model Is Easier for Models to Continue

easy-model organizes state around model classes:

• fields hold state
• methods hold business behavior
• components consume instances via useModel or useInstance

That creates a very direct map between business intent and code structure.

Here is the kind of code AI tools seem to handle well:

class SearchWorkspaceModel {
  query = '';
  results: SearchResult[] = [];
  filters: string[] = [];
  selectedId: string | null = null;

  setQuery(query: string) {
    this.query = query;
  }

  toggleFilter(filter: string) {
    this.filters = this.filters.includes(filter)
      ? this.filters.filter(item => item !== filter)
      : [...this.filters, filter];
  }

  select(id: string | null) {
    this.selectedId = id;
  }

  @loader.load()
  async search() {
    this.results = await api.search({
      query: this.query,
      filters: this.filters,
    });
  }
}

The business domain is obvious.
The actions are obvious.
The UI dependencies are obvious.

That alone makes AI-generated follow-up changes much more stable.

This Becomes Even More Valuable in AI Products

If you are building:

• chat UIs
• agent dashboards
• retrieval interfaces
• multi-panel copilots
• tool-execution consoles

you are dealing with unusually rich frontend state.

Not just “is the modal open,” but:

• what is currently streaming
• which tool is running
• what the session history is
• which panel shares the same session
• how retries and logs behave

Those apps benefit from having state and behavior live in the same place.

For example:

class ChatWorkspaceModel {
  messages: Message[] = [];
  draft = '';
  streamingText = '';
  toolCalls: ToolCall[] = [];
  error: string | null = null;

  setDraft(draft: string) {
    this.draft = draft;
  }

  @loader.load(true)
  async send() {
    const content = this.draft.trim();
    if (!content) return;

    this.messages.push({ role: 'user', content });
    this.draft = '';
    this.error = null;

    try {
      const stream = await llm.stream(this.messages);
      for await (const chunk of stream) {
        this.streamingText += chunk;
      }

      this.messages.push({
        role: 'assistant',
        content: this.streamingText,
      });
      this.streamingText = '';
    } catch (error) {
      this.error = 'Send failed';
    }
  }
}

When an assistant sees this, it has far less ambiguity about where the next feature belongs.

The Supporting Pieces Matter Too

What makes easy-model practical is not just the model class pattern, but the utilities around it:

• instance sharing by arguments is useful for session-based UIs
• watchers help with logging, analytics, and side effects
• loading utilities reduce repetitive async state wiring
• IoC features make service boundaries cleaner in larger apps

That combination makes it a good fit for apps where business logic is not trivial and AI is expected to contribute repeatedly.

That is the gap I increasingly feel between easy-model and Zustand:

• Zustand wins on minimal entry cost
• easy-model wins once business behavior, shared instances, async flow, and AI-assisted extension all start compounding

Redux still has its place, but in day-to-day modern React discourse, Zustand is usually the more relevant comparison, and I think easy-model holds up well there.

My New Mental Model

I still care about ergonomics and performance.

But I now treat AI compatibility as a first-class architectural concern.

A state pattern is stronger if:

• a human can read it quickly
• an AI can continue it predictably
• both can locate business intent without hunting through five layers

That is the real reason easy-model stands out to me.

It does not just reduce boilerplate. It reduces ambiguity.

And ambiguity is exactly where AI-assisted codebases start to decay.

Closing

If you are evaluating React state management in an AI-assisted workflow, I would seriously add this question to your shortlist:

Will this pattern still feel coherent after ten rounds of human + AI iteration?

For me, easy-model is one of the few tools that earns a solid “yes” there.

GitHub: https://github.com/ZYF93/easy-model

npm: pnpm add @e7w/easy-model

If you are also thinking about AI compatibility as a real frontend architecture concern, a star on the repo would mean a lot.

Every few months, something drops that cuts through the AI hype and forces the conversation back to reality. This week, that something was ARC-AGI-3.

The results were blunt: every frontier AI model scored below 1%. Every human scored 100%.

Let that sink in for a second. Not some humans. Not specially trained humans. Every single person who attempted it, regardless of background, aced it. Meanwhile, the most powerful AI systems in existence, the same ones passing bar exams and writing production code, nearly completely failed.

If you’ve been building AI systems for any length of time, your gut reaction was probably somewhere between “I told you so” and “okay, but what does this mean for what I’m shipping?” That’s exactly the question worth digging into.

WHAT ARC-AGI-3 ACTUALLY TESTS

ARC-AGI isn’t your typical benchmark, and that’s the point. It’s not about trivia recall, coding ability, or text summarization. It was specifically designed to test abstract reasoning from first principles. The kind of task where you’re shown a small number of examples of a visual pattern transformation and have to figure out the underlying rule from scratch.

No prior knowledge helps. No retrieval helps. You can’t Google your way to the answer. You have to look at the examples, abstract the logic, and apply it to a new case you’ve never seen before.

Humans find this intuitive. We abstract patterns constantly, it’s one of the most fundamental things our brains do. Show a child three examples of a rule they’ve never been taught, and they’ll generalize it. Show a frontier LLM the same examples, and it will confidently give you a wrong answer based on a pattern it half-remembers from training.

That’s not a knowledge gap. That’s a reasoning gap.

THIS ISN’T A SCALE PROBLEM

The predictable response to any AI failure is: “give it more data, more parameters, more compute.” It’s become almost a mantra. But that narrative is getting harder to sustain.

We’ve been scaling aggressively for years. Each new model family came with promises of emergent capabilities and breakthrough reasoning. Some of those promises were real – coding, analysis, writing, structured reasoning have all improved substantially. But ARC-AGI has barely moved despite years of scaling.

LeCun has been arguing this point for a while: next-token prediction has a fundamental ceiling for certain types of reasoning, and throwing more compute at it won’t fix the architecture. His new venture just raised $1 billion to pursue Energy-Based Models as an alternative. Whether EBMs actually work at scale remains to be seen, but the underlying observation is increasingly hard to dismiss.

If the architecture is the constraint, you can’t benchmark-engineer or fine-tune your way out of it. And for engineers building production systems, that has real consequences.

HOW THIS PLAYS OUT IN PRODUCTION

Here’s what happens when teams treat the latest model as a near-complete replacement for human judgment.

The system works beautifully on the easy cases — which is most of the traffic. Speed is good, costs are low. Then edge cases start showing up. And AI failures at the boundary don’t fail quietly. They fail confidently. The model produces an answer that looks perfectly reasonable, stated with full certainty, that happens to be completely wrong in a way that violates a rule it was never taught to reason about from scratch.

These aren’t just wrong answers. They’re wrong answers that pass basic sanity checks. They slip through unless someone who actually understands the domain is paying attention.

That’s the gap ARC-AGI-3 is measuring. Not “can this model do most things well”, it clearly can. But “can it reason to a correct answer when it has never encountered this specific structure before, with no retrieved knowledge to fall back on?” The answer, consistently, is no.

HITL ISN’T A CRUTCH – IT’S AN ARCHITECTURAL DECISION

Human-in-the-Loop has an image problem. In a lot of technical conversations, it gets framed as the fallback you use before the AI is good enough – something you eventually eliminate as the model improves.

ARC-AGI-3 is strong evidence that this framing is wrong. Not all HITL is about compensating for a model that isn’t there yet. Some of it is about designing honestly around what AI systems structurally cannot do.

The question isn’t whether to include humans in the loop. It’s where, how much, and for what. Getting that right is actually a sophisticated engineering problem, and most teams rush past it.

1. Route the hard cases, not all the cases. Build a reliable routing layer using confidence scoring, uncertainty quantification, or task-specific heuristics to identify inputs where the model is likely to fail and route only those for human review.

2. Treat every human correction as a training signal. Every override or validation is a labeled data point. Systems that capture this systematically get better over time. Systems that treat human review as a one-way gate leave the most valuable feedback on the table.

3. Design for graceful degradation, not silent failure. The worst failure mode is confident wrongness. A well-designed system knows when it’s uncertain and triggers a handoff rather than producing a confident bad output.

4. Be honest about the boundary. There’s a category of task where the model shouldn’t be the final decision-maker, not because the model is bad, but because the task requires novel abstract reasoning. Identifying that boundary honestly is the job.

THE DEEPER TAKEAWAY

ARC-AGI-3 is useful precisely because it forces clarity on a question teams tend to answer optimistically: what can AI actually do, and what is it structurally limited at?

The honest answer in 2026 is that AI systems are genuinely capable and getting better and they have a real ceiling on certain types of abstract reasoning that hasn’t moved despite years of scaling. Both things are true at the same time.

The teams that build the most reliable AI systems aren’t the ones who bet hardest on that ceiling disappearing. They’re the ones who design honestly around it, keeping humans in the loop not because the model is bad, but because they’ve thought carefully about where human judgment is irreplaceable.

Human judgment isn’t going away. The job is to figure out exactly where it matters most, and build accordingly.

This is a submission for the Notion MCP Challenge

What I Built

I buy in bulk at Costco to save money. The problem: tracking 100+ pantry items, remembering what’s expiring, and figuring out what to cook for a two-person household with different food preferences.

Pantry & Plate is an AI-powered pantry tracker and meal planner that eliminates that cognitive load. It parses grocery receipts using Claude’s vision, tracks expiry dates in Notion, and runs an agentic chat assistant that knows exactly what’s in my kitchen, what needs to be used first, and what my partner won’t eat (mushrooms, shrimp, brussels sprouts).

Here’s what makes it different: when I ask “What can I make tonight?”, the agent doesn’t guess. It queries my actual Notion databases — pantry items with real expiry dates, my household preferences, my planned meals for the week — then reasons over the results before suggesting anything.

The agent might respond: “The Italian sausage expires in four days. How about a quick sausage pasta with the San Marzano tomatoes from your pantry? I’ll add it to your meal agenda.”

That’s not a canned response. The agent read Expiry Date: March 30 from my Notion Pantry database.

Key Features

• Receipt parsing with human-in-the-loop review: Upload a photo of a Costco receipt. Claude’s vision parses “KS ORG STOCK” into “Kirkland Organic Chicken Stock” (it guesses). You review and correct before saving.
• Compact pantry view: 100+ items grouped by category, collapsible sections, inline editing, expiry date tracking.
• 11-tool conversational agent: Query pantry, shopping list, meal history, preferences, kitchen tools, and meal agenda — all via natural language.
• Shopping list with purchase-to-pantry flow: Check “purchased” → item moves to pantry automatically.
• Preferences as silent context: The agent knows my partner hates mushrooms. It never narrates this — just excludes them.

Video Demo

Show us the code

https://github.com/Aprattcodes/pantry-tracker

Stack

• Next.js 15, TypeScript, Tailwind v4, shadcn/ui
• Anthropic Claude API (vision for OCR, forced tool use for parsing, agentic loops)
• Notion as the persistent data layer (6 databases)
• @notionhq/client v2

How I Used Notion MCP

We implemented the MCP tool-use pattern — Claude decides which of 11 tools to call, queries live Notion data, and reasons over results in an agentic loop — using @notionhq/client v2 with integration tokens.

We initially attempted mcp.notion.com but it requires OAuth authentication, which doesn’t fit a server-side web application architecture where the backend needs persistent database access. The agentic pattern is structurally identical to an MCP client-server interaction: tool discovery, tool invocation, result handling, multi-turn reasoning. The transport layer differs, but the intelligence pattern is the same.

The Agentic Loop in Action

Here’s how chatAgent() works:

// 11 tools available to the agent
const CHAT_TOOLS = [
  { name: 'query_pantry', description: 'Get all pantry items with expiry dates' },
  { name: 'query_preferences', description: 'Get household food preferences' },
  { name: 'query_meal_agenda', description: 'Get planned meals for the week' },
  { name: 'suggest_meals', description: 'Generate meal suggestions' },
  { name: 'add_to_meal_agenda', description: 'Add a meal to the weekly plan' },
  { name: 'log_meal', description: 'Log a meal to history' },
  // ... 5 more tools
];

// The loop: Claude calls tools, we execute, Claude reasons over results
while (response.stop_reason === 'tool_use' && iterations < 8) {
  const toolUse = response.content.find(c => c.type === 'tool_use');

  // Execute against real Notion databases
  const result = await executeNotionTool(toolUse.name, toolUse.input);

  // Feed result back to Claude for reasoning
  messages.push({ role: 'user', content: [{ type: 'tool_result', content: result }] });
  response = await anthropic.messages.create({ model, messages, tools: CHAT_TOOLS });
}

When the user says “What can I make tonight?”, Claude decides to:

1. Call query_preferences → learns one of us hates mushrooms, we both love Mexican food
2. Call query_pantry → sees Italian sausage expires in four days
3. Call query_meal_agenda → checks what’s already planned
4. Call suggest_meals → generates contextual suggestions

The agent makes multiple Notion queries in a single conversational turn, reasoning over real data — not summaries.

Notion as the Data Layer

Six databases power the entire system:

The agent can query any of these, cross-reference them, and write back. When I say “Add Italian sausage pasta to my meal plan,” it:

1. Calls add_to_meal_agenda → writes to Meal Agenda DB
2. Auto-triggers log_meal → writes to Meals Log DB

Two Notion writes from a single conversational command.

Human-in-the-Loop Receipt Parsing

Costco receipts are cryptic. “KS ORG STOCK” means Kirkland Signature Organic Chicken Stock. We use Claude’s vision with forced tool use to guarantee structured output:

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 4096, // Required for 27+ item receipts
  tool_choice: { type: 'tool', name: 'record_pantry_items' },
  // ...
});

The parsed items appear in a review table — original receipt text on the left, Claude’s interpretation on the right. The human corrects mistakes, picks expiry dates, then saves. The review step is critical: Claude makes educated guesses, but a human confirms before anything hits Notion.

Key Technical Decisions

Forced tool use for structured output: tool_choice: { type: "tool", name: "record_pantry_items" } guarantees JSON output. Prompt engineering alone was unreliable for 27+ item receipts.

max_tokens: 4096 for long receipts: Below this threshold, Claude silently truncates. Discovered this the hard way with a Costco run.

Preferences as silent context: Early versions narrated preferences (“I see you don’t like mushrooms…”). Now the agent applies them without explanation — like a real kitchen assistant would.

Store inference from preferences: When the user says “add ground beef to my shopping list,” the agent queries preferences, finds “household buys ground beef at Costco,” and auto-sets store=Costco, quantity=3 lbs.

Purchase-to-pantry flow: Checking “purchased” on a shopping list item creates a pantry entry with the same name/store/quantity. One checkbox replaces a manual two-step process.

Reflections

Building this taught me that the MCP pattern isn’t about the transport layer — it’s about giving an AI agent live data access and the autonomy to query what it needs. Whether that’s via a remote MCP server or a custom tool wrapper around @notionhq/client, the intelligence pattern is the same: tool discovery, invocation, result handling, multi-turn reasoning.

The hardest part wasn’t the agentic loop — it was the UX around it. Making tool calls visible (we show “tool pills” in the chat), handling the max_tokens stop reason gracefully, and ensuring the agent doesn’t narrate its reasoning when it should just act.

Notion as a data layer worked surprisingly well. The real-time queries mean the agent always has accurate state. No stale caches, no sync issues. When I buy groceries and check them off, the next “What can I make?” query sees the updated pantry.

For a two-person household that meal plans around Costco runs and expiring produce, this is the tool I actually wanted to exist.

Built by a developer who got tired of throwing away forgotten produce.