# 🌾 Digital Farm Platform - Portfolio Uitleg

## 📌 Overzicht

**Digital Farm Platform** is een moderne, full-stack agro-management applicatie waarmee boeren en landbouwbedrijven hun velden, gewassen, teeltactiviteiten en weersomstandigheden digitaal kunnen beheren. Het is een **monorepo** (één repository met meerdere componenten) die bestaat uit een **FastAPI backend**, een **React + TypeScript frontend** en een **PostgreSQL database**.

---

## 🏗️ Architectuur & Technische Stack

```
┌─────────────────────────────────────────────────────┐
│                   FRONTEND                           │
│           React + TypeScript + Vite                  │
│           Tailwind CSS styling                       │
│           Leaflet (kaarten)                          │
│           React Router (navigatie)                   │
├─────────────────────────────────────────────────────┤
│                        │ API calls (httpOnly cookies)│
├─────────────────────────────────────────────────────┤
│                   BACKEND                            │
│           FastAPI (Python 3.11)                      │
│           SQLAlchemy 2.0 (ORM)                       │
│           JWT authenticatie                          │
│           TOTP 2FA (pyotp)                           │
│           OpenWeatherMap integratie                  │
├─────────────────────────────────────────────────────┤
│                   DATABASE                           │
│           PostgreSQL 15                              │
│           SQLAlchemy models                          │
├─────────────────────────────────────────────────────┤
│                   INFRA & DEVOPS                     │
│           Docker + Docker Compose                    │
│           Nginx (productie)                          │
│           Makefile (shortcuts)                       │
│           Admin Panel (token management)             │
└─────────────────────────────────────────────────────┘
```

### 🔧 Tech Stack in detail

| Component | Technologie | Waarom? |
|-----------|-------------|---------|
| **Backend** | FastAPI + Python 3.11 | Async performant, automatische API docs (Swagger), type hints |
| **Frontend** | React + TypeScript + Vite | Moderne tooling, snelle dev server, type safety |
| **Database** | PostgreSQL 15 | Relationele data, GIS ondersteuning, robuust |
| **ORM** | SQLAlchemy 2.0 | Krachtige Python ORM, type-safe queries |
| **Auth** | JWT (python-jose) + httpOnly cookies | Veilige sessies, CSRF/XSS bescherming |
| **2FA** | TOTP (pyotp + qrcode) | RFC 6238 compliant, Google Authenticator compatible |
| **Weer** | OpenWeatherMap API | Live weerdata en 5-daagse forecast |
| **Kaarten** | Leaflet + OpenStreetMap | Open-source kaartweergave van velden |
| **Containerisatie** | Docker + Docker Compose | Eenvoudig lokaal en productie deployen |
| **Admin** | Aparte FastAPI service | Token revocatie & user management |

---

## 🗄️ Databasemodel

Het systeem gebruikt **5 hoofdtabellen** met relaties:

```
┌──────────┐     ┌──────────────────┐     ┌───────────┐
│   User   │────→│      Field       │←────│   Crop    │
├──────────┤     ├──────────────────┤     ├───────────┤
│ id (PK)  │     │ id (PK)          │     │ id (PK)   │
│ email    │     │ user_id (FK)     │     │ name      │
│ password │     │ name             │     │ type      │
│ full_name│     │ size (ha)        │     │ season    │
│ phone    │     │ soil_type        │     │ duration  │
│ 2FA cols │     │ lat / lng        │     │ water_req │
└──────────┘     │ planting_date    │     │ yield     │
                 │ growth_days      │     └───────────┘
                 └──────────────────┘           ↑
                        │                       │
                        ↓          ┌──────────────────────┐
                 ┌──────────────┐  │ field_crop_assoc (N:N)│
                 │ ActivityLog  │  │ field_id + crop_id    │
                 │──────────────│  │ planting_date, area   │
                 │ id (PK)      │  └──────────────────────┘
                 │ field_id(FK) │
                 │ crop_id (FK) │
                 │ activity_type│
                 │ date / area   │
                 └──────────────┘

┌──────────────────┐
│  RevokedToken    │ (voor JWT revocatie)
│──────────────────│
│ id (PK)          │
│ jti (uniek)      │
│ revoked_at       │
└──────────────────┘
```

### 📋 Entiteiten & Relaties

1. **User** - Gebruikersaccounts met authenticatie en 2FA-ondersteuning
2. **Field** - Landbouwvelden gekoppeld aan een gebruiker (één-op-veel)
3. **Crop** - Gewasdatabank met teeltinformatie (veel-op-veel met Field)
4. **field_crop_association** - Koppeltabel met extra info (plantdatum, areaal)
5. **ActivityLog** - Bijgehouden activiteiten per veld/gewas
6. **RevokedToken** - Zwarte lijst voor ingetrokken JWT's

---

## 🔐 Authenticatie & Beveiliging

### JWT Authenticatie Flow
```
1. Gebruiker logt in → backend genereert JWT met unieke jti
2. JWT wordt opgeslagen in httpOnly cookie (niet toegankelijk via JS)
3. Elke API call stuurt cookie mee naar backend
4. Backend valideert JWT + checkt of jti niet is ingetrokken
5. Uitloggen → jti wordt toegevoegd aan revoked_tokens tabel
```

### 2FA (Twee-Factor Authenticatie) Flow
```
1. Gebruiker activeert 2FA in Instellingen
2. Backend genereert TOTP secret + QR code
3. Gebruiker scant QR met Google/Microsoft Authenticator
4. Gebruiker bevestigt met 6-cijferige code → 2FA ingeschakeld
5. Bij inloggen: eerst wachtwoord check → daarna 2FA code verplicht
6. Tijdelijke challenge token (5 min) voor 2FA verificatie
```

### Beveiligingsfeatures
- ✅ httpOnly cookies (XSS bescherming)
- ✅ JWT revocatie (bij uitloggen)
- ✅ TOTP 2FA (RFC 6238)
- ✅ CORS bescherming
- ✅ Wachtwoord hashing (PBKDF2-SHA256)
- ✅ Wachtwoord validatie (hoofdletter, cijfer, speciaal teken, 8+ karakters)
- ✅ SameSite cookie attributen (CSRF bescherming)

---

## 🌐 API Endpoints Overzicht

### Auth & Gebruikers
| Endpoint | Methode | Beschrijving |
|----------|---------|--------------|
| `/auth/register` | POST | Registreer nieuwe gebruiker |
| `/auth/login` | POST | Login (returns `requires_totp` als 2FA aan) |
| `/auth/verify-totp` | POST | Verifieer TOTP code na login |
| `/auth/logout` | POST | Log uit + revoke JWT |
| `/user/profile` | GET | Profiel ophalen |
| `/user/profile` | PUT | Profiel bijwerken |
| `/user/password` | PUT | Wachtwoord wijzigen |

### 2FA
| Endpoint | Methode | Beschrijving |
|----------|---------|--------------|
| `/totp/setup` | POST | Genereer QR code voor 2FA setup |
| `/totp/verify-with-secret` | POST | Verifieer + activeer 2FA |
| `/totp/disable` | POST | Deactiveer 2FA (met wachtwoord + code) |
| `/totp/status` | GET | Check 2FA status |

### Velden (Fields)
| Endpoint | Methode | Beschrijving |
|----------|---------|--------------|
| `/fields/` | GET | Alle velden van gebruiker |
| `/fields/{id}` | GET | Specifiek veld |
| `/fields/` | POST | Nieuw veld aanmaken |
| `/fields/{id}` | PUT | Veld bijwerken |
| `/fields/{id}` | DELETE | Veld verwijderen |
| `/fields/{id}/crops` | GET | Gewassen in veld |
| `/fields/{id}/crops` | POST | Gewas toevoegen aan veld |
| `/fields/{id}/crops/{crop_id}` | DELETE | Gewas verwijderen uit veld |
| `/fields/{id}/activities` | GET | Activiteiten van veld |
| `/fields/{id}/activities` | POST | Activiteit toevoegen |
| `/fields/{id}/city` | GET | Stad uit adres halen |

### Gewassen (Crops)
| Endpoint | Methode | Beschrijving |
|----------|---------|--------------|
| `/crops/` | GET | Alle gewassen (met filters) |
| `/crops/` | POST | Nieuw gewas aanmaken |
| `/crops/{id}` | PUT | Gewas bijwerken |
| `/crops/{id}` | DELETE | Gewas verwijderen |

### Weer & Health
| Endpoint | Methode | Beschrijving |
|----------|---------|--------------|
| `/weather?city=...` | GET | Huidig weer via OpenWeatherMap |
| `/weather/forecast?city=...` | GET | 5-daagse weersverwachting |
| `/health` | GET | API + database health check |

---

## 🎨 Frontend Componenten

### Pagina's & Features

| Pagina | Bestand | Functionaliteit |
|--------|---------|-----------------|
| **Dashboard** | `Dashboard.tsx` | Statistieken, weer, veldoverzicht, alerts, recente activiteiten |
| **Weer** | `Weather.tsx` | Live weer, 5-daagse forecast, weerwaarschuwingen, tips per locatie |
| **Slimme Planner** | `SmartPlanner.tsx` | Automatisch veldadvies op basis van weer en gewastype |
| **Gewassen** | `Crops.tsx` | Gewasdatabank met details, groei-eisen, teeltkalender |
| **Velden** | `Fields.tsx` | Lijst/kaartweergave, CRUD, gewas-toewijzing, activiteitenlog |
| **Instellingen** | `Settings.tsx` | Profiel bewerken, wachtwoord wijzigen, 2FA beheer |
| **2FA Modals** | `TwoFactorModal.tsx` | Login 2FA verificatie |
| **2FA Setup** | `TwoFactorSetup.tsx` | QR code scannen + 2FA activeren |

### API Laag
```
frontend/src/api/
├── client.ts      → HTTP client (get, post, put, delete) met cookies
├── auth.ts        → Login/register API calls
├── crops.ts       → Gewas CRUD API
├── fields.ts      → Veld CRUD + gewassen/activiteiten API (met TypeScript types)
├── totp.ts        → 2FA TOTP API
└── user.ts        → Profiel/wachtwoord API
```

### Routing
```
/ → dashboard (beschermd)
/login → authenticatiepagina
/dashboard → overzicht
/weather → weerberichten
/smart-planner → slim advies
/crops → gewassendatabank
/fields → veldenbeheer
/settings → instellingen
```

---

## 🧠 Slimme Planner - Hoe Werkt Het?

De **Smart Planner** combineert **weerdata** met **gewaskennis** om slim advies te geven:

```
1. Laad alle velden van de gebruiker
2. Voor elk veld:
   a. Bepaal locatie (via adres in field.address)
   b. Haal actueel weer op via OpenWeatherMap
   c. Analyseer weercondities:
      - Vorst? → "Geen veldwerk"
      - Harde wind? → "Niet sproeien"
      - Regen? → "Geen irrigatie nodig"
   d. Voor elk gewas in veld:
      - Specifieke gewasadviezen (temp, luchtvochtigheid)
      - Bijv: Aardappelen → Phytophthora risico bij hoge luchtvochtigheid
3. Toon gepersonaliseerd advies per veld
```

### Gewas-specifieke regels (voorbeelden)
- **Aardappelen**: Phytophthora risico bij >80% luchtvochtigheid
- **Tarwe**: Bladziekten bij >85%, goede groei bij 12-27°C
- **Maïs**: Groeistilstand onder 10°C, hittestress boven 32°C
- **Suikerbieten**: Actieve groei bij 15-28°C, bladschimmel bij hoge luchtvochtigheid

---

## 📦 Docker & Deployment

### Development Stack (`docker-compose.dev.yml`)
```
Services:
├── db (PostgreSQL 15)  → poort 5432
├── api (FastAPI)       → poort 8000 (hot-reload)
└── web (Vite)          → poort 5173 (hot-reload)
```

### Production Stack (`docker-compose.prod.yml`)
```
Services:
├── db (PostgreSQL 15)  → poort 5432
├── api (FastAPI)       → poort 8000
└── web (Nginx)         → poort 3000
```

### Makefile Commando's
```bash
make dev      # Start development stack
make build    # Bouw development stack
make backend  # Start alleen backend
make frontend # Start alleen frontend
make stop     # Stop services
make down     # Stop + verwijder volumes
make clean    # Volledige opschoning
make restart  # Herstarten
```

### Entrypoint Script
Het `entrypoint.sh` script doet bij opstarten:
1. Wacht tot PostgreSQL bereikbaar is
2. Creëert database + role indien nodig
3. Maakt alle SQLAlchemy tabellen aan
4. Creëert testgebruiker (`user@example.com` / `Passw0rd`)
5. Seedd de database met standaard gewassen

---

## 🔧 Admin Panel

Een **aparte, minimale admin service** die:
- Rechtstreeks op dezelfde database verbindt
- Beveiligd is met een `ADMIN_TOKEN` header
- JWT tokens kan revoken (intrekken)
- Gebruikers kan beheren
- Apart draait via `docker-compose.admin.yml`

---

## ⚡ 2FA Implementatie (TOTP)

De **Twee-Factor Authenticatie** is volledig geïmplementeerd:

### Backend (267 regels code)
- TOTP setup endpoint → genereert secret + QR code (base64)
- Verify-with-secret endpoint → slaat secret op + activeert 2FA
- Disable endpoint → deactiveert met wachtwoord + code
- Login flow → `requires_totp` flag in login response
- Tijdelijke challenge token (5 min) via httpOnly cookie

### Frontend (695 regels code)
- **Settings.tsx**: 2FA in-/uitschakelen met wachtwoordbevestiging
- **TwoFactorSetup.tsx**: QR code scannen + handmatige code invoer
- **TwoFactorModal.tsx**: Login 2FA verificatie popup
- Copy-to-clipboard functionaliteit
- Validatie, loading states, error handling

### Compatibiliteit
- ✅ Google Authenticator
- ✅ Microsoft Authenticator
- ✅ Authy
- ✅ Elke RFC 6238-compatibele app

---

## 📊 Gebruikte Design Patterns

| Pattern | Toepassing |
|---------|------------|
| **MVC-achtig** | Models (data) → Routes (controllers) → Frontend (views) |
| **Repository** | API laag in frontend scheidt data-access van UI |
| **Dependency Injection** | FastAPI's `Depends()` voor DB-sessies en auth |
| **DTO/Schema** | Pydantic modellen voor request/response validatie |
| **Observer** | `useEffect` hooks in React voor data-binding |
| **Middleware** | CORS middleware, JWT cookie authenticatie |

---

## 🚀 Hoe Start Je Het Project?

### Met Docker (aanbevolen)
```bash
# 1. Clone de repository
git clone https://github.com/AgroPlatform/digital-farm-platform.git
cd digital-farm-platform

# 2. Start development omgeving
make dev

# 3. Open in browser
# Frontend: http://localhost:5173
# Backend API: http://localhost:8000
# API Docs: http://localhost:8000/docs

# 4. Of productie modus
docker-compose -f docker-compose.prod.yml up --build
# Frontend: http://localhost:3000
```

### Zonder Docker
```bash
# Backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend
cd frontend
npm install
npm run dev
```

### Testgebruiker
- **Email**: `user@example.com`
- **Wachtwoord**: `Passw0rd`

---

## 🎯 Conclusie

**Digital Farm Platform** is een **productie-ready** agro-management systeem dat laat zien:

✅ **Moderne full-stack architectuur** (FastAPI + React + PostgreSQL)
✅ **Veilige authenticatie** (JWT + httpOnly cookies + 2FA/TOTP)
✅ **Docker-gebaseerde deployment** (dev + prod stacks)
✅ **Externe API integratie** (OpenWeatherMap, OpenStreetMap)
✅ **Slimme data-gedreven features** (Smart Planner met weer-gewaskennis)
✅ **GIS-functionaliteit** (Leaflet kaarten met veldlocaties)
✅ **Type safety** (TypeScript frontend + Python type hints backend)
✅ **Uitgebreide documentatie** (README, 2FA docs, admin panel)

> Dit project demonstreert vaardigheden in: **full-stack web development, database design, API design, authenticatie/security patterns, Docker containerisatie, externe API integratie, en moderne frontend development met React.**

---
*Gemaakt voor het AgroPlatform digital farming initiatief*