Skip to content

Specification — Pool Management and Dashboard in Poolia

1. Objective

Model pools as the primary business entity in Poolia, including ownership, technician assignment, operational configuration, and dashboard-style aggregated information for frontend consumption.

A pool is the anchor for several related domains:

  • invitations;
  • visits;
  • water measurements;
  • messaging;
  • media attachments;
  • alert configuration.

2. Functional Approach

Pool management is centered on the Pool document and several related resources.

The current implementation supports:

  • creating pools;
  • listing pools;
  • retrieving a pool by id;
  • updating pool data;
  • deleting pools;
  • listing pools by owner;
  • listing pools by technician;
  • removing a technician from a pool;
  • reading and upserting alert configuration;
  • exposing a dashboard response derived from multiple collections.

3. Data Design

3.1. Pool

The pools collection stores the main pool record.

Main fields

  • ownerId
  • name
  • location
  • volume
  • depth
  • poolType
  • technicianIds
  • createdAt
  • updatedAt

Location structure

Location is modeled as:

  • address
  • lat
  • lng

Pool type

The current schema supports:

  • SALTY
  • CHLORINE

3.2. AlertConfig

Each pool can also have an alert configuration stored in the alertConfigs collection.

Main fields

  • poolId
  • phMin
  • phMax
  • chlorineMin
  • chlorineMax
  • temperatureMin
  • temperatureMax
  • createdAt
  • updatedAt

3.3. Dashboard aggregation

The dashboard response is not stored as a document. It is assembled dynamically from:

  • the pool;
  • the owner;
  • the most recent pool values;
  • the most recent visit;
  • the technician of the most recent visit.

4. Validation and Business Rules

Owner validation

Pool creation and owner reassignment require ownerId to belong to a user whose role is owner.

Technician validation

Operations that address technicians by id validate that the referenced user exists and has role technician.

Technician removal

A technician can only be removed if that technician is currently assigned to the pool.

Default alert config

If a pool has no existing alert configuration, reading /pools/{pool_id}/alert-config creates and returns a default configuration instead of returning 404.

This means the read operation also acts as lazy initialization.

5. Pool Dashboard Logic

The dashboard is intended as a frontend-friendly summary.

Data included

  • owner email
  • technician email from the latest visit, if available
  • pool name
  • pool location
  • pool volume
  • pool depth
  • latest visit date
  • latest visit status summary (isPoolOk)
  • observations from the latest visit
  • latest measured ph
  • latest measured chlorine
  • latest measured temperature

Data selection strategy

The backend:

  1. loads the pool;
  2. loads the owner;
  3. loads all pool values for the pool and picks the latest by createdAt;
  4. loads all visits for the pool and picks the latest by date;
  5. optionally resolves the technician from the latest visit.

If there are no visits yet, the dashboard still returns pool and owner information and may include latest pool values if available.

6. REST Endpoints

6.1. Create pool

POST /pools

Request body

{
  "ownerId": "owner-id",
  "name": "Beach House Pool",
  "location": {
    "address": "Some address",
    "lat": -34.88,
    "lng": -56.07
  },
  "volume": 42000,
  "depth": 1.8,
  "poolType": "SALTY",
  "technicianIds": []
}

Behavior

  • validates owner role;
  • initializes technician list if missing;
  • sets timestamps;
  • creates the pool.

6.2. Get pool

GET /pools/{pool_id}

Returns one pool or 404.

6.3. List pools

GET /pools

Optional query

  • ownerId

If ownerId is present, pools are filtered by owner. Otherwise all pools are returned.

6.4. Update pool

PATCH /pools/{pool_id}

Behavior

  • loads the pool;
  • validates owner if owner is being changed;
  • applies partial updates;
  • updates updatedAt.

6.5. Delete pool

DELETE /pools/{pool_id}

Deletes the pool document.

6.6. Remove technician from pool

DELETE /pools/{pool_id}/technicians/{technician_id}

Behavior

  • validates the pool exists;
  • validates the technician role;
  • validates assignment;
  • removes the technician from technicianIds.

6.7. List pools by owner

GET /pools/user/{user_id}

Returns all pools whose ownerId matches the given user.

6.8. List pools by technician

GET /pools/technician/{tech_id}

Returns all pools where technicianIds contains the given technician id.

6.9. Get alert config

GET /pools/{pool_id}/alert-config

Behavior

  • validates pool existence;
  • returns the alert config if it exists;
  • otherwise creates and returns a default alert config.

6.10. Upsert alert config

PUT /pools/{pool_id}/alert-config

Behavior

  • validates pool existence;
  • creates a new alert config if none exists;
  • otherwise updates the existing one.

Validation

The payload enforces:

  • phMin < phMax
  • chlorineMin < chlorineMax
  • temperatureMin < temperatureMax

6.11. Get dashboard

GET /pools/{pool_id}/dashboard

Returns an aggregated dashboard response for frontend consumption.

7. Backend Logic Summary

Pool lifecycle

  1. validate owner;
  2. create or update the pool;
  3. manage technician assignment indirectly through invitations and explicit removal.

Alert-config lifecycle

  1. resolve by poolId;
  2. create default if missing when reading;
  3. update in place when upserting.

Dashboard lifecycle

  1. gather data from pool, owner, values, and visits;
  2. compute latest records in memory;
  3. return a flattened response tailored to the client.

8. Frontend Integration Notes

Pool list screens

Frontend can use:

  • GET /pools
  • GET /pools?ownerId=...
  • GET /pools/user/{user_id}
  • GET /pools/technician/{tech_id}

depending on whether the screen is generic, owner-specific, or technician-specific.

Pool detail screens

Frontend can combine:

  • GET /pools/{pool_id}
  • GET /pools/{pool_id}/dashboard
  • GET /pools/{pool_id}/alert-config

to render a richer operational detail page.

Alert configuration screens

The frontend can safely request alert config even when none exists yet, because the backend auto-creates a default record on first read.

9. UX Considerations

Pool dashboard

The dashboard endpoint is especially useful for mobile or summary views because it saves frontend from orchestrating multiple requests and cross-entity joins.

Alert defaults

Because alert config can be auto-created, the frontend should treat the endpoint as both read and initialization.

10. Current Scope

The current implementation covers:

  • pool CRUD;
  • owner and technician validation;
  • alert configuration;
  • aggregated dashboard data;
  • owner and technician list filters.

It does not currently cover:

  • explicit pool archival state;
  • soft deletion of pools;
  • advanced pool search;
  • explicit technician assignment endpoint outside invitations;
  • pagination or sorting parameters.

11. Future Recommendations

A future version could add:

  • pool archival or status fields;
  • filtering by operational state;
  • pagination for large owner portfolios;
  • richer dashboard metrics;
  • direct technician assignment endpoints if needed.

12. Final Summary

Pool management in Poolia treats the pool as the central business entity and combines direct CRUD behavior with derived operational endpoints such as alert configuration and dashboard aggregation. The design is practical for both backend workflows and frontend summary screens and is consistent with the existing REST architecture.