Bellyful - Cross-Platform Meal Planning App

Project Overview

Bellyful is a meal planning platform designed around a practical kitchen workflow: track what is already in the pantry, plan meals around real inventory, and shop only for what is missing. The product includes a public marketing experience, a protected web dashboard, an Expo mobile app, shared frontend contracts, and a FastAPI backend.

Key Features

  • Pantry-aware planning: Food inventory, expiry attention, meal plans, and shopping lists are modeled as connected workflows instead of separate notes.
  • Cross-platform UI: Next.js powers the web experience while Expo and React Native support mobile access for store and kitchen use cases.
  • Shared domain layer: TypeScript DTOs, API clients, auth helpers, onboarding logic, and design tokens live in a shared package so web and mobile behavior stay aligned.
  • Protected product area: Authenticated users can manage pantry batches, meal plans, recipes, ingredient restrictions, shopping lists, and profile state.
  • Typed backend foundation: FastAPI, SQLModel, Pydantic schemas, JWT auth, email workflows, and pytest coverage provide the API layer for the product.

Technical Architecture

bellyful-ui/
  web/       # Next.js App Router web app
  mobile/    # Expo Router React Native app
  shared/    # Shared TypeScript contracts and helpers

bellyful-api/
  app/       # FastAPI routes, schemas, services, and database models
  docs/      # Product requirements, flows, and planning docs
  tests/     # Pytest suites for API behavior

Implementation Highlights

Product Workflow

The product is centered on the loop from pantry to meal plan to shopping list. That shape keeps the user experience grounded in daily food decisions instead of forcing users to maintain unrelated lists.

Frontend System

The web app uses Next.js App Router, React 19, Mantine, and feature-scoped route modules. Shared UI-adjacent logic, DTOs, auth helpers, and API clients are exported from @bellyful/shared, reducing duplication between web and mobile.

Mobile Companion

The Expo app mirrors the main food planning surfaces so users can check pantry items, update shopping lists, and reference meal plans away from the desktop. This matters for the two places the product is most useful: the store aisle and the kitchen.

Backend Services

The FastAPI service provides the foundation for account management, secure authentication, user workflows, media handling, and transactional email. The backend is typed with Pydantic and SQLModel and verified with pytest, mypy, Ruff, Black, and isort.

Technical Stack

Web

  • Next.js App Router
  • React
  • TypeScript
  • Mantine
  • Playwright and Vitest

Mobile

  • Expo Router
  • React Native
  • TypeScript
  • Shared service and form primitives

Backend

  • FastAPI
  • SQLModel and SQLAlchemy
  • Pydantic
  • JWT authentication
  • Pytest, mypy, Ruff, Black, and isort

Conclusion

Bellyful demonstrates a full-product implementation that spans product design, frontend architecture, mobile ergonomics, shared contracts, and backend service design. The project focuses on turning a common household problem into a clear, connected planning flow that can grow across devices and deeper food workflows.