MaisPraia

MaisPraia is a web and mobile operations platform for lifeguard associations. It was created to replace fragmented workflows spread across WhatsApp, paper, email, Google Forms, and Excel with one structured operational system.

The project is not primarily about moving forms onto a screen. Its central engineering problem is converting flexible, informal organizational behavior into explicit domain rules while preserving a usable workflow for the people doing the work.

The problem

Before MaisPraia, the association’s operational state was distributed across several tools.

At the end of each month, lifeguards submitted availability through a Google Form. Coordinators used those responses to build the next schedule manually in Excel, then distributed static copies through WhatsApp.

During the month, shift changes were recorded on paper and confirmed in messages. The original schedule was not always updated. As changes accumulated, the association could have several versions of the same operational truth:

Google Form → Excel → WhatsApp → paper annotations → coordinator knowledge

The same pattern affected incident reporting, equipment requests, documentation, operational information, and team communication. Information existed, but it was difficult to structure, retrieve, audit, and analyze.

MaisPraia centralizes that lifecycle:

Availability
    ↓
Scheduling
    ↓
Shift management
    ↓
Attendance and daily operations
    ↓
Incidents, equipment, documentation, and notifications

The architectural objective is a single, current source of truth—not another static representation that becomes stale after the first operational change.

Operational context

The platform targets an association operating at approximately the following scale:

Dimension	Current known scale
Lifeguards	≈60
Beaches	≈20
User contexts	Administrators and lifeguards

Administrators need broad operational views: workforce management, availability, schedules, changes, attendance, incidents, equipment, documentation, and notifications.

Lifeguards need fast access to their current assignment and the actions closest to daily work: submitting availability, consulting schedules, requesting changes, registering attendance or incidents, requesting materials, and receiving operational information.

This difference affects both authorization and interface design. An administrative schedule editor and a lifeguard’s mobile daily view expose the same operational domain from very different perspectives.

System scope

The platform organizes the association’s workflow into connected modules:

Area	Responsibility
Availability	Collect monthly availability without an external form
Scheduling	Build and maintain assignments for each operational location
Shift changes	Validate, approve, persist, and communicate assignment changes
Attendance	Associate operational presence with people, places, and schedules
Daily operations	Record structured information about beaches and pools
Incidents	Capture reports through a retrievable, consistent workflow
Equipment	Track operational needs and material requests
Documentation	Keep relevant operational documents centrally accessible
Notifications	Communicate relevant events through application and web push capabilities

Modules are not isolated CRUD screens. Their value comes from shared identities, locations, assignments, permissions, and history.

Architecture

MaisPraia uses a client-server architecture with web and mobile clients, a Spring Boot backend, and PostgreSQL.

┌──────────────────────────┐       ┌──────────────────────────┐
│ Angular web application  │       │ Ionic mobile application │
│ Progressive Web App      │       │ Mobile-oriented flows    │
└─────────────┬────────────┘       └─────────────┬────────────┘
              │                                  │
              └──────────── HTTP / REST ─────────┘
                                 │
                     ┌───────────▼───────────┐
                     │ Spring Boot backend   │
                     │                       │
                     │ Domain logic          │
                     │ Authentication        │
                     │ Authorization         │
                     │ Operational APIs      │
                     └───────────┬───────────┘
                                 │
                     ┌───────────▼───────────┐
                     │ PostgreSQL            │
                     │ Operational state     │
                     └───────────────────────┘

The development environment is containerized with Docker and Docker Compose. Flyway migrations version the database schema alongside the application.

The final public deployment topology is intentionally not documented yet. It will be added only after the production infrastructure is finalized and verified.

Domain model

The domain centers on the relationship between lifeguards, operational locations, schedules, and daily activity.

Lifeguard
   │
   ├── submits ────── Availability
   │
   ├── assigned to ─ Shift
   │                    │
   │                    └── belongs to ─ Operational Location
   │
   ├── records ────── Attendance
   ├── reports ────── Incident
   └── requests ───── Equipment / Material

Principal concepts include users, lifeguards, roles, beaches and pools, availability, schedules, shifts, assignments, shift changes, attendance, incidents, equipment, material requests, documents, and notifications.

This public representation is deliberately simplified. The model will be updated from implemented entities and invariants as individual modules stabilize rather than maintained as a speculative diagram.

Key engineering decisions

Keep operational state in the system

Previously, one schedule could be represented by an Excel file, paper changes, WhatsApp messages, and the private knowledge of coordinators. MaisPraia moves operational changes into structured database state.

An approved shift change must update the current assignments. It cannot remain a disconnected message that people later reconcile manually. This principle shapes both the domain model and the transaction boundaries.

Use a relational database

PostgreSQL fits a domain made of strongly related records: users, schedules, shifts, locations, availability, incidents, and equipment. These workflows require referential integrity and, in important operations, consistent changes across multiple records.

A relational model also supports the historical and analytical questions the organization may need to ask later without treating each module as a separate data island.

Put business rules behind a structured backend

Spring Boot provides the application structure for domain services, REST APIs, persistence, validation, authentication, authorization, and transactional business logic.

The backend is the enforcement boundary. Rules such as who can approve a change or access administrative records cannot depend only on whether a frontend control is visible.

Share a frontend ecosystem across web and mobile

Angular supports the main web application, while Ionic extends the broader frontend ecosystem toward mobile-oriented usage. This avoids maintaining two completely unrelated client stacks while still allowing interfaces to reflect different working contexts.

PWA capabilities support installability and web push notifications. They are particularly relevant because lifeguards interact with the system in mobile operational environments.

Make authorization explicit

The platform uses JWT-based authentication and Role-Based Access Control.

Administrator                       Lifeguard
├── Manage users                    ├── Submit availability
├── Manage locations                ├── View assigned schedule
├── Create schedules                ├── Register operational information
├── Review incidents                ├── Submit incidents
├── Manage operational records      ├── Request materials
└── Manage organizational resources └── Access relevant documentation

Both groups interact with the same operational data, but their responsibilities and permissions differ. Those boundaries are represented and enforced by the application rather than treated as a presentation concern.

Deep dive: turning a message into a workflow

Informal tools are flexible because they impose few rules. A message such as “I swapped tomorrow’s shift with another lifeguard” is understandable to people, but incomplete as durable system state.

The software workflow has to make the hidden decisions explicit:

Shift change requested
        ↓
Participants and assignments identified
        ↓
Current schedule state validated
        ↓
Required approval recorded
        ↓
Assignments updated consistently
        ↓
Affected users notified
        ↓
Change retained as operational history

Each step introduces questions that an informal conversation can leave ambiguous. Is the requester assigned to that shift? Is the replacement available and authorized for the location? Has another change already modified the assignment? Who can approve it? What should happen if notification delivery fails after the database update?

This is why the scheduling and shift-change problem is primarily one of domain modeling, state transitions, validation, and consistency—not form design.

Engineering challenges

Maintaining a current schedule

The initial monthly schedule is only one state in a continuously changing process. The system must expose the current assignments after approved changes, not preserve an immutable spreadsheet while recording corrections elsewhere.

This requires a clear distinction between a change request, its approval state, the resulting assignments, and the retained audit history.

Serving different user contexts

Administrators need tables, filters, bulk operations, historical records, and broad schedule visibility. Lifeguards need a fast mobile path to their current assignment and frequent operational actions.

The challenge is to avoid exposing backend complexity to lifeguards without hiding the state and controls administrators need to manage the organization safely.

Replacing habits, not just software

Adoption is an engineering constraint. A theoretically complete workflow that is slower than sending a message will push users back toward WhatsApp and recreate fragmented state outside the system.

The design therefore has to balance validation and auditability with the speed of real operational work.

Quality strategy

Testing is organized around risk rather than raw coverage.

Unit tests          → domain rules and state transitions
Integration tests   → database, migrations, and services
API tests           → authorization and external behavior
Frontend tests      → critical client workflows
End-to-end tests    → complete operational scenarios

The highest-value scenarios include authentication, authorization, availability submission, schedule creation, shift assignment, shift changes, attendance, and incident registration.

Database migrations are treated as application changes. Flyway keeps schema evolution reproducible between containerized development environments and future deployments.

Security considerations

The platform handles organizational and personnel-related information. Relevant controls include authenticated access, backend authorization, secure password storage, input validation, role separation, careful JWT handling, and protection of administrative operations.

Important changes such as schedule assignments and approvals also need sufficient auditability to explain how the current state was reached.

This case study intentionally excludes real user data, credentials, internal identifiers, production secrets, and sensitive operational information.

Current state and measurement policy

MaisPraia is in active development as a real operational platform rather than a tutorial project. The main architecture and domain have been established across authentication, workforce management, availability, scheduling, operational records, incidents, equipment, documentation, notifications, and web/mobile access.

The precise deployed scope will be updated as individual modules enter operational use.

Performance or impact numbers will not be published until they have a reproducible measurement source. Planned measurements include:

• API p50, p95, and p99 latency;
• database query performance and error rates;
• frontend performance and notification delivery success;
• schedules and shift changes processed;
• administrative time required to create a schedule;
• time required to process a shift change;
• operational workflows moved away from messages and paper.

The only scale figures currently presented are the known association context: approximately 60 lifeguards and 20 beaches. They describe the target operation, not measured platform throughput.

Results so far

The concrete architectural result is a shared model for operational work that was previously fragmented across forms, spreadsheets, paper, email, and messages.

                         MaisPraia
                            │
              ┌─────────────┼─────────────┐
              ↓             ↓             ↓
         Workforce      Operations      Records
              │             │             │
        Availability    Incidents      Attendance
        Scheduling      Equipment      Documentation
        Shift changes   Requests       History

The expected organizational impact—less reconciliation work, faster changes, and more complete records—remains to be measured after operational deployment. It is not presented as a completed result yet.

Known limitations and future work

• Measure production performance and operational impact.
• Add load testing around critical scheduling and reporting workflows.
• Improve observability and audit history.
• Evaluate scheduling assistance and optimization.
• Measure and improve notification reliability.
• Define degraded-connectivity and offline behavior from real field requirements.
• Automate operational reporting where it removes verified administrative work.
• Document the production deployment topology once finalized.

These are development directions, not implemented-feature claims.

Engineering lesson

Digitizing an organization is not simply a matter of building CRUD interfaces.

Processes that previously depended on messages, spreadsheets, paper notes, and coordinator knowledge have to become entities, permissions, state transitions, validations, and historical records. The difficult work is deciding where flexibility is necessary, where consistency is non-negotiable, and how the system can remain usable enough to become the actual source of truth.

MaisPraia is therefore an exercise in domain modeling, product engineering, and operational system design as much as it is a web and mobile application.