Overview

This section documents the Next.js web app: a modern implementation of the public site using Next.js, Tailwind CSS, shadcn/ui, and Zustand.

Management Tool Hierarchy (Abstract)

This diagram shows the "what controls what" hierarchy of management roles, reflecting the ideal way to manage development environments.

graph TD
    SYS["System Package Manager (e.g. winget, brew)"] --> VM["Version Manager (e.g. nvm, asdf)"]
    VM --> RT["Language Runtime (e.g. Node.js)"]
    RT --> WRAP["Manager Wrapper (e.g. Corepack)"]
    RT --> NPM["Bundled Manager (e.g. npm)"]
    WRAP --> PM["External Package Manager (e.g. pnpm, yarn)"]
    PM --> DEP["Project Dependencies (Libraries)"]
    NPM --> DEP
    DEP --> APP["Application Codebase"]
    SYS --> B_RT["Independent Runtime/PM (e.g. Bun)"]
    B_RT --> DEP

Management Tool Hierarchy (Specific)

This diagram shows the specific tools used and recommended in this ecosystem.

graph TD
    W["UniGetUI / winget"] --> NODE["Node.js 24"]
    NODE --> CP["Corepack"]
    CP --> PNPM["pnpm 11.17.0\npackageManager pin"]
    PNPM --> WS["pnpm workspace root"]
    WS --> NEXT["site-nextjs\nNext.js"]
    WS --> SHARED["shared"]
    WS --> SOLID["site-solidstart\nretired archive"]
    NEXT --> DEP["App dependencies"]

This repo pins Node 24 and pnpm 11.17.0 at the monorepo root. See Tooling.

Features

Patrons

  • Search for food trucks by name

  • View food trucks on a map and see what is nearby

  • Track food trucks in your area (including status/open information where available)

  • Explore community content and owner resources designed to help you choose great trucks

  • Responsive design for mobile and desktop

Owners

  • Register and manage a food truck linked to Square POS

  • Publish a reliable presence so customers can discover where you are and when you are open

  • Public events and host venues: post gigs (stipend / budget / bids), review applications; publish recurring venue schedules

  • Enhanced check-in system:

    • GPS-based nearby addresses discovery

    • Advanced map-based location selection

    • Distance indicators for nearby addresses

    • One-click check-in from nearby locations

    • Automatic checkout with time spans

  • Food truck management (CRUD operations) and menu sync via Square integration

  • Community forum / discussion space for owner-to-owner exchange

  • Industry stats and insights, plus blogs/resources to help owners become more successful

  • Networking-style connection points and other ecosystem resources for owner growth

Technologies Used

  • Next.js 15: React framework with App Router

  • React 19: UI library

  • Tailwind CSS 4: Utility-first CSS framework

  • shadcn/ui: Reusable UI components built with Radix UI

  • Zustand: State management library

  • Radar SDK: Maps and location services

  • Convex: Backend database and real-time sync

  • Square API: POS integration

  • Resend: Transactional email (host requests, etc.)

  • Customer.io (planned): Marketing and multi-channel journeys — Email, SMS, Push, In-app (see Messaging & marketing)

  • Twilio (planned): SMS transport under Customer.io / account OTPs

Project Structure

ftn-nextjs/
├── app/              # Next.js App Router
│   ├── actions/      # Server actions
│   ├── api/          # API routes
│   └── manage/       # Management pages
├── components/       # React components
│   ├── ui/           # shadcn/ui components
│   ├── food-trucks/  # Food truck components
│   ├── map/          # Map components
│   └── checkin/      # Check-in components
├── convex/           # Convex backend
├── lib/              # Utility functions
├── store/            # Zustand stores
└── public/           # Static assets

Getting Started

Choose one of the following paths:

  • Option A: Manual Setup (DIY) (baseline, cross-platform)

  • Option B: External Dev Setup App (optional UX)

Development Scripts

  • run.ps1 – Start dev server, build, lint, format

Environment Variables

See Environment variables for details.

Documentation