Project Overview and Product Development Requirements

1. Project Overview

Project Name: HMP IoT Platform
Type: Multi-tenant aquaculture (fish/shrimp farming) monitoring and management system
Target Market: Vietnamese market

1.1 Business Context

HMP IoT Platform integrates IoT devices with business operations to help farm owners:

Track water quality parameters (pH, DO, temperature, salinity)
Monitor growth data and farming cycles
Manage farm infrastructure (areas, ponds)
Receive real-time alerts on anomalies
Generate reports and analytics

1.2 Technical Context

Aspect	Implementation
Architecture	Monorepo (Bun workspaces)
Backend	NestJS, TypeScript, PostgreSQL + TimescaleDB, TypeORM, Redis, MQTT (EMQX), MinIO
Frontend	React 19, Vite, Ant Design, TanStack Query, Zustand
Multi-tenancy	All business entities scoped to `organizationId`
Authentication	JWT (15min) + httpOnly refresh token (7 days)
API Versioning	`/api/v1` prefix

2. Product Requirements

2.1 Core Features (MVP)

Feature	Priority	Description
Authentication	P0	JWT login, refresh tokens, password reset
Multi-tenant Organizations	P0	Organization CRUD, user assignments
RBAC	P0	Role-based access with `resource:action:scope` permissions
Farm Management	P0	Areas and Ponds CRUD
Species Management	P1	Species catalog for farming
Farming Cycles	P1	Cycle creation, tracking, completion
IoT Device Management	P0	Device registration, telemetry, alerts
MQTT Integration	P0	MQTT broker connection for device communication
Telemetry Ingestion	P1	Time-series data storage and querying
Alert System	P1	Alert configurations, notifications
Daily Logs	P1	Daily farming activity logs
Growth Records	P1	Growth tracking data
Reports & Analytics	P2	FCR, biomass, survival rate reports
Inventory Management	P2	Items, warehouses, transactions
Supplier Management	P2	Supplier CRUD and tracking
Financial Module	P1	Expense/revenue tracking, cost categories, P&L reports

2.2 User Roles

Role	Permissions
Super Admin	Full system access, organization management
Admin	Organization-level full access
Owner	Farm-level management, can view all ponds
Staff	Assigned pond operations, daily logging
Technical	Device configuration, troubleshooting

2.3 Non-Functional Requirements

Requirement	Target
API Response Time	< 200ms (p95)
Telemetry Ingestion	1000 msg/sec
Concurrent Users	500 per organization
Uptime	99.9%
Security	OWASP Top 10 compliant

3. System Context

3.1 External Integrations

MQTT Broker (EMQX): Device telemetry ingestion
MinIO: File storage (device images, reports)
Redis: Caching, session management

3.2 Data Flow

IoT Devices → MQTT → NestJS → PostgreSQL/TimescaleDB
                                    ↓
                              REST API → React Frontend
                                    ↓
                              WebSocket → Real-time updates

4. Development Phases

Phase	Focus	Status
Phase 1	Infrastructure, Auth, RBAC	Complete
Phase 2	Farm, Devices, MQTT	Complete
Phase 3	Aquaculture (Cycles, Logs, Growth)	Complete
Phase 4	Telemetry, Alerts	Complete
Phase 5	Reports & Analytics	Complete
Phase 6	Frontend UI Polish	Complete
Phase 7	Inventory & Suppliers	Complete
Phase 8	Financial Module	In Progress
Phase 9	Documentation & Monitoring	Pending

5. Success Criteria

All backend APIs implemented and tested
Frontend pages functional with demo data
IoT device integration working
Multi-tenant isolation verified
Demo environment deployable
Documentation complete