AquaX API Architecture

Owner: Backend & Architecture
Reviewers: Web, Mobile, QA, Security, DevOps
Status: Draft - Current-Code Baseline
Version: 0.1
Last Updated: 2026-09-17
Review Cycle: Per API runtime, module boundary, auth, integration or deployment change

1. Purpose And Scope

This document describes the current AquaX API architecture as implemented in the repository. It focuses on runtime structure, module boundaries, request flow, authentication, authorization, validation, response conventions, data access, client integration, IoT integration and operational risks.

This document is different from docs/08_API Specification.md:

• 08_API Specification.md lists API contracts and endpoint inventory.
• API_Architecture.md explains how the API is designed, bootstrapped, secured, layered and integrated.

Sources reviewed:

• backend/main.ts
• backend/app.module.ts
• backend/common/**
• backend/modules/**
• web/src/core/config/axios.config.ts
• web/src/core/constants/api-url.ts
• mobile/src/core/config/api-client.ts
• mobile/src/core/constants/apiURL.constants.ts
• docs/08_API Specification.md
• docs/current/architecture/backend-architecture.md

2. High-Level API Context

AquaX backend is a NestJS REST API. It is the server-side source of truth for:

• authentication and session management;
• user, role, farm and pond scope;
• farm, pond and crop operations;
• water quality, sensors, thresholds and telemetry;
• devices, device commands and auto-rules;
• alerts, tickets, notifications and activity logs;
• feeding records, farming logs and reports;
• handbook and locations;
• dashboard and settings.

Current global API prefix:

/api

Runtime Swagger documentation:

/api/docs

Default local port:

3001

3. Runtime Bootstrap

backend/main.ts creates the Nest application and configures API-wide concerns.

Runtime flow:

HTTP client
  -> CORS and cookie parsing
  -> /api global prefix
  -> validation pipe
  -> throttler guard
  -> controller
  -> use case/service
  -> repository/Prisma/GCS/cache/email/MQTT
  -> response DTO wrapper

4. Application Module Composition

backend/app.module.ts wires global infrastructure and feature modules.

Global infrastructure:

Imported feature modules:

5. Common Infrastructure Layer

CommonModule is marked @Global() and exports shared providers.

Architectural rule:

• Feature modules should depend on the exported CommonModule providers instead of creating direct infrastructure clients ad hoc.
• New email providers, cache providers or storage providers should be added through CommonModule/provider tokens.

6. Layering Pattern

The codebase uses a pragmatic NestJS module architecture. Not every module has identical internal folders, but the dominant pattern is:

controller
  -> use-case/service
  -> repository
  -> PrismaService / external provider

Common module folders:

backend/modules/<module>/
  dto/
  entities/
  repositories/
  services/
  use-cases/
  <module>.controller.ts
  <module>.module.ts

Implementation note:

• Some mature modules use repositories and use cases.
• Some modules still use direct service methods.
• New work should follow the local pattern inside the module being changed instead of forcing a repo-wide refactor.

7. API Surface Map

All paths below are mounted under /api.

For endpoint-level detail, use docs/08_API Specification.md or runtime Swagger at /api/docs.

8. Authentication Architecture

8.1 Access Token Flow

Protected API routes use bearer access tokens:

Authorization: Bearer <accessToken>

JwtAuthGuard:

1. Extracts the bearer token.
2. Verifies token signature and expiry through JwtTokenService.
3. Checks account active state from token payload.
4. Validates session state through SessionService.
5. Updates session activity.
6. Attaches request.user.

Attached user shape:

id
email
roles
farmIds
pondIds
sessionId

8.2 Refresh Token Flow

Web:

• Login sets refresh token in an httpOnly cookie named refreshToken.
• /auth/refresh reads the cookie.

Mobile:

• Mobile sends x-client-type: mobile.
• Login/refresh responses can include refreshToken in JSON.
• Refresh can send token in body or x-refresh-token header.

8.3 Session Model

Access token validation is not purely stateless. JwtAuthGuard validates the session with SessionService, so server-side session revocation and idle/absolute timeout policies can affect subsequent API calls.

9. Authorization And Scope Model

Current authorization layers:

Known risk:

• Multiple services/use cases contain TEMPORARY BYPASS comments for role, farm, pond and historical-record checks.
• AdminGuard currently returns true even when the user is not ADMIN because the ForbiddenException is commented out.
• This must be treated as production-readiness risk, not as final permission behavior.

Architecture rule:

• Any new protected business endpoint should explicitly document its auth guard, role requirement and farm/pond scope behavior.
• Temporary bypasses must be tracked before production hardening.

10. IoT API Architecture

IoT-facing APIs are under:

/api/iot/v1

Current route groups:

• telemetry ingest;
• command acknowledgement;
• device registration list/detail/map/assign;
• device registration enable/disable;
• device registration controls;
• output mode update.

Security:

• Telemetry and command ACK use IotIngestTokenGuard.
• Guard expects IOT_INGEST_TOKEN.
• Token is compared using timingSafeEqual.

Integration role:

MQTT device / iot-worker
  -> /api/iot/v1/telemetry
  -> backend validation and persistence
  -> sensors/readings/devices/alerts domain data

Production gap:

• IoT production topology is still documented as TBD in deployment docs.
• Device provisioning and production token rotation policy should be finalized.

11. Request And Response Conventions

11.1 Validation

Global validation behavior:

• strips unknown fields through whitelist;
• rejects non-whitelisted fields through forbidNonWhitelisted;
• transforms payloads based on DTO metadata;
• keeps implicit conversion disabled.

DTO rule:

• Request DTOs should define validation decorators for all accepted fields.
• Query DTOs should define type transformation explicitly where numeric/boolean values are expected.

11.2 Standard Response Shapes

Item response:

{
  "data": {},
  "message": "Thanh cong"
}

Paginated response:

{
  "data": [],
  "meta": {
    "page": 1,
    "take": 10,
    "itemCount": 0,
    "pageCount": 0,
    "hasPreviousPage": false,
    "hasNextPage": false
  },
  "message": "Thanh cong"
}

Common pagination fields:

11.3 Error Handling

Global Prisma exception mapping:

Validation and auth errors follow NestJS defaults unless overridden by controller/use-case code.

12. Data Access Architecture

Primary database access:

PrismaService -> Prisma Client -> PostgreSQL/TimescaleDB

Domain data clusters:

Database migration rule:

• Production should use prisma migrate deploy.
• prisma db push is not a production migration strategy.
• Seed should not run in production unless explicitly approved and idempotent.

13. Client Integration Architecture

13.1 Web Client

Web API integration:

• Axios config under web/src/core/config/axios.config.ts.
• Endpoint constants under web/src/core/constants/api-url.ts.
• Feature service wrappers under web/src/core/services/*.

Architecture rule:

• Web pages/components should call service wrappers and hooks, not hardcode raw endpoints in UI components.
• Endpoint constants intentionally omit /api; the base URL should include the API prefix when configured.

13.2 Mobile Client

Mobile API integration:

• API client under mobile/src/core/config/api-client.ts.
• Endpoint constants under mobile/src/core/constants/apiURL.constants.ts.
• Feature service wrappers under mobile/src/core/services/api/*.

Mobile-specific auth behavior:

• Mobile stores tokens client-side.
• Mobile refresh flow can send x-client-type: mobile and x-refresh-token.

14. External Integrations

15. Observability And Operations

Current confirmed behavior:

• Successful API requests are logged by method, URL, status and duration.
• Swagger asset requests are excluded from the success log.
• Health endpoint exists at /api/health.
• Status endpoint exists at /api/status.json.
• Prisma known request errors are normalized by a global filter.

Current gaps:

• No production metrics provider is confirmed.
• No distributed tracing is confirmed.
• No centralized log provider is confirmed.
• No API SLO/SLI definitions are confirmed.

Recommended API signals:

16. Versioning And Compatibility

Current versioning:

• Main app APIs are not URL-versioned beyond the global /api prefix.
• IoT API uses route-level version namespace /iot/v1.
• Swagger document version is 1.0.0.

Compatibility rules:

• Breaking response-shape changes must update 08_API Specification.md, client services, QA test cases and release notes.
• New public routes should include Swagger decorators and DTO validation.
• If route-level versioning expands beyond IoT, define a consistent API versioning policy before adding /v2 routes.

17. Security And Production Readiness Risks

18. Change Rules

When changing API architecture or contracts:

1. Update controller DTOs and Swagger decorators.
2. Update docs/08_API Specification.md for endpoint contract changes.
3. Update this file for runtime/layer/security/integration architecture changes.
4. Update web/mobile endpoint constants and service wrappers.
5. Add or update tests for auth, scope and response behavior.
6. Record release notes for breaking changes.

19. Traceability