MónAI

Vietnam's AI-Powered Food Trend Intelligence

MónAI helps F&B brands spot viral dishes, forecast adoption, analyze menu gaps, compare regional trends, and discover suppliers — before competitors launch. The repo is a monorepo: a Vietnamese street-food–inspired marketing landing page (React) and a FastAPI backend wired for TinyFish search + OpenAI analysis.

Table of contents

• Overview
• Architecture
• Product workflow
• Tech stack
• Project structure
• Getting started
• Environment variables
• API reference
• Landing page
• Design system
• Deployment
• Project status

Overview

Architecture

System context

API request flow

Every intelligence endpoint follows the same pipeline: gather signals → analyze with AI → return structured JSON.

Forecast path (optional OpenAI prose only — no invented scores):

Deployment topology

Product workflow

The landing page visualizes MónAI's end-to-end flow as a bánh mì assembled layer by layer:

Tech stack

Frontend

Fonts: Playfair Display · Bebas Neue · Be Vietnam Pro

Backend

Runtime: Python 3.12.8 (runtime.txt)

Project structure

MonAI/
├── main.py                      # FastAPI app entry + CORS
├── requirements.txt
├── runtime.txt
├── render.yaml                  # Render deploy blueprint
├── .env.example                 # Backend env template
│
├── app/
│   ├── routes/
│   │   ├── trends.py            # Emerging, forecast, regional
│   │   ├── analysis.py          # Menu gap analysis
│   │   └── suppliers.py         # Discovery + RFQ outreach
│   └── services/
│       ├── tinyfish_client.py   # Search + fetch wrappers
│       ├── ai_client.py         # OpenAI chat completions
│       ├── report_builder.py    # Report generation
│       ├── response_parser.py   # Response parsing + metric stripping
│       └── search_analysis.py   # Search result analysis
│
└── frontend/
    ├── vercel.json              # SPA rewrites
    ├── .env.example             # VITE_API_BASE_URL
    ├── src/
    │   ├── main.tsx
    │   ├── styles.css           # MónAI design tokens (oklch)
    │   ├── routes/
    │   │   ├── __root.tsx       # Fonts, meta, og tags
    │   │   └── index.tsx        # Landing page composition
    │   ├── components/
    │   │   ├── monai/           # Landing sections
    │   │   └── ui/              # shadcn/ui primitives
    │   ├── lib/
    │   │   ├── api.ts           # Backend client (env-driven)
    │   │   └── utils.ts
    │   └── assets/              # Food illustrations (.webp) + leaf texture
    └── package.json

Frontend component map

Getting started

Prerequisites

• Node.js 20+ and npm
• Python 3.12+
• API keys (for backend only): OpenAI, TinyFish

1. Clone and install

git clone <your-repo-url>
cd MonAI

Frontend

cd frontend
npm install
cp .env.example .env    # optional for landing-only preview
npm run dev

Open http://localhost:5173.

Backend

cd ..                   # repo root
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env    # fill in values — see below
uvicorn main:app --reload --port 8000

Open http://localhost:8000/docs for interactive Swagger UI.

Required: Set TINYFISH_API_KEY in .env. Search and Fetch go through the official TinyFish Python SDK. OPENAI_API_KEY is optional for richer synthesis.

2. Connect frontend to backend (optional)

In frontend/.env:

VITE_API_BASE_URL=http://localhost:8000
VITE_DEFAULT_LOCATION=TP.HCM

In root .env:

ALLOWED_ORIGINS=http://localhost:5173

The landing page and dashboard call the live API via src/lib/api.ts (Vite dev proxy or VITE_API_BASE_URL).

Environment variables

Backend (.env at repo root)

Frontend (frontend/.env)

API reference

Base URL: http://localhost:8000 (local) or your Render service URL.

Trends

Example — emerging trends

curl "http://localhost:8000/api/trends/emerging?location=TP.HCM&category=beverage"

Analysis

{
  "current_menu_items": ["Cà phê sữa đá", "Bạc xỉu"],
  "location": "Hà Nội",
  "competitor_urls": ["https://example.com/menu"]
}

Suppliers

Health

Landing page

The home route (frontend/src/routes/index.tsx) is a single-page marketing site with seven sections:

Illustrations live in frontend/src/assets/ (pho.png, banhmi.png, capthrung.png, banhxeo.png, bunbohue.png, leaf.jpg).

Design system

Tokens are defined in frontend/src/styles.css using oklch and semantic aliases — no hardcoded hex in components.

Typography: --font-display (Playfair Display) · --font-punch (Bebas Neue) · --font-vn (Be Vietnam Pro)

Motifs: rice-paper texture, banana-leaf dividers, rubber-stamp seals, Vietnamese star bullets, chopstick underlines, steam wisps.

Deployment

Frontend → Vercel

1. Import the GitHub repo in Vercel.
2. Set Root Directory to frontend.
3. Framework preset: Vite (auto-detect).
4. Build command: npm run build · Output: dist.
5. Add env var when connecting to backend:
   code复制

   VITE_API_BASE_URL=https://<your-render-service>.onrender.com

frontend/vercel.json handles SPA routing:

{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

Backend → Render (free tier)

Option A — Manual (recommended for free):

1. Render Dashboard → New → Web Service → connect repo.

2. Do not use Blueprint if it prompts for paid workspace — create the service manually instead.

3. Settings:

   • Root directory: leave empty (repo root)
   • Runtime: Python
   • Instance type: Free (not Starter)
   • Build command: pip install -r requirements.txt
   • Start command: uvicorn main:app --host 0.0.0.0 --port $PORT
   • Health check path: /health

4. Environment variables:

   Key	Example
   ALLOWED_ORIGINS	https://your-app.vercel.app
   TINYFISH_API_KEY	your key from agent.tinyfish.ai/api-keys
   OPENAI_API_KEY	optional

Option B — Blueprint (render.yaml):

render.yaml includes plan: free and runtime: python. Without plan: free, Render defaults to Starter ($7/mo).

1. New → Blueprint → select repo.
2. Confirm the service shows Free instance before applying.

Post-deploy checklist

• Backend / returns JSON on Render
• Backend /docs loads
• ALLOWED_ORIGINS includes exact Vercel URL (no trailing slash)
• Frontend builds without VITE_API_BASE_URL (landing works standalone)
• CORS preflight succeeds from Vercel origin

Project status

Known considerations

• Backend deps: Use a virtualenv with pinned requirements.txt (tinyfish, fastapi, etc.).
• .env syntax: Ensure no unquoted special characters; dotenv warns on malformed lines.

Scripts reference