🌍 Atlas Core - Precision Agriculture Platform

Transform agricultural data into actionable intelligence for African farmers through satellite imagery, AI plant diagnostics, and predictive analytics.

---

📋 What is Atlas Core?

Atlas Core is an intelligent geospatial platform designed to empower African farmers with data-driven decision-making. It combines:

• 📸 AI Plant Diagnostics - Photograph plants, get instant disease detection
• 🛰️ Satellite Field Monitoring - NDVI-based crop health visualization
• 💡 Smart Recommendations - AI-powered irrigation, fertilizer, pest control advice
• 🌤️ Weather Intelligence - Agricultural forecasts and alerts
• 📈 Historical Analytics - Track field performance over time

Current Status: ✅ Phase 2 MVP - 75% Complete | Auth + Camera + Recommendations Working

---

🚀 Quick Start (2 Minutes)

1. Setup

npm install
cp .env.example .env.local
# Add Supabase credentials

2. Seed Test Data

npm run seed:test-data

3. Start

npm run dev
# Open http://localhost:5000

4. Test

Create account → Click "Atlas Agri" → Explore modules

📖 Full setup guide: QUICKSTART.md

---

📚 Documentation (Start Here!)

Document	Purpose	Read Time
QUICKSTART.md	Setup + testing	10 min
PROJECT_STATUS.md	Current progress + blockers	15 min
CLAUDE.md	Architecture principles	20 min
CHANGELOG.md	Commit history	10 min
CAMERA_SATELLITE_SETUP.md	API integration guide	30 min

👉 New to this project? Start with QUICKSTART.md

---

📊 What's Working Now ✅

• ✅ Authentication - Login/signup with Supabase + VIP admin access code
• ✅ Recommendations - Load real data from database, filter by category, mark complete
• ✅ Plant Scanning - Camera capture + OpenAI Vision AI diagnosis (with mock fallback)
• ✅ Sidebar Navigation - 6-section AgriModule with smooth animations
• ✅ Test Data - npm run seed:test-data creates 2 farms + 4 parcels + 3 scans + 5 recommendations
• ✅ Services Layer - All Supabase queries properly abstracted
• ✅ State Management - Zustand stores for auth + agricultural data
• ✅ TypeScript + Theme - Strict types, responsive design, professional animations

🔄 What's In Progress ⏳

• ⏳ Photo Upload - Camera captures images, NOT yet uploaded to Supabase storage (HIGH PRIORITY)
• ⏳ Weather Forecast - UI 100% complete, API integration needs real OpenWeatherMap wiring
• ⏳ Satellites/NDVI - Map UI ready, needs real Sentinel Hub data integration
• ⏳ Dashboard - UI skeleton complete, needs real farm/parcel data binding
• ⏳ Scan History - UI structure ready, needs data connection

Full details: PROJECT_STATUS.md | Audit: CODE_AUDIT_2026-05-28.md

---

🏗️ Architecture Overview

UI Components (React Native)
    ↓ calls store actions
Zustand Stores (authStore, agriStore)
    ↓ triggers service calls
Services Layer (Business logic + API calls)
    ↓ queries
External APIs (Supabase, OpenAI, Weather, Satellites)

Key Principles:

• ✅ Services handle all API calls
• ✅ Stores handle state + errors
• ✅ Components display data only
• ✅ Everything strictly typed

See CLAUDE.md for full architecture.

---

📱 Module Status

Atlas Agri (Main MVP)

Module	Status	What It Does
Tableau de bord	50%	Farm overview structure ready, needs real data binding
Carte du champ	55%	Interactive NDVI grid UI ready, needs Sentinel Hub API
Scan de plante	85% ✅	Camera capture + AI diagnosis working, photo upload TODO
Recommandations	100% ✅	Load from DB, filter, mark complete — fully functional
Météo agricole	60%	UI 100% complete, weather API needs real integration
Historique	50%	UI structure ready, needs to load real scan history

---

🔑 Environment Setup

Minimal (Works with Mock Data)

EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJhbGc...

Full (Real APIs)

# Required
EXPO_PUBLIC_SUPABASE_URL=...
SUPABASE_ANON_KEY=...

# Optional (falls back to mock if not provided)
OPENAI_API_KEY=sk-proj-...        # Plant diagnosis
EXPO_PUBLIC_WEATHER_API_KEY=...   # Weather forecast
EXPO_PUBLIC_SENTINEL_HUB_TOKEN=... # Satellite data (Sentinel Hub)
# Optional compatibility alias:
# SENTINEL_HUB_TOKEN=...          # Satellite data (legacy)

Get API keys:

• Supabase: https://supabase.com
• OpenAI: https://platform.openai.com (requires payment)
• OpenWeatherMap: https://openweathermap.org (free tier)
• Sentinel Hub: https://sentinelhub.com (free tier)

---

🧪 Test Data

Pre-seeded realistic data for demo:

npm run seed:test-data

Creates:

• 2 Farms: Kayes (Mali) + Bamako (Mali)
• 4 Parcels: Different crops + health scores
• 3 Scans: Plant diagnostics with confidence scores
• 5 Recommendations: Urgent to low priority

Perfect for testing without external APIs.

---

📝 Development Workflow

Start a Task

# 1. Read current status
cat PROJECT_STATUS.md

# 2. Make changes
npm run typecheck  # Check types
npm run lint       # Check style

# 3. Test locally
npm run dev

# 4. Commit using conventional commits
git commit -m "feat: Add real satellite integration"
git commit -m "fix: Correct weather API"
git commit -m "docs: Update README"

# 5. Update docs
# - CHANGELOG.md (what changed)
# - PROJECT_STATUS.md (progress update)

Commands

npm run dev              # Start dev server (web)
npm run dev:ios          # iOS simulator
npm run dev:android      # Android emulator
npm run typecheck        # TypeScript validation
npm run lint            # Code style check
npm run seed:test-data  # Load test data
npm run build:web       # Production web build

---

🐛 Known Issues

Issue	Severity	Timeline
Photos not uploading to Supabase storage	Medium	This week
Satellite NDVI currently mock data	Medium	This week
Weather not displayed in UI	Low	This week
Dashboard not showing live data	Low	Next week

See PROJECT_STATUS.md for details.

---

🚀 Next Priorities

This Week

1. Real Satellite NDVI (3-4h)

   • Fetch from Sentinel Hub
   • Update map to show real grid

2. Weather Display (1-2h)

   • Wire AgriMeteo to store
   • Show forecast

3. Photo Upload (2h)

   • Store camera photos to Supabase

Next Week

1. Dashboard Connections (2-3h)
2. Performance Optimization (2h)
3. Error Handling (2h)

Full roadmap: PROJECT_STATUS.md

---

📂 Project Structure

atlas-core/
├── app/                        # Expo Router navigation
├── components/
│   ├── agri/                   # Atlas Agri modules
│   │   ├── AgriScan.tsx        # Camera + AI diagnosis ✅
│   │   ├── AgriRecommandations.tsx  # Real data ✅
│   │   ├── AgriNDVIMap.tsx     # Satellite visualization
│   │   ├── AgriMeteo.tsx       # Weather
│   │   ├── AgriDashboard.tsx   # Dashboard
│   │   └── AgriHistorique.tsx  # History
│   ├── auth/                   # Login/signup screens
│   └── hub/                    # Module selection
├── lib/
│   ├── services/
│   │   ├── auth.ts             # Supabase Auth
│   │   ├── plantDiagnosis.ts   # OpenAI Vision ✅
│   │   ├── farms.ts, parcels.ts, scans.ts...
│   │   └── index.ts
│   ├── stores/
│   │   ├── authStore.ts        # User auth state ✅
│   │   └── agriStore.ts        # Agricultural data ✅
│   ├── types.ts                # TypeScript interfaces
│   ├── theme.ts                # Design tokens
│   └── env.ts                  # Environment validation
├── scripts/
│   └── seed.ts                 # Test data seeding ✅
├── supabase/
│   └── migrations/             # Database schema
├── docs/
│   ├── QUICKSTART.md           # Setup guide ✅
│   ├── PROJECT_STATUS.md       # Progress tracking ✅
│   ├── CAMERA_SATELLITE_SETUP.md # Integration guide ✅
│   └── CHANGELOG.md            # Commit history ✅
├── CLAUDE.md                   # Architecture ✅
└── package.json

---

🛠 Tech Stack

• Frontend: React Native 0.81 + Expo 54
• Navigation: Expo Router
• State: Zustand
• Database: Supabase (PostgreSQL + Auth + Storage)
• Language: TypeScript
• Styling: React Native StyleSheet + theme tokens
• Icons: Lucide React Native
• Validation: Zod

---

🔒 Security

• ✅ Row-level security (RLS) on all tables
• ✅ Secure token storage (encrypted on mobile + web)
• ✅ Input validation + sanitization
• ✅ Audit log for compliance
• ✅ HTTPS-only Supabase
• ✅ Environment variable validation

---

📞 Resources

• Supabase: https://supabase.com/docs
• Expo: https://docs.expo.dev
• React Native: https://reactnative.dev
• TypeScript: https://www.typescriptlang.org
• OpenAI Vision: https://platform.openai.com/docs/guides/vision
• Sentinel Hub: https://docs.sentinel-hub.com

---

🎓 For New Team Members

1. Read (in order):

   • This README
   • QUICKSTART.md
   • CLAUDE.md

2. Setup:

   npm install
   cp .env.example .env.local  # Add credentials
   npm run seed:test-data
   npm run dev

3. Explore:

   • Click through UI
   • Open DevTools (F12)
   • Read the code (stores → services → components)

4. Understand (in order):

   • How Zustand stores work
   • How services call Supabase
   • How components read stores
   • The architecture flow

5. Build:

   • Start with small changes
   • Use conventional commits
   • Update docs after work
   • Test before pushing

---

📈 Phase Progress

Phase 1: Foundation ✅ COMPLETE
Phase 2: MVP 🔄 75% COMPLETE (Current Sprint)
├─ Auth ✅
├─ Recommendations ✅
├─ Camera + AI ✅
├─ Test Data ✅
├─ Satellites ⏳
├─ Weather ⏳
└─ Dashboard ⏳

Phase 3: Backend Logic 🔜
Phase 4: Testing & Deploy 🔜
Phase 5: Other Modules 🔜

---

🤝 Contributing

1. Create a feature branch: git checkout -b feat/your-feature
2. Make changes following CLAUDE.md guidelines
3. Run checks: npm run typecheck && npm run lint
4. Commit: git commit -m "feat: Your feature"
5. Update docs before pushing
6. Push: git push

---

📄 License

MIT License - see LICENSE for details

---

👥 Team

• Founder/Lead Developer: Ghostofshadoow (@ghostofshadoow)

---

Building Africa's future, one field at a time. 🌾

Last Updated: 2026-05-28 | Phase: 2 MVP - 75% Complete