construprogress/docs/MANUAL.en.md

<!--
  Cover / TOC: this document is meant to be converted to Word.
  - To generate the .docx with headings and a navigable TOC:
      pandoc docs/MANUAL.en.md -o docs/Manual_EN.docx --toc --toc-depth=3
  - The "📷 Screenshot:" blocks are placeholders where the matching image goes.
-->

<div align="center">

# ConstruProgress

## Application Manual

**Construction site tracking system**

MAI Group · RTE International

📷 *Screenshot: cover / application logo (`public/images/logo-rte.png`).*

| | |
|---|---|
| Document version | 1.0 |
| Date | June 2026 |
| Scope | Web application + mobile app API |
| Language | English (Spanish version: `MANUAL.md`) |

</div>

<div style="page-break-after: always;"></div>

---

## Table of contents

1. [Introduction and concepts](#1-introduction-and-concepts)
2. [System requirements](#2-system-requirements)
3. [Installation and deployment](#3-installation-and-deployment)
4. [Access and getting started](#4-access-and-getting-started)
5. [Roles and permissions](#5-roles-and-permissions)
6. [Section-by-section user guide](#6-section-by-section-user-guide)
7. [Typical workflows](#7-typical-workflows)
8. [API (mobile app)](#8-api-mobile-app)
9. [Maintenance, backups and updates](#9-maintenance-backups-and-updates)
10. [Troubleshooting (FAQ)](#10-troubleshooting-faq)
11. [Appendices](#11-appendices)

<div style="page-break-after: always;"></div>

---

# 1. Introduction and concepts

## 1.1 What is ConstruProgress?

ConstruProgress is a web application for **construction site tracking and control**.
It organizes each project into phases, maps its elements on an interactive map, records
inspections via templates, manages issues (with tasks, comments and photos) and produces
reports. It also powers a **mobile app that works offline** in the field and syncs once
back online.

📷 *Screenshot: main dashboard with the overview.*

## 1.2 Key concepts (glossary)

| Term | Meaning |
|---|---|
| **Project** | Main unit of work (a construction site). Contains phases, layers, elements, inspections and issues. |
| **Phase** | A project stage (e.g. Foundations, Structure). Has order, color, progress and planned/actual dates. |
| **Layer** | A grouping of elements on the map within a phase. |
| **Element (feature)** | A geographic object (point/line/polygon) on the map, with status and % progress. |
| **Inspection** | A control record on an element, usually via a **template**. |
| **Inspection template** | A reusable form with configurable fields (text, number, %, boolean, select…). |
| **Issue** | A detected problem or defect: has priority, status, type, tasks, comments and photos. |
| **Issue checklist** | A task list to resolve an issue; can be generated from a **checklist template**. |
| **Role** | A user's set of permissions in the system (Admin, Supervisor…). |
| **Project role** | A user/company's role within a specific project (supervisor, client, constructor…). |

## 1.3 Architecture (technical summary)

- **Backend:** Laravel 12 (PHP 8.2+), Livewire 3 (Volt).
- **UI:** TailwindCSS + DaisyUI, Rappasoft tables, Leaflet maps, Heroicons.
- **DB:** MySQL/MariaDB.
- **Permissions:** spatie/laravel-permission.
- **Mobile API:** Laravel Sanctum (tokens), offline-first sync.

<div style="page-break-after: always;"></div>

---

# 2. System requirements

**Server**
- PHP **8.3** recommended (minimum 8.2). Extensions: `mbstring, pdo_mysql, openssl, tokenizer, xml, ctype, json, bcmath, fileinfo, curl, gd, zip`.
- MySQL/MariaDB.
- Composer. (Node only to build the assets, preferably locally.)
- HTTPS (SSL).

> **Version note:** a dependency (`zipstream-php`) requires PHP 8.3. With PHP 8.2,
> `composer install` needs `--ignore-platform-reqs`. Recommended: use PHP 8.3.

**Client (browser)**
- A modern browser (Chrome, Edge, Firefox, Safari) with JavaScript enabled.

<div style="page-break-after: always;"></div>

---

# 3. Installation and deployment

Guide for a web server such as OVH (VPS recommended; also valid on shared hosting with
the noted caveats).

## 3.1 Database
Create a MySQL database and a user with privileges. Note the **host, name, user and
password**.

## 3.2 Build the assets (on your PC)
The host usually has no Node. Build locally and upload the result:
```bash
npm install
npm run build        # generates public/build
```

## 3.3 Upload the code
Upload the whole project **except** `node_modules/`, `.git/` and `.env`. You can install
`vendor/` on the server (if you have SSH) or upload it.
```bash
composer install --no-dev --optimize-autoloader
```

## 3.4 Document root → `public/` folder
The domain must point to `…/construprogress/public` (never the root).
- **VPS (nginx/apache):** virtualhost `root` → `/path/construprogress/public`.
- **OVH shared:** in *Multisite*, set the domain root folder → `construprogress/public`.

## 3.5 Configure `.env`
Copy `.env.example` to `.env` and adjust:
```ini
APP_NAME=ConstruProgress
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com
APP_LOCALE=es

DB_CONNECTION=mysql
DB_HOST=...
DB_DATABASE=...
DB_USERNAME=...
DB_PASSWORD=...

FILESYSTEM_DISK=public      # photos/files use the public disk
SESSION_DRIVER=database
```

## 3.6 Prepare the application
```bash
php artisan key:generate
php artisan migrate --force
php artisan db:seed --force        # roles, permissions (PermissionCatalogSeeder…)
php artisan storage:link           # public/storage → storage/app/public
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

## 3.7 Write permissions
```bash
chmod -R ug+rwX storage bootstrap/cache
```

## 3.8 Scheduler cron (overdue task alerts)
Add a cron **every minute**:
```cron
* * * * * cd /path/construprogress && php artisan schedule:run >> /dev/null 2>&1
```
This runs `issues:notify-overdue` daily. No queue worker is needed (notifications are
synchronous).

## 3.9 HTTPS
Enable OVH's free SSL (Let's Encrypt) and force HTTPS.

## 3.10 Post-deploy checks
- The home redirects to **login** (correct).
- The **logo** (`/images/logo-rte.png`) and **flags** (`/images/flags/*.svg`) display.
- Uploading a **photo** in an issue works (validates `storage:link` + `FILESYSTEM_DISK=public`).
- The **API** responds: `GET https://yourdomain.com/api/v1/...` with a token.

## 3.11 Deploying later changes
```bash
git pull
composer install --no-dev --optimize-autoloader
# (on your PC) npm run build  and upload public/build
php artisan migrate --force
php artisan config:cache && php artisan route:cache && php artisan view:cache
```

<div style="page-break-after: always;"></div>

---

# 4. Access and getting started

📷 *Screenshot: login screen with the language switcher.*

## 4.1 Sign in
Go to `https://yourdomain.com/login` with your email and password. After installation,
the seeder creates an initial administrator (**admin@email.com**) — **change its
password** as soon as you log in.

## 4.2 Password recovery
From the login, “Forgot your password?” sends a reset email (requires outgoing mail
configured in `.env`).

## 4.3 Profile
In the user menu → **Profile** you can update your details, change your password and
(optionally) delete your account.

## 4.4 Language
The application is available in **Spanish** and **English**. Switch the language with the
flag toggle (🇪🇸/🇬🇧) in the header. Each user also has a **default language** configurable
when creating/editing the user.

<div style="page-break-after: always;"></div>

---

# 5. Roles and permissions

## 5.1 System roles (baseline)

| Role | Baseline permissions (editable) |
|---|---|
| **Admin** | Full access (`manage all`). |
| **Supervisor** | View projects, upload layers, update progress. |
| **Consultant (Consultor)** | View projects, view reports. |
| **Client (Cliente)** | View projects. |

> Each role's permissions are **fully configurable** from *Administration → Roles*
> (permission matrix). The table above is the seeder's initial setup. For a non-Admin
> role to use newer modules (phases, issues, assignments…), grant the matching
> permissions.

📷 *Screenshot: permission matrix when editing a role.*

## 5.2 Permission catalogue (by section)

- **Projects:** view, create, edit, delete, export.
- **Phases & progress:** view phases, manage phases, update progress.
- **Layers & elements:** view, upload/import, edit, delete.
- **Inspections:** view, record, delete, manage templates.
- **Issues:** view, create, edit (resolve/close), delete.
- **Companies:** view, create, edit, delete, **assign to projects**.
- **Users:** view, create, edit, delete, **assign users/roles to projects**.
- **Roles:** manage roles and permissions.
- **Reports:** view panel, export.
- **Files:** view, upload, delete.
- **General:** `manage all` (super-administrator).

## 5.3 Project role (different from the system role)
When assigning **users** to a project you pick their role: *Supervisor, Consultant,
Client, Viewer*. For **companies**: *Owner, Constructor, Subcontractor, Consultant,
Supplier, Other*.

<div style="page-break-after: always;"></div>

---

# 6. Section-by-section user guide

## 6.1 Main dashboard
Home view with the overview: accessible projects, progress, open/critical issues and
recent issues. Includes shortcuts to the sections.

📷 *Screenshot: main dashboard.*

## 6.2 Projects

### Listing
*Projects* shows a table (with search and sorting) of the projects you can access, with
reference, name, address, status, progress and dates. Row actions: **Dashboard**, **Map**
and **Edit**.

📷 *Screenshot: project listing.*

### Create / Edit
The project editor is organized into **tabs**:
1. **Data**: reference, name, address, location (lat/lng on a map), dates and status.
2. **Phases** (see 6.3).
3. **Users** (see 6.11): assign users to the project with their role.
4. **Companies**: assign companies to the project with their role.

📷 *Screenshot: project editor (Data tab).*

## 6.3 Phases
Inside the project editor, the **Phases** tab lists phases in a table (order, name,
progress, dates, color) and lets you:
- **Add phase**: opens a **modal form** with all parameters (name, description, order,
  color, % progress, planned and actual dates).
- **Edit**: same modal with the data loaded.
- **Update progress**: a dedicated screen to record progress.
- **Delete**.
(Requires the *manage phases* permission.)

📷 *Screenshot: Phases tab with the table and the create/edit modal.*

## 6.4 Project map
*Projects → Map* opens the interactive map (Leaflet) with side tabs/panel:
- **Layers & elements**: visualization by layers; selecting an element shows its panel
  with responsible, progress, files and inspections.
- **Inspection**: from an element, pick a template and record the inspection.
- **Files**: the element's file manager.
- **Issues**: tab with the project's issues; from an element you can click **“Issue”** to
  report a new one already linked to that element.

📷 *Screenshot: project map with a selected element panel.*

## 6.5 Layers and elements
Manage layers per phase (import/upload, edit, delete) and the elements they contain,
with their geometry, status and progress.

## 6.6 Inspections and templates
- **Templates** (*Projects → Templates*): configurable forms (text, number, percentage,
  boolean, select, textarea fields…). Each template is versioned for mobile sync.
- **Record inspection**: from the map, on an element, by selecting the template and
  filling its fields (status, result, notes).

📷 *Screenshot: inspection form from the map.*

## 6.7 Issues
Accessible from *Projects → Issues* or the Issues tab on the map.

### Listing
A table (Rappasoft) with **filters by status, priority and type**, search, a task
progress bar, comment/photo counters and an **overdue** tasks badge. The header has
**New issue** and **Templates** (checklist) buttons.

📷 *Screenshot: issue listing with filters.*

### Create / Edit
Dedicated pages (not a modal). Fields: title, description, **priority** (low/medium/
high/critical), **status** (open/in review/resolved/closed), **type** (defect/safety/
quality/documentation/other), assignee and resolution notes. Saving opens the **detail**.

### Issue detail
- **Tasks (checklist)**: add/check/delete tasks with assignee and due date; a % progress
  bar; **apply a checklist template** for bulk creation.
- **Follow-up & comments**: comment thread, each with an optional photo.
- **Issue photos**: a gallery with upload/delete.
- **Verification / workflow**: send to review (when tasks are complete), **validate and
  resolve**, close, reopen; with resolution notes.

📷 *Screenshot: issue detail (checklist + comments + photos).*

### Checklist templates
*Issues → Templates*: create reusable task lists (for recurring defects) to later apply
to any issue.

### Notifications
A bell notification is sent when an issue/task is assigned, when someone comments and on
status changes. The scheduled command alerts about **overdue tasks**.

## 6.8 Gantt chart
*Projects → Gantt*: a timeline view of the project's phases.

📷 *Screenshot: Gantt chart.*

## 6.9 Reports and exports
*Reports* shows a metrics panel and lets you **export to Excel**: projects, phases and
inspections. (Requires *view/export reports* permissions.)

📷 *Screenshot: reports panel.*

## 6.10 Companies
*Companies*: a table (Rappasoft) with search and filters (type, status). Lets you create,
view and edit companies (logo, tax ID, contact, address…). Companies are assigned to
projects with a role from the project's Companies tab.

📷 *Screenshot: company listing.*

## 6.11 Users
*Administration → Users*: a table (Rappasoft) of users. Creating/editing a user includes
personal data, company, status and validity, **system role**, **default language** (with
flags) and notes. Project assignment (with a role) is done from the project's Users tab.

📷 *Screenshot: create/edit user form (with the language selector).*

## 6.12 Roles and permissions (administration)
*Administration → Roles*: a roles table; creating/editing a role assigns permissions via
a **matrix** grouped by section. *Administration → Permissions* shows the full catalogue.

## 6.13 Client portal
Client-role users get a **simplified panel** (`/client`) focused on checking the progress
of their projects.

## 6.14 Files / gallery
Each project and element has a file manager (images and documents) with upload, viewer
and delete, according to *Files* permissions.

<div style="page-break-after: always;"></div>

---

# 7. Typical workflows

## 7.1 Set up a project (Admin/Supervisor)
1. **Projects → New**: fill in data and location.
2. **Phases** tab: create phases with dates and colors.
3. **Users/Companies** tabs: assign the team and companies with their role.
4. **Map**: create layers and import/draw the elements.
5. **Templates**: define the inspection templates you need.

## 7.2 Field/office tracking
1. On the **Map**, select an element and **record an inspection**.
2. If you spot a problem, click **“Issue”** to create it linked to the element.
3. In the **issue detail**, add the **checklist** (or apply a template), assign owners
   and dates, upload **photos** and comment on progress.
4. When all tasks are done, **send to review** and then **validate and resolve**.

## 7.3 Reporting and closing
1. Update the **progress** of phases/elements.
2. Check the **Gantt** and the project **Dashboard**.
3. In **Reports**, export projects/phases/inspections to Excel for delivery.

<div style="page-break-after: always;"></div>

---

# 8. API (mobile app)

The application exposes a REST API (prefix `/api/v1`) designed for an **offline-first**
mobile app. The full contract lives in:
- `docs/openapi.yaml` — OpenAPI 3 specification.
- `docs/MOBILE_SYNC_PROTOCOL.md` — sync protocol.
- `docs/MOBILE_APP_BRIEF.md` — handoff guide with examples and the data model.

## 8.1 Authentication
Per-device **Sanctum** tokens (ability `mobile-sync`). `POST /login` returns the token;
all other calls use `Authorization: Bearer <token>`.

## 8.2 Endpoints
| Method | Route | Use |
|---|---|---|
| POST | `/api/v1/login` | Device token |
| GET | `/api/v1/me` | User + permissions |
| POST | `/api/v1/logout` | Revoke token |
| GET | `/api/v1/projects` | Accessible projects |
| GET | `/api/v1/projects/{id}/bundle?since=` | Download (snapshot or delta + deletions) |
| GET | `/api/v1/templates?since=` | Templates (version/hash) |
| POST | `/api/v1/sync` | Push changes (idempotent by `uuid`) |
| POST | `/api/v1/media` | Upload files (multipart) |

## 8.3 Sync model (summary)
- **PULL**: full `bundle` the first time; then `?since=<date>` returns only what changed
  plus the **deleted ids** (tombstones). The `since` parameter must be **URL-encoded**.
- **PUSH** `/sync`: a batch of operations, each with `uuid` (idempotency) and
  `client_updated_at`. Per-operation response: `applied | duplicate | conflict | error`
  (conflicts via *last-write-wins*).
- **Media**: multipart, idempotent by `uuid`, attached to the parent entity.
- **Security**: the server sets `user_id`/`project_id` and validates permissions per op.

> Operation, payload and field detail: see `docs/MOBILE_APP_BRIEF.md`.

<div style="page-break-after: always;"></div>

---

# 9. Maintenance, backups and updates

## 9.1 Backups
- **Database**: daily backup (`mysqldump`) — contains all data.
- **Uploaded files**: back up `storage/app/public` (photos, logos, documents).
- Also keep a copy of `.env` (contains keys and credentials) in a safe place.

## 9.2 Version updates
Follow 3.11: `git pull`, `composer install --no-dev`, rebuild assets, `migrate --force`
and regenerate caches. Back up **before** migrating.

## 9.3 Scheduled tasks
The scheduler cron (3.8) must be active for overdue task alerts.

## 9.4 Best practices
- `APP_DEBUG=false` in production.
- Force HTTPS.
- Change default credentials and review role permissions.

<div style="page-break-after: always;"></div>

---

# 10. Troubleshooting (FAQ)

**No styles / the page looks “broken”.**
Compiled assets were not uploaded. Run `npm run build` and upload `public/build`; check
`APP_URL` is correct and regenerate caches.

**Images/photos don't show (broken icon).**
Missing storage link: `php artisan storage:link` and `FILESYSTEM_DISK=public`.

**500 error after deploying.**
Check `.env` (DB, `APP_KEY` via `key:generate`), permissions on `storage/` and
`bootstrap/cache`, and `php artisan config:clear`.

**Flags show as “ES/GB” instead of the flag.**
That's some systems' emoji behavior; the app uses local SVG flags (`/images/flags`).
Verify that folder was uploaded.

**A user can't see a module / can't create.**
It's a permissions matter: grant them to their role in *Administration → Roles*.

**`composer install` fails due to PHP version.**
Use PHP 8.3, or `composer install --no-dev --ignore-platform-reqs`.

**Overdue alerts don't arrive.**
The scheduler cron (3.8) is missing, or mail/notifications aren't configured.

<div style="page-break-after: always;"></div>

---

# 11. Appendices

## 11.1 Main route map
| Section | Route |
|---|---|
| Login | `/login` |
| Dashboard | `/dashboard` |
| Projects | `/projects` |
| Edit project | `/projects/{id}/edit` |
| Map | `/projects/{id}/map` |
| Gantt | `/projects/{id}/gantt` |
| Project report | `/projects/{id}/report` |
| Issues | `/projects/{id}/issues` |
| Checklist templates | `/projects/{id}/issues/checklists` |
| Inspection templates | `/projects/{id}/templates` |
| Companies | `/companies` |
| Users | `/admin/users` |
| Roles | `/admin/roles` |
| Permissions | `/admin/permissions` |
| Reports | `/reports/dashboard` |
| Client portal | `/client` |

## 11.2 Related documents
- `docs/openapi.yaml`, `docs/MOBILE_SYNC_PROTOCOL.md`, `docs/MOBILE_APP_BRIEF.md`.

## 11.3 Screenshot index
> List of the “📷 Screenshot:” placeholders throughout the manual, to insert when
> converting the document to Word.