| # SolarWine — Production Architecture |
|
|
| ## Overview |
|
|
| Migrate from a single-process Streamlit prototype to a 3-layer production system |
| deployed on free-tier infrastructure. The monorepo stays — no new repositories. |
|
|
| ``` |
| Baseline/ (monorepo) |
| ├── frontend/ NEW — Lovable-generated React app |
| │ ├── src/ |
| │ │ ├── pages/ |
| │ │ │ ├── Dashboard.tsx Overview + energy + weather |
| │ │ │ ├── Advisor.tsx Chatbot + advisory cards |
| │ │ │ ├── Control.tsx System status + tracker angles |
| │ │ │ ├── Photosynthesis.tsx FvCB/ML results + forecasts |
| │ │ │ ├── Shading.tsx Interactive simulator |
| │ │ │ └── Docs.tsx Documentation |
| │ │ ├── components/ |
| │ │ │ ├── EnergyCard.tsx |
| │ │ │ ├── WeatherCard.tsx |
| │ │ │ ├── Chatbot.tsx |
| │ │ │ ├── TrackerStatus.tsx |
| │ │ │ └── Charts.tsx Recharts / Plotly wrappers |
| │ │ ├── hooks/ |
| │ │ │ ├── useWeather.ts fetch /api/weather/* |
| │ │ │ ├── useEnergy.ts fetch /api/energy/* |
| │ │ │ ├── useSensors.ts fetch /api/sensors/* |
| │ │ │ ├── useChatbot.ts POST /api/chatbot/message |
| │ │ │ └── useControl.ts fetch /api/control/* |
| │ │ ├── lib/ |
| │ │ │ └── api.ts API base URL + fetch wrapper |
| │ │ └── App.tsx Router + layout |
| │ ├── package.json |
| │ └── tailwind.config.js |
| │ |
| ├── backend/ NEW — FastAPI middleware + background services |
| │ ├── api/ |
| │ │ ├── __init__.py |
| │ │ ├── main.py FastAPI app, CORS, lifespan |
| │ │ ├── routes/ |
| │ │ │ ├── weather.py GET /api/weather/* |
| │ │ │ ├── sensors.py GET /api/sensors/* |
| │ │ │ ├── energy.py GET /api/energy/* |
| │ │ │ ├── photosynthesis.py GET /api/photosynthesis/* |
| │ │ │ ├── control.py GET /api/control/* |
| │ │ │ ├── chatbot.py POST /api/chatbot/message |
| │ │ │ └── health.py GET /api/health |
| │ │ ├── deps.py Shared dependencies (DataHub, Redis) |
| │ │ └── auth.py JWT middleware (Phase 11.6) |
| │ ├── workers/ |
| │ │ ├── control_tick.py ControlLoop 15-min cron entry point |
| │ │ └── daily_planner.py DayAheadPlanner daily cron entry point |
| │ ├── Dockerfile |
| │ └── requirements.txt |
| │ |
| ├── .github/ |
| │ └── workflows/ |
| │ ├── control-tick.yml GitHub Actions: 15-min cron |
| │ └── daily-planner.yml GitHub Actions: daily 05:00 IST cron |
| │ |
| ├── src/ UNCHANGED — shared Python core |
| │ ├── control_loop.py |
| │ ├── command_arbiter.py |
| │ ├── tracker_dispatcher.py |
| │ ├── day_ahead_planner.py |
| │ ├── energy_budget.py |
| │ ├── data/ |
| │ │ ├── data_providers.py DataHub + 6 services |
| │ │ ├── thingsboard_client.py |
| │ │ └── ims_client.py |
| │ ├── chatbot/ |
| │ │ ├── vineyard_chatbot.py |
| │ │ ├── guardrails.py |
| │ │ └── routing_agent.py |
| │ ├── models/ |
| │ │ ├── farquhar_model.py |
| │ │ └── phenology.py |
| │ ├── forecasting/ |
| │ │ ├── predictor.py |
| │ │ └── ts_predictor.py |
| │ ├── shading/ |
| │ │ ├── solar_geometry.py |
| │ │ └── tradeoff_engine.py |
| │ └── ... |
| │ |
| ├── config/settings.py UNCHANGED — shared configuration |
| ├── app.py KEPT temporarily (Streamlit, deprecated) |
| ├── ui/ KEPT temporarily (Streamlit tabs, deprecated) |
| ├── docker-compose.yml NEW — local dev orchestration |
| └── requirements.txt Shared Python deps |
| ``` |
|
|
| --- |
|
|
| ## Layer 1 — The Brain (Backend Services) |
|
|
| ### What it is |
|
|
| All business logic, models, data access, and control algorithms. This layer |
| already exists in `src/`. The only change is extracting the runtime entry points |
| into `backend/workers/`. |
|
|
| ### Components |
|
|
| | Component | Module | Runtime | Schedule | |
| |-----------|--------|---------|----------| |
| | ControlLoop | `src/control_loop.py` | GitHub Actions cron | Every 15 min | |
| | DayAheadPlanner | `src/day_ahead_planner.py` | GitHub Actions cron | Daily 05:00 IST + re-plan events | |
| | DataHub | `src/data/data_providers.py` | Imported by API + workers | Always available | |
| | ThingsBoard client | `src/data/thingsboard_client.py` | Imported by DataHub | On-demand | |
| | IMS client | `src/data/ims_client.py` | Imported by DataHub | On-demand (30-min TTL) | |
| | FvCB model | `src/models/farquhar_model.py` | Imported by PhotosynthesisService | On-demand (~10ms) | |
| | ML ensemble | `src/forecasting/predictor.py` | Imported by PhotosynthesisService | On-demand (~500ms) | |
| | Chronos forecaster | `src/forecasting/ts_predictor.py` | Imported by PhotosynthesisService | On-demand (~2-5s) | |
| | CommandArbiter | `src/command_arbiter.py` | Imported by ControlLoop | Per tick | |
| | TrackerDispatcher | `src/tracker_dispatcher.py` | Imported by ControlLoop | Per tick | |
| | EnergyBudget | `src/energy_budget.py` | Imported by ControlLoop | Per tick | |
| | Chatbot + guardrails | `src/chatbot/*.py` | Imported by API route | Per message | |
|
|
| ### Caching strategy |
|
|
| | Data | Current | Production | |
| |------|---------|------------| |
| | IMS weather | In-memory TTLCache (30 min) | **Upstash Redis** (30 min TTL) | |
| | Vine sensors | In-memory TTLCache (5 min) | **Upstash Redis** (5 min TTL) | |
| | Energy daily | No cache | **Upstash Redis** (15 min TTL) | |
| | ML trained model | Pickle file | Pickle in `/tmp` + Redis metadata | |
| | Day-ahead plan | JSON file | Redis hash + JSON file backup | |
| | Chatbot history | Streamlit session_state | Redis list per session | |
| |
| ### External dependencies |
| |
| | Service | URL | Auth | Purpose | |
| |---------|-----|------|---------| |
| | ThingsBoard | `web.seymouragri.com` | Username/password → JWT | 21 sensors, 4 trackers, energy | |
| | IMS | `api.ims.gov.il` | API token | Weather station 43 (Sde Boker) | |
| | Google Gemini | `generativelanguage.googleapis.com` | API key | Chatbot (2.5-flash), routing | |
| | Upstash Redis | `*.upstash.io` | Token | Shared cache | |
| |
| --- |
| |
| ## Layer 2 — Middleware (FastAPI on HuggingFace Spaces) |
| |
| ### What it is |
| |
| A thin Python API layer that wraps `DataHub` services as REST endpoints. Hosted |
| on **HuggingFace Spaces** (Docker SDK, free tier) — Python-native, no cold starts |
| on the free tier's persistent container. |
| |
| ### Tech stack |
| |
| | Component | Technology | Why | |
| |-----------|-----------|-----| |
| | Framework | **FastAPI** | Same Python team, async, auto-docs, WebSocket | |
| | Serialization | **Pydantic v2** | Already a FastAPI dependency, typed responses | |
| | Auth | **JWT** (PyJWT) | Simple, stateless, no external IdP needed initially | |
| | Rate limiting | **slowapi** | Token bucket per IP, protects Gemini quota | |
| | CORS | FastAPI `CORSMiddleware` | Allow Cloudflare Pages frontend origin | |
| | WebSocket | FastAPI WebSocket | Live tracker angles, energy push (future) | |
| | Process manager | **uvicorn** | ASGI server, production-ready | |
| | Hosting | **HuggingFace Spaces** (Docker SDK) | Free, Python-native, persistent container | |
| |
| ### HuggingFace Space configuration |
| |
| The API Space uses Docker SDK. A `Dockerfile` at `backend/` builds the FastAPI |
| server. The Space README metadata: |
| |
| ```yaml |
| --- |
| title: SolarWine API |
| emoji: 🌿 |
| colorFrom: green |
| colorTo: yellow |
| sdk: docker |
| app_port: 7860 |
| private: true |
| --- |
| ``` |
| |
| Note: HF Spaces exposes port 7860, so FastAPI binds to `0.0.0.0:7860`. |
| |
| ### API endpoints |
| |
| ``` |
| Health |
| GET /api/health → { status, uptime, redis_ok, tb_ok } |
|
|
| Weather |
| GET /api/weather/current → WeatherService.get_current() |
| GET /api/weather/history?days=7 → WeatherService.get_history() |
| GET /api/weather/forecast → WeatherService.get_forecast() |
| |
| Vine Sensors |
| GET /api/sensors/snapshot → VineSensorService.get_snapshot() |
| GET /api/sensors/history?type=crop&hours=24 → VineSensorService.get_history() |
| |
| Energy |
| GET /api/energy/current → EnergyService.get_current() |
| GET /api/energy/daily/{date} → EnergyService.get_daily_production() |
| GET /api/energy/history?hours=24 → EnergyService.get_history() |
| GET /api/energy/predict/{date} → EnergyService.predict() |
| |
| Photosynthesis |
| GET /api/photosynthesis/current → PhotosynthesisService.get_current() |
| GET /api/photosynthesis/forecast → PhotosynthesisService.forecast_day_ahead() |
|
|
| Control |
| GET /api/control/status → Last TickResult from Redis |
| GET /api/control/plan → Current DayAheadPlan from Redis |
| GET /api/control/budget → EnergyBudget current state |
| GET /api/control/trackers → Live tracker angles from TB |
|
|
| Chatbot |
| POST /api/chatbot/message → VineyardChatbot.chat() |
| Body: { message, session_id } |
| Response: { message, confidence, sources, caveats, rule_violations } |
| |
| POST /api/chatbot/feedback → feedback.log_feedback() |
| Body: { session_id, message_id, rating, comment } |
| |
| Biology |
| GET /api/biology/phenology → BiologyService current stage |
| GET /api/biology/rules → All biology rules |
| ``` |
| |
| ### Middleware stack (order matters) |
| |
| 1. **CORS** — allow `*.pages.dev` + localhost |
| 2. **Rate limiter** — 60 req/min general, 10 req/min chatbot (Gemini costs) |
| 3. **Auth** — JWT validation (initially optional, enforced in Phase 11.6) |
| 4. **Request logging** — structured JSON logs |
| 5. **Error handler** — consistent error response format |
| |
| --- |
| |
| ## Layer 3 — Frontend (Lovable → Cloudflare Pages) |
| |
| ### What it is |
| |
| Production-grade React frontend generated via **Lovable** (AI-powered React |
| builder). Produces a standard Vite + React + TypeScript + Tailwind project. |
| Deployed to **Cloudflare Pages** (free tier, unlimited bandwidth, private org repos supported). |
| |
| Lovable generates the initial scaffold and components rapidly. After generation, |
| the code is committed to the monorepo under `frontend/` and maintained manually |
| or with further Lovable iterations. |
| |
| ### Tech stack |
| |
| | Component | Technology | Why | |
| |-----------|-----------|-----| |
| | Generator | **Lovable** | AI-generated React UI, rapid prototyping | |
| | Framework | **React 19 + Vite** | Lovable default output, fast build | |
| | Language | **TypeScript** | Type safety, IDE support | |
| | Styling | **Tailwind CSS + shadcn/ui** | Lovable default, beautiful components | |
| | Charts | **Recharts** (default) or **Plotly.js** | Data visualization | |
| | HTTP | **TanStack Query** (React Query) | Auto-refresh, caching, loading states | |
| | Routing | **React Router** | Page navigation | |
| | Hosting | **Cloudflare Pages** (free) | Unlimited bandwidth, private org repos, global CDN, auto-deploy from GitHub | |
| |
| ### Pages (mapped from current Streamlit tabs) |
| |
| | Streamlit Tab | React Page | Route | Key Components | |
| |---------------|------------|-------|----------------| |
| | Vineyard Advisor | `Advisor.tsx` | `/` | Chatbot, weather card, energy card, shading card, irrigation card | |
| | System Status | `Control.tsx` | `/control` | Tracker angles, energy budget gauge, control replay, ROI | |
| | Overview | `Dashboard.tsx` | `/dashboard` | Energy history, crop comparisons | |
| | Photosynthesis & Data | `Photosynthesis.tsx` | `/photosynthesis` | FvCB/ML results, sensor explorer | |
| | Forecasting | — | merged into `/dashboard` | Weather + PS forecast cards | |
| | Shading Simulator | `Shading.tsx` | `/shading` | Interactive offset tester | |
| | Documentation | `Docs.tsx` | `/docs` | Help, API reference | |
| |
| ### Data fetching pattern |
| |
| Using TanStack Query for all API calls. Auto-refetch on window focus and |
| configurable polling intervals. |
| |
| ```typescript |
| // hooks/useWeather.ts |
| import { useQuery } from "@tanstack/react-query"; |
| import { api } from "@/lib/api"; |
| |
| export function useCurrentWeather() { |
| return useQuery({ |
| queryKey: ["weather", "current"], |
| queryFn: () => api.get("/api/weather/current"), |
| refetchInterval: 60_000, // 60s auto-refresh |
| }); |
| } |
| ``` |
| |
| ```typescript |
| // lib/api.ts |
| const API_URL = import.meta.env.VITE_API_URL; |
| |
| export const api = { |
| get: async (path: string) => { |
| const res = await fetch(`${API_URL}${path}`); |
| if (!res.ok) throw new Error(res.statusText); |
| return res.json(); |
| }, |
| post: async (path: string, body: unknown) => { |
| const res = await fetch(`${API_URL}${path}`, { |
| method: "POST", |
| headers: { "Content-Type": "application/json" }, |
| body: JSON.stringify(body), |
| }); |
| if (!res.ok) throw new Error(res.statusText); |
| return res.json(); |
| }, |
| }; |
| ``` |
| |
| ### Frontend ↔ Backend communication |
|
|
| | Pattern | Use Case | Protocol | |
| |---------|----------|----------| |
| | REST | All data reads, chatbot messages | HTTPS (fetch via TanStack Query) | |
| | Polling | Dashboard auto-refresh | 60s interval via `refetchInterval` | |
| | WebSocket | Live tracker angles, energy (future) | WSS (native WebSocket, future) | |
|
|
| --- |
|
|
| ## Infrastructure & Deployment |
|
|
| ### Hosting (all free tier) |
|
|
| | Layer | Platform | Tier | Limits | |
| |-------|----------|------|--------| |
| | Frontend | **Cloudflare Pages** | Free | Unlimited bandwidth, 500 builds/month, auto-deploy from GitHub | |
| | API server | **HuggingFace Spaces** | Free (Docker SDK) | 2 vCPU, 16GB RAM, persistent container, private spaces | |
| | Cron workers | **GitHub Actions** | Free (private repos) | 2,000 min/month, plenty for 15-min cron + daily planner | |
| | Cache | **Upstash Redis** | Free | 10K commands/day, 256MB, REST API | |
| | Secrets | **HF Space secrets** + **Cloudflare env vars** + **GitHub Actions secrets** | Free | Per-service | |
| | Repo | **GitHub** | Free private | Unlimited | |
|
|
| ### Deployment topology |
|
|
| ``` |
| GitHub (private repo, main branch) |
| │ |
| ├──── push ────► Cloudflare Pages (auto-deploy) |
| │ ├── frontend/ → Vite build → static React app |
| │ ├── URL: baseline.pages.dev (or custom domain) |
| │ └── Env: VITE_API_URL=https://<user>-solarwine-api.hf.space |
| │ |
| ├──── push ────► HuggingFace Space (auto-deploy via HF GitHub sync) |
| │ ├── backend/ → Dockerfile → FastAPI (uvicorn, port 7860) |
| │ ├── URL: https://<user>-solarwine-api.hf.space |
| │ └── Secrets: TB creds, IMS token, Gemini key, Redis URL |
| │ |
| └──── cron ────► GitHub Actions (scheduled workflows) |
| ├── control-tick.yml: */15 * * * * → pip install + python control_tick.py |
| ├── daily-planner.yml: 0 2 * * * (02:00 UTC = 05:00 IST) |
| └── Secrets: TB creds, IMS token, Redis URL |
| |
| Upstash Redis |
| └── URL: solarwine-cache-*.upstash.io (shared by API + workers) |
| ``` |
|
|
| ### GitHub Actions cron workflows |
|
|
| The ControlLoop and DayAheadPlanner run as scheduled GitHub Actions. This |
| replaces the need for a separate worker host. |
|
|
| ```yaml |
| # .github/workflows/control-tick.yml |
| name: Control Loop Tick |
| on: |
| schedule: |
| - cron: "*/15 * * * *" # every 15 min |
| workflow_dispatch: # manual trigger |
| |
| jobs: |
| tick: |
| runs-on: ubuntu-latest |
| steps: |
| - uses: actions/checkout@v4 |
| - uses: actions/setup-python@v5 |
| with: |
| python-version: "3.12" |
| cache: pip |
| - run: pip install -r requirements.txt -r backend/requirements.txt |
| - run: python -m backend.workers.control_tick |
| env: |
| THINGSBOARD_HOST: ${{ secrets.THINGSBOARD_HOST }} |
| THINGSBOARD_USERNAME: ${{ secrets.THINGSBOARD_USERNAME }} |
| THINGSBOARD_PASSWORD: ${{ secrets.THINGSBOARD_PASSWORD }} |
| IMS_API_TOKEN: ${{ secrets.IMS_API_TOKEN }} |
| UPSTASH_REDIS_URL: ${{ secrets.UPSTASH_REDIS_URL }} |
| UPSTASH_REDIS_TOKEN: ${{ secrets.UPSTASH_REDIS_TOKEN }} |
| ``` |
|
|
| ```yaml |
| # .github/workflows/daily-planner.yml |
| name: Day-Ahead Planner |
| on: |
| schedule: |
| - cron: "0 2 * * *" # 02:00 UTC = 05:00 IST |
| workflow_dispatch: |
| |
| jobs: |
| plan: |
| runs-on: ubuntu-latest |
| steps: |
| - uses: actions/checkout@v4 |
| - uses: actions/setup-python@v5 |
| with: |
| python-version: "3.12" |
| cache: pip |
| - run: pip install -r requirements.txt -r backend/requirements.txt |
| - run: python -m backend.workers.daily_planner |
| env: |
| THINGSBOARD_HOST: ${{ secrets.THINGSBOARD_HOST }} |
| THINGSBOARD_USERNAME: ${{ secrets.THINGSBOARD_USERNAME }} |
| THINGSBOARD_PASSWORD: ${{ secrets.THINGSBOARD_PASSWORD }} |
| IMS_API_TOKEN: ${{ secrets.IMS_API_TOKEN }} |
| GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }} |
| UPSTASH_REDIS_URL: ${{ secrets.UPSTASH_REDIS_URL }} |
| UPSTASH_REDIS_TOKEN: ${{ secrets.UPSTASH_REDIS_TOKEN }} |
| ``` |
|
|
| ### Docker setup (HuggingFace Space) |
|
|
| ```dockerfile |
| # backend/Dockerfile |
| FROM python:3.12-slim |
| |
| WORKDIR /app |
| COPY requirements.txt . |
| COPY backend/requirements.txt backend/ |
| RUN pip install -r requirements.txt -r backend/requirements.txt |
| |
| COPY src/ src/ |
| COPY config/ config/ |
| COPY backend/ backend/ |
| COPY Data/ Data/ |
| |
| ENV PYTHONPATH=/app |
| |
| # HuggingFace Spaces requires port 7860 |
| EXPOSE 7860 |
| CMD ["uvicorn", "backend.api.main:app", "--host", "0.0.0.0", "--port", "7860"] |
| ``` |
|
|
| ### Environment variables |
|
|
| | Variable | Where | Source | |
| |----------|-------|--------| |
| | `THINGSBOARD_HOST` | HF Space, GH Actions | HF secrets, GH secrets | |
| | `THINGSBOARD_USERNAME` | HF Space, GH Actions | HF secrets, GH secrets | |
| | `THINGSBOARD_PASSWORD` | HF Space, GH Actions | HF secrets, GH secrets | |
| | `IMS_API_TOKEN` | HF Space, GH Actions | HF secrets, GH secrets | |
| | `GOOGLE_API_KEY` | HF Space, GH Actions | HF secrets, GH secrets | |
| | `UPSTASH_REDIS_URL` | HF Space, GH Actions | HF secrets, GH secrets | |
| | `UPSTASH_REDIS_TOKEN` | HF Space, GH Actions | HF secrets, GH secrets | |
| | `JWT_SECRET` | HF Space | HF secrets | |
| | `ALLOWED_ORIGINS` | HF Space | HF secrets (Cloudflare Pages URL) | |
| | `VITE_API_URL` | Cloudflare Pages | Cloudflare env vars (HF Space URL) | |
|
|
| --- |
|
|
| ## Data Flow |
|
|
| ### Request flow (user views dashboard) |
|
|
| ``` |
| Browser → Cloudflare CDN → React SPA (static) |
| │ |
| └── useQuery → fetch https://<user>-solarwine-api.hf.space/api/weather/current |
| │ |
| ▼ |
| FastAPI route (HuggingFace Spaces) |
| │ |
| ▼ |
| DataHub.weather.get_current() |
| │ |
| ├── Redis cache hit? → return cached |
| └── Redis miss → IMS API → cache → return |
| ``` |
|
|
| ### Control flow (15-min tick) |
|
|
| ``` |
| GitHub Actions cron (*/15 * * * *) |
| │ |
| └── python -m backend.workers.control_tick |
| │ |
| ▼ |
| ControlLoop.tick() |
| │ |
| ├── DataHub.weather.get_current() → IMS (via Redis cache) |
| ├── DataHub.vine_sensors.get_snapshot() → ThingsBoard |
| ├── RoutingAgent → FvCB or ML model |
| ├── DayAheadPlan lookup → Redis |
| ├── InterventionGate check |
| ├── BudgetGuard check |
| ├── CommandArbiter → decide angle |
| ├── TrackerDispatcher → ThingsBoard shared attributes |
| ├── EnergyBudget.spend_slot() |
| └── Save TickResult → Redis (for API /control/status) |
| ``` |
|
|
| ### Chatbot flow |
|
|
| ``` |
| Browser → React → POST /api/chatbot/message { message, session_id } |
| │ |
| ▼ |
| FastAPI route (HF Space) → VineyardChatbot.chat(message, hub=DataHub) |
| │ |
| ├── QueryClassifier → data / knowledge / greeting |
| ├── Gemini Pass 1 → tool calls (if data query) |
| ├── DataHub.dispatch_tool() → real data |
| ├── tag_tool_result() → source metadata |
| ├── Gemini Pass 2 → grounded response |
| ├── ResponseValidator → rule checks |
| ├── estimate_confidence() |
| └── Return ChatResponse → JSON → Browser |
| ``` |
|
|
| --- |
|
|
| ## Security |
|
|
| | Concern | Mitigation | |
| |---------|-----------| |
| | API keys in repo | `.env` in `.gitignore`; secrets in HF/Cloudflare/GH settings | |
| | TB credentials | Server-side only; frontend never sees TB creds | |
| | Gemini API abuse | Rate limit 10 req/min on `/api/chatbot/message` | |
| | CORS | Whitelist Cloudflare Pages domain only | |
| | Auth (Phase 11.6) | JWT tokens; initially optional for research use | |
| | Tracker commands | Only GH Actions worker can write to TB; API is read-only | |
| | HF Space | Set to **private** — not publicly accessible without auth | |
|
|
| --- |
|
|
| ## Migration from Streamlit |
|
|
| The existing `app.py` and `ui/` folder remain functional throughout migration. |
| They are deprecated once the Lovable frontend reaches feature parity. |
|
|
| | Phase | Streamlit | Lovable/React | Notes | |
| |-------|-----------|---------------|-------| |
| | 11.1–11.3 | Primary | Not started | Backend being built | |
| | 11.4 | Primary | Scaffold | Pages generated via Lovable | |
| | 11.5 | Deprecated | Primary | Feature parity reached | |
| | 11.6+ | Removed | Primary | Auth, monitoring, polish | |
|
|
| --- |
|
|
| ## Scaling path (when free tier is outgrown) |
|
|
| | Bottleneck | Upgrade | Cost | |
| |-----------|---------|------| |
| | HF Space resources | HF Space upgrade (2× CPU, 16GB) | $0 (already free) → $9/mo for GPU | |
| | GitHub Actions minutes | GitHub Team (3,000 min) | $4/user/mo | |
| | Upstash 10K commands/day | Upstash Pay-as-you-go ($0.20/100K) | ~$1/mo | |
| | Cloudflare Pages | Already unlimited on free tier | $0 | |
| | Heavy ML inference | Add GPU worker (Modal/RunPod) | $5–10/mo | |
| | Multi-site (>1 vineyard) | Add Postgres (Neon free) for multi-tenant state | Free → $19/mo | |
|
|
| Total cost to run a real commercial deployment: **~$25/month**. |
|
|
