CannaCopilot

Mobile-first cultivation intelligence platform with AI-assisted scouting, plant history, and operational tracking.

CannaCopilot helps professional cannabis cultivators document, analyze, track, and improve plant health and crop performance using image analysis, historical comparison, operational logs, and AI-assisted recommendations.

Tech Stack

Layer	Technology
Mobile	Expo + React Native + TypeScript (expo-router, NativeWind)
State	Zustand (client) + TanStack Query (server) + Supabase Realtime
Backend Platform	Supabase (Auth, Postgres, Storage, Realtime)
AI Service	FastAPI (Python 3.12+)
AI Provider	Google Gemini (primary vision analysis)
Monorepo	Turborepo + pnpm
Shared Types	Zod schemas in packages/shared

Repository Map

apps/mobile/       Expo React Native app (TypeScript)
apps/api/          FastAPI AI analysis service (Python 3.12+)
packages/shared/   Shared Zod schemas, types, constants (@cannacopilot/shared)
supabase/          PostgreSQL migrations, storage config, seed data
docs/              Product specs, architecture docs, operational guides
scripts/           Dev scripts and tooling

Getting Started

Prerequisites

• Node.js 22 LTS
• pnpm 10+ (via corepack: corepack enable && corepack prepare pnpm@latest --activate)
• Python 3.12+
• uv (Python package manager)
• Supabase CLI (npx supabase --version)
• Expo Go app on a physical device (iOS or Android)
• Android Studio or Xcode for emulator/simulator (optional)

Setup

# Clone the repo
git clone https://github.com/stevenschling13/CannaCopilot.git
cd CannaCopilot

# Install Node dependencies
pnpm install

# Set up Python virtual environment for the API
cd apps/api
uv venv
uv pip install -e ".[dev]"
cd ../..

# Copy environment file and fill in credentials
cp .env.example .env

# Link Supabase project (requires a Supabase project)
npx supabase link --project-ref <your-project-ref>

# Apply database migrations
npx supabase db push

# Start development
pnpm dev              # Starts Expo mobile app
cd apps/api && uvicorn app.main:app --reload  # Starts FastAPI (separate terminal)

Validation Commands

# Node workspaces (mobile + shared)
pnpm lint             # ESLint across all TS workspaces
pnpm typecheck        # TypeScript type checking
pnpm test             # Jest tests

# Python API
cd apps/api
uv run ruff check .   # Lint
uv run ruff format --check .  # Format check
uv run pytest         # Tests

Core User Flow

The primary flow that drives the entire app:

1. Scout — User selects a room/zone/plant, takes 1–3 photos
2. Analyze — AI analyzes images for stage, health, issues, and recommendations
3. Save — Observation saved with images, AI results, and operator notes
4. Act — User reviews recommendations, creates tasks, tracks follow-ups
5. Compare — Timeline shows trends over time with historical comparison

Architecture

See docs/architecture/system-design.md for the full system design.

Key principles:

• Supabase handles auth, database, storage, and realtime — no custom auth or file servers
• FastAPI service handles AI analysis only — it does not serve the mobile app
• All mobile ↔ API communication goes through typed schemas in packages/shared
• RLS policies enforce organization-level data isolation at the database layer
• Single AI provider (Gemini) with a clean provider interface for future extensibility

Documentation

Document	Purpose
Product Spec	Full product definition
MVP Scope	What's in/out for MVP
User Flows	Core user flow definitions
System Design	Architecture and service boundaries
Data Model	Database schema and relationships
AGENTS.md	AI agent instructions
CONTRIBUTING.md	Contribution guidelines

License

MIT — see LICENSE.