Codebase Summary

1. Overview

This document provides a high-level summary of the HMP IoT Platform codebase structure and organization.

2. Repository Structure

iot_platform/
├── backend/                 # NestJS API server
├── frontend/                # React web application
├── package.json             # Root workspace config (Bun)
├── biome.json               # Shared linting config
├── docker-compose.dev.yml   # Development services with hot-reload
├── docker-compose.prod.yml  # Production services
└── CLAUDE.md               # AI assistant guidelines

3. Backend Structure (`backend/src/`)

3.1 Modules

Module	Path	Description
Auth	`auth/`	JWT authentication, refresh tokens, password reset
RBAC	`rbac/`	Role-based access control, permissions
Users	`users/`	User CRUD, profile management
User Roles	`user-roles/`	User-role mappings
Roles	`roles/`	Role management
Organizations	`organizations/`	Multi-tenant organization management
Farm	`farm/`	Areas and Ponds management
Aquaculture	`aquaculture/`	Species, Farming Cycles, Growth Records, Daily Logs
Devices	`devices/`	IoT device management, telemetry, alerts
MQTT	`mqtt/`	MQTT broker integration
Telemetry	`telemetry/`	Telemetry data ingestion and querying
Notifications	`notifications/`	User notification preferences
Inventory	`inventory/`	Inventory items, batches, transactions, warehouses
Suppliers	`suppliers/`	Supplier management
Reports	`reports/`	Dashboard and analytics reports
WebSocket	`websocket/`	Real-time communication
Scheduled Tasks	`scheduled-tasks/`	Background jobs
Health	`health/`	Health check endpoints
Redis	`redis/`	Redis cache service

3.2 Common Components

Component	Path	Description
Decorators	`common/decorators/`	`@CurrentUser`, `@Permissions`, `@Organization`
Guards	`common/guards/`	JWT auth, RBAC permissions
Interceptors	`common/interceptors/`	Organization filter, response transformation
Enums	`common/enums/`	Action, Resource, Scope enums

3.3 Database

Migrations: src/migrations/
Seeds: src/database/seeds/
TypeORM entities in each module

4. Frontend Structure (`frontend/src/`)

4.1 Tech Stack

Category	Technologies
UI Framework	React 19, Vite
UI Libraries	Ant Design, Tailwind CSS, Recharts
State	TanStack Query, Zustand
Validation	Zod

4.2 Pages

Module	Pages
Auth	Login
Dashboard	DashboardOverview
Farm	FarmDashboard, AreaList, AreaDetail, PondList, PondDetail
Devices	DeviceDashboard, DeviceList, DeviceDetail
Cycles	CyclesDashboard, CycleList, CycleDetail, CycleWizard, DailyLogs, GrowthTracking
Inventory	InventoryDashboard, InventoryItemList, InventoryItemDetail, TransactionPage, WarehouseList, SupplierList, CostReportPage
Reports	ReportsPage, GrowthPerformanceReport, FCRReport, BiomassReport, SurvivalRateReport, ComparisonReport, ReportLanding
Settings	SettingsPage, ProfilePage

4.2 Components

Category	Components
Common	PageHeader, StatsCard, StatusBadge, DataTable, LoadingSkeleton, EmptyState
Layouts	AuthLayout, DashboardLayout, SidebarMenu, TopNav
Farm	AreaCard, PondCard, PondForm, AreaForm
Devices	TelemetryChart, GatewayControlPanel
Notifications	NotificationBell

4.3 State & Data

TanStack Query: Server state, API calls
Zustand: Global client state
Zod: Form validation schemas

4.4 Services & Hooks

Category	Files
Services	area.service.ts, cycle.service.ts, device.service.ts, report.service.ts, inventory.service.ts, notification.service.ts, pond.service.ts
Hooks	useFarms.ts, useDeviceTelemetry.ts, useReports.ts, useInventory.ts, useWebSocket.ts
Stores	auth.store.ts, cycle.store.ts, device.store.ts, notification.store.ts

4.5 Schemas & Types

Category	Files
Schemas	auth.schema.ts, farm.schema.ts, cycle.schema.ts, device.schema.ts, inventory.schema.ts, common.schema.ts
Types	cycle.types.ts, device.types.ts, farm.types.ts, inventory.types.ts, notification.types.ts, report.types.ts

5. RBAC Architecture

5.1 Core Components

Component	File	Description
`AuthorizationPolicyService`	`rbac/authorization-policy.service.ts`	Core service for permission checking and scope resolution
`ResourceScopeMap`	`rbac/resource-scope-map.ts`	Defines scope configs per resource
`PermissionsGuard`	`common/guards/permissions.guard.ts`	OR-based permission checking (user needs ONE of listed permissions)

5.2 Permission Format

Permissions follow format resource:action:scope (e.g., pond:read:all, device:update:own, role:*:system).

5.3 EffectiveScope Levels

Scope	Description
`none`	No access
`assigned`	Only resources assigned to user
`own`	Resources created by user
`all`	All resources in organization
`system`	Cross-organization access (superadmin)

5.4 ResourceScopeMap Configuration

Per-resource ResourceScopeConfig:

Resource	Assignment Mode	Supports System Scope
`area`	`by-pond`	No
`pond`	`direct`	No
`cycle`	`by-pond`	No
`device`	`by-pond`	No
`inventory`	`direct`	No
`warehouse`	`direct`	No
`supplier`	`direct`	No
`organization`	`none`	Yes
`role`	`none`	Yes

5.5 CurrentUserData Extended

interface CurrentUserData {
  userId: string;
  email: string;
  organizationId: string | null;
  roles: string[];
  permissions?: string[];
  assignedResources?: string[]; // NEW: resources assigned to user
}

6. Key Conventions

5.1 Naming

Type	Convention	Example
Files	kebab-case	`create-user.dto.ts`
Classes	PascalCase	`UserService`
Variables	camelCase	`userId`
Database	snake_case	`user_id`

5.2 Imports

Use @/ alias for internal imports
Avoid relative paths like ../

5.3 TypeScript Rules

No any type - use unknown or proper types
Strict mode enabled
Prefix unused params with _

5.4 API Conventions

All routes prefixed with /api/v1
Use Swagger decorators (@ApiTags, @ApiOperation)
Throw NestJS exceptions

7. Database Schema Highlights

6.1 Core Entities

organizations - Multi-tenant organizations
users - User accounts with roles
roles - Role definitions
permissions - Permission definitions
areas - Farm areas/zones
ponds - Individual ponds
species - Aquaculture species
farming_cycles - Farming cycles
devices - IoT devices
device_telemetry - Time-series sensor data
device_alerts - Alert records

6.2 Multi-Tenancy

All business entities include organization_id column. The OrganizationFilterInterceptor automatically scopes queries.

8. Build & Run

Command	Description
`bun install`	Install dependencies
`bun run backend:start:dev`	Start backend
`bun run frontend:start:dev`	Start frontend
`bun run check`	Lint + format

9. Testing

Backend: Jest (bun test)
Run specific: bun test -- path/to/test.spec.ts

10. External Services

Service	Port	Purpose
PostgreSQL + TimescaleDB	5432	Primary database + time-series
Redis	6379	Caching, sessions
EMQX	1883/18083	MQTT broker
MinIO	9000/9001	File storage (S3-compatible)
MinIO	9000/9001	File storage

Generated from codebase analysis - Last updated: March 2026