javier/construprogress
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9c164bb7ef1d1f3180412ea3b984408dbc619313
construprogress/docs/MANUAL.en.md
T

20 KiB
Raw Blame History

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)

Table of contents

  1. Introduction and concepts
  2. System requirements
  3. Installation and deployment
  4. Access and getting started
  5. Roles and permissions
  6. Section-by-section user guide
  7. Typical workflows
  8. API (mobile app)
  9. Maintenance, backups and updates
  10. Troubleshooting (FAQ)
  11. Appendices

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.

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.

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:

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.

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:

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

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

chmod -R ug+rwX storage bootstrap/cache

3.8 Scheduler cron (overdue task alerts)

Add a cron every minute:

* * * * * 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

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

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.

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.

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.

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.

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.

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.

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.

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.

Reference in New Issue View Git Blame Copy Permalink