Climate-smart Approach for Reducing Antimicrobial resistance
IoT-enabled mobile platform for Vietnamese shrimp farmers
Features • Quick Start • Architecture • Development • Roadmap
CARA is a research-grade mobile application designed for monitoring and reducing antimicrobial use in Vietnamese aquaculture systems. Built for Oxford University Clinical Research Unit (OUCRU) under ICARS Global funding.
| Goal | Metric | Target |
|---|---|---|
| 🔬 Reduce antimicrobial use | mg/kg biomass | -30% |
| 🌍 Mitigate greenhouse gas | CH₄, N₂O emissions | -20% |
| 🦠 Decrease AMR genes | qPCR abundance | -40% |
| 🐟 Maintain production | FCR, survival rate | Stable |
| 💰 Economic viability | ROI | Positive |
Home Dashboard IoT monitoring priority |
Real-time Monitoring DO, pH, Temperature |
Health Recording Photo + Voice capture |
Research Dashboard Comprehensive data view |
AMU Recording Automatic mg/kg calculation |
Data Collection Triangulation validation |
Key UI Features:
- ✅ Glassmorphism design with semi-transparent cards
- ✅ Network status indicator (green/red cloud icon)
- ✅ Offline sync badge (shows pending records count)
- ✅ Role-based interfaces (Farmer simple, Researcher comprehensive)
- ✅ Vietnamese/English bilingual support
- ✅ Real-time IoT data visualization
|
🌡️ Real-time IoT Monitoring
|
📱 Simple Data Recording
|
|
🔔 Smart Alerts
|
📊 Production Tracking
|
|
📈 Data Collection
|
✅ Quality Control
|
|
🎤 Participatory Evaluation
|
📊 Data Export
|
Backend
FastAPI (Python 3.11) → PostgreSQL 15 + TimescaleDB
→ MinIO (S3-compatible storage)
→ EMQX MQTT (IoT broker)
→ Redis (cache + Celery)
Mobile App
Flutter 3.x → Provider (state management)
→ Hive (offline storage)
→ Dio (HTTP client)
→ Firebase Cloud Messaging
Infrastructure
Docker Compose → 9 containers
→ Nginx reverse proxy
→ Let's Encrypt SSL
→ Prometheus + Grafana
CARA_APP/
├── backend/ # FastAPI backend services
│ ├── app/
│ │ ├── api/v1/ # REST API endpoints
│ │ ├── models/ # SQLAlchemy ORM models
│ │ ├── services/ # Business logic layer
│ │ └── core/ # Config, security, database
│ ├── Dockerfile
│ └── requirements.txt
│
├── mobile_app/ # Flutter mobile application
│ ├── lib/
│ │ ├── main.dart # Application entry point
│ │ ├── core/ # Core services & utilities
│ │ ├── features/ # Feature modules (home, auth, etc.)
│ │ └── shared/ # Reusable widgets & themes
│ ├── ios/ # iOS platform configuration
│ ├── android/ # Android platform configuration
│ └── pubspec.yaml # Flutter dependencies
│
├── infra/
│ ├── docker/ # Docker Compose setup
│ │ ├── docker-compose.yml
│ │ └── init-db.sql
│ └── nginx/ # Nginx reverse proxy config
│
├── scripts/ # Development automation
│ ├── quickstart.sh # One-command startup
│ ├── run.sh # Mobile app launcher
│ └── verify_sprint1.sh
│
└── docs/
└── images/ # UI screenshots for README
Core Tables (10 tables)
farmers -- Farmer profiles (name, phone, consent)
ponds -- Pond metadata (species, volume, density)
amu_records -- AMU tracking (auto mg/kg calculation)
biomass_estimates -- Fish sampling data
production_parameters -- FCR, survival, yield
costs -- Economic tracking
alerts -- AI risk alerts
lab_results -- qPCR AMR gene data
interviews -- Participatory evaluation
audit_logs -- Complete audit trailKey Features:
- ✅ Automatic mg/kg calculation (PostgreSQL computed column)
- ✅ Multi-language enums (Vietnamese/English)
- ✅ Complete audit trail for compliance
- ✅ TimescaleDB for IoT time-series data
📋 Development Environment (Click to expand)
Already installed and verified:
- ✅ Docker 27.4.0 & Docker Compose 2.30.3
- ✅ Flutter 3.35.5 / Dart 3.9.0
- ✅ Xcode 16.4 + CocoaPods 1.16.2
- ✅ Android Studio Ladybug 2024.2.1
- ✅ Ruby 3.4.0 + ffi 1.17.0
- ✅ Homebrew 4.4.14
# Clone repository
git clone https://github.com/ChaokunHong/CARA.git
cd CARA
# Start all backend services (9 Docker containers)
./scripts/quickstart.sh
# Run mobile app
./run.sh # Auto-detects available devicesThat's it! The script will:
- ✅ Start PostgreSQL, TimescaleDB, MinIO, EMQX, Redis
- ✅ Initialize database schema with sample data
- ✅ Verify all services are healthy
- ✅ Launch Flutter app on selected device
| Service | URL | Credentials |
|---|---|---|
| API Documentation | http://localhost:8000/docs | - |
| MinIO Console | http://localhost:9001 | minioadmin / minioadmin123 |
| EMQX Dashboard | http://localhost:18083 | admin / cara_admin123 |
| PostgreSQL | localhost:5432 | cara_user / cara_password |
| Backend API | http://localhost:8000 | - |
# Copy example environment file
cp backend/.env.example backend/.env
# Edit configuration (optional)
nano backend/.envKey variables:
# Database
POSTGRES_URI=postgresql://cara_user:cara_password@localhost:5432/cara_db
# MinIO (S3-compatible storage)
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin123
# JWT Authentication
JWT_SECRET=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
# EMQX MQTT Broker
EMQX_URL=mqtt://localhost:1883cd backend
# Install dependencies
pip install -r requirements.txt
# Run database migrations
alembic upgrade head
# Start development server
uvicorn app.main:app --reload --port 8000
# Run tests
pytest tests/ -v --cov=app
# Check API health
curl http://localhost:8000/healthcd mobile_app
# Install dependencies
flutter pub get
# Generate Hive type adapters
flutter pub run build_runner build --delete-conflicting-outputs
# Run on iOS simulator
flutter run -d "iPhone 15 Pro"
# Run on Android emulator
flutter run -d "Pixel 8"
# Code analysis
flutter analyze
# Run tests
flutter test{
"farmer": {
"phone": "+84901234567",
"name": "Nguyen Van A",
"role": "farmer"
},
"researcher": {
"phone": "+84903456789",
"name": "Tran Thi B",
"role": "researcher"
}
}View Sprint 1 details
Infrastructure Setup
- Monorepo project structure
- Docker Compose environment (9 containers)
- PostgreSQL + TimescaleDB database
- MinIO object storage
- EMQX MQTT broker
- FastAPI backend with JWT auth
- Complete database schema (10 tables)
- iOS & Android platform setup
View Sprint 2 details
User Interface & Offline Foundation
- Dual role system (Farmer/Researcher)
- Glassmorphism UI design
- Photo capture + preview
- Offline queue system (Hive + connectivity_plus)
- Auto-sync when network recovers
- Network status indicator with sync badge
- AudioService & FileUploadService preparation
IoT Real-time Monitoring
- EMQX MQTT integration
- DO, pH, temperature, conductivity display
- TimescaleDB time-series storage
- Pond dashboard with live data
- AI risk scoring (0-100 scale)
- Smart alert triggers (<2min push)
| Sprint | Focus | Key Deliverables |
|---|---|---|
| 4 | Alert System | Push notifications, alert history, acknowledgment |
| 5 | AMU & Biomass | Full AMU workflow, biomass sampling, mg/kg auto-calc |
| 6 | Participatory Evaluation | Interview recording, acceptability scoring |
| 7 | Data Export | CSV export, lab results, sample tracking |
| 8 | Security & QA | Triangulation validation, audit logging |
| 9 | Performance | Load testing, production deployment, monitoring |
| 10 | Pilot Launch | 6 farmers onboarding, training materials |
# Unit tests with coverage
pytest tests/ -v --cov=app --cov-report=html
# Integration tests
pytest tests/integration/ -v
# Load testing (Apache Bench)
ab -n 1000 -c 10 http://localhost:8000/health# Unit tests
flutter test
# Widget tests
flutter test test/widget_test.dart
# Integration tests
flutter test integration_test/
# Code coverage
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html# Full workflow test
./scripts/test_e2e.sh
# Performance benchmarks
flutter drive --target=test_driver/perf_test.dart| Metric | Target | Current |
|---|---|---|
| API Response Time (P95) | <500ms | ~100ms ✅ |
| Mobile App Launch | <3s | ~2s ✅ |
| Offline Queue Capacity | 100+ records | 200+ ✅ |
| IoT Data Latency | <2min | TBD 🚧 |
| Photo Upload Time | <5s | TBD 🚧 |
| Test Coverage | >80% | ~70% 🟡 |
- Authentication: JWT with refresh tokens
- Password Hashing: Bcrypt (cost factor 12)
- Transport Security: TLS 1.2+ enforced
- Rate Limiting: 100 requests/minute per IP
- Audit Logging: Complete CRUD trail
- Row-Level Security: Farmer data isolation
- Secret Management: Environment variables only
- CORS: Whitelist origins only
| Resource | Description |
|---|---|
| API Documentation | Interactive Swagger UI (FastAPI) |
| API ReDoc | Alternative API documentation |
| MinIO Console | Object storage management |
| EMQX Dashboard | MQTT broker monitoring |
This is a research project under active development. For development guidelines:
- Follow existing code patterns and project structure
- Write tests for new features (>80% coverage)
- Use English for all code, comments, and commit messages
- Ensure all tests pass before submitting changes
- Update README.md if adding new features
This is a research project under Oxford University Clinical Research Unit (OUCRU). Not for commercial use without permission.
Research Team
- Lead Researcher: Sonia Lewycka (slewycka@oucru.org)
- Project: CARA - Climate-smart AMR Reduction in Aquaculture
- Funding: ICARS Global
Technical Team
- Technical Lead: Chaokun Hong
- Backend: FastAPI + PostgreSQL + TimescaleDB
- Mobile: Flutter + Dart
- Infrastructure: Docker + Nginx + Let's Encrypt
- Oxford University Clinical Research Unit (OUCRU)
- ICARS Global Funding Program
- Vietnamese Aquaculture Farmers (Pilot Participants)
- Open Source Community (Flutter, FastAPI, PostgreSQL)
Built with ❤️ for sustainable aquaculture