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.

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

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 trail

Key Features:

• ✅ Automatic mg/kg calculation (PostgreSQL computed column)
• ✅ Multi-language enums (Vietnamese/English)
• ✅ Complete audit trail for compliance
• ✅ TimescaleDB for IoT time-series data

# 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 devices

That's it! The script will:

1. ✅ Start PostgreSQL, TimescaleDB, MinIO, EMQX, Redis
2. ✅ Initialize database schema with sample data
3. ✅ Verify all services are healthy
4. ✅ Launch Flutter app on selected device

# Copy example environment file
cp backend/.env.example backend/.env

# Edit configuration (optional)
nano backend/.env

Key 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:1883

cd 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/health

cd 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"
  }
}

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)

# 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

• 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

This is a research project under active development. For development guidelines:

1. Follow existing code patterns and project structure
2. Write tests for new features (>80% coverage)
3. Use English for all code, comments, and commit messages
4. Ensure all tests pass before submitting changes
5. 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)