Econ systemtutorial

This tutorial explains how Econ works end to end — for office staff on this web dashboard, field workers on the mobile app, and equipment owners. Use the menu on the left to jump to a specific operation (creating a project, starting a site, scanning QR, approving trip issues, generating reports, and more).

What you will learn

• How to set up a company, project, site, and field team from zero.
• LINEAR (chainage) vs AREA (map polygon) projects — when to use each.
• All 11 trip process types: standard QR, no-loader, paper QR, offline, exceptions, and more.
• How GPS verification works for loader, driver, and unloader on LINEAR and AREA sites.
• How to read reports, approve trip issues, and close a site.

Shorter topic pages are also available from the home menu: Platform, Trips, Trip issues, Office dashboard, Roles.

Office (this website)  →  ComapySass API  →  projects, sites, reports, users
Field (mobile app)     →  Field API         →  trips, QR, offline queues, equipment

Both share the same business story: projects consume equipment and record every delivery trip.

A typical day

• Morning — office: log in, switch company, check dashboard KPIs, add a site or adjust members.
• Morning — site: foreman opens Work, syncs after poor coverage, starts site or opens loader/driver screens.
• Handoff — loader shows QR; driver scans; unloader completes at destination.
• Evening — office: products/equipment reports; approve trip issues; generate site report.
• Evening — owner: mobile Reports tab for machine trip history.

Econ connects equipment owners, construction companies, and field workers through one trip-tracking story. Everything below happens in order — skip a phase and field work will block.

Registration → Company users → Project setup → Foreman starts site
    → Loader QR / driver scan / unloader complete → Reports & verification

Registration today means: your phone is already in the system, you log in with a Telegram one-time code. Self-signup on /register is not wired — an admin must add you first (Phase 4).

1. 1
   Open login

   Web /login or mobile app login screen.

2. 2
   Enter phone

   International format (e.g. 2519…). Mobile normalizes 09… and 9-digit local numbers.

3. 3
   Request code

   Backend sends 6-digit code to Telegram bot linked to that phone.

4. 4
   Enter code

   JWT stored; user lands on dashboard (web) or five tabs (mobile).

5. 5
   If login fails

   “User not found” — phone not in company_workers. Admin adds you in User Management.

Equipment owners use the mobile marketplace to list trucks and machines. This is separate from company project work but feeds the equipment pool companies can assign to drivers.

1. 1Home tab — browse equipment with filters (category, location, type).
2. 2Add Post — 5-step wizard: category → type → specs → up to 4 images → details (phone required).
3. 3Account — profile, my equipment, update GPS location for nearby features.
4. 4Reports tab — trip history per machine (usage, not favorites).

Office analytics for equipment compliance live on the web dashboard, not the public /hearted placeholder route.

Phase 3 — Company registration

• A company record is created (name, settings, feature flags such as area_projects).
• First owner and system admin are attached to the company.
• Done by operations / system admin — not self-service on the public site.

Phase 4 — Add company workers

Route: /dashboard/CompanyUsers — HR adds people to the company directory.

Field roles vs dashboard roles

Every project has a project type that controls how geometry, sites, places, and GPS verification work.

Prerequisite: Company has area_projects feature enabled.

Step 1 — Create AREA project

1. 1Projects → + New project → choose AREA type (not CSV chainage).
2. 2Draw the project boundary polygon on the map (at least 3 points, closed area).
3. 3Save — project stores boundaryGeoJson.

Step 2 — Add products & places

1. 1Add products as usual (DELIVERY or DISPOSAL type).
2. 2Open Product places — chainage fields are hidden for AREA.
3. 3Enter latitude and longitude for each place (LOADING, UNLOADING, or DISPOSAL).
4. 4Set geofence radius (m) — used for GPS verification at that place.
5. 5Distance field remains available where applicable.

Step 3 — Create site on map

1. 1Manage Sites → map shows project boundary (brand color).
2. 2Draw site polygon inside project area — clicks outside boundary are rejected.
3. 3Or tick “Use whole project area” to inherit full boundary.
4. 4Select products and places; set start date and site name.
5. 5Save — site stores boundaryGeoJson (or null for full-area sites).

Step 4 — Field & verification

• Foreman starts site on mobile same as LINEAR.
• Trips unload inside site polygon (DELIVERY) or pickup inside polygon (DISPOSAL).
• Office Trip Details shows GPS badges per role — see GPS verification section.
• Click site area on dashboard to open map overlay (project + site polygons).

Disposal tracks material picked up from a site zone and dumped at configured destinations. Works on both LINEAR and AREA projects with different geometry inputs.

Office setup (Phase 5)

1. 1Create DISPOSAL product on project.
2. 2Add DISPOSAL places (dump destinations) with GPS or chainage.
3. 3Manage Sites → check Disposal site.
4. 4Select DISPOSAL product(s) and which dumps apply to this site.
5. 5Optional: Allow trip without unloader — driver can complete alone (Mode 1B).

Foreman site starter (Phase 7)

GPS verification (AREA disposal)

• Loader + driver-load: must be inside site polygon (pickup zone).
• If dump destination selected: driver-unload + unloader checked against DISPOSAL place GPS.
• If no dump selected (pickup-only): dump-side checks PASS automatically.

1. 1
   Foreman starts disposal site

   Site starter: pickup loaders + per-dump unloaders (if required). No supervisor.

2. 2
   Loader at pickup

   Shows QR at site pickup zone; driver scans as standard delivery.

3. 3
   Driver transport

   May select dump destination if multiple dumps configured.

4. 4
   Unloader at dump

   Assigned per dump place; completes trip at destination GPS.

5. 5
   Without unloader flag

   If office enabled allow trip without unloader, driver completes trip at dump.

Phase 8 covers every trip process type the system supports. Pick the scenario that matches your site configuration.

loading → driving → unloaded → (needs checking) → approved
         ↘ issue_reported → pending_approval → approved/rejected

The default flow: loader shows QR → driver scans → unloader completes.

Before first trip (office + foreman)

1. 1Project has products and product places.
2. 2Site created with products/places; allowDriverTripWithoutLoader = off.
3. 3Loader, driver (+ equipment), unloader are project members.
4. 4Foreman started site → status Loading.
5. 5Loader assigned to place; driver on site personnel.

Loader — step by step

1. 1Work → project → Loader sites (Loading status only).
2. 2Loader site detail → select driver + product.
3. 3Tap Show QR — app captures GPS, POST scanQRCode → trip status loading.
4. 4Driver scans QR from LoaderQRCodeDialog.

Driver — step by step

1. 1Work → Driver sites → Scan QR.
2. 2Camera decrypts payload; confirm car/plate if prompted.
3. 3POST acceptTrip → status driving.

Unloader — step by step

1. 1Work → Unloading sites → Unloader site detail.
2. 2Scan QR or pick trip; enter chainage (LINEAR) or confirm GPS (AREA).
3. 3POST completeTrip → status unloaded.

Common failures & recovery

Drivers start trips without loader QR when office enabled the site flag and foreman started with supervisor only.

Prerequisites

• allowDriverTripWithoutLoader = true on site (office Manage Sites).
• Supervisor assigned on Site starter.
• Site started → Loading (may start with supervisor only — no loader teams).
• Driver is project member with equipment/plate.
• For offline create: driver needed one prior online session to cache equipment list.

Field steps

1. 1Foreman: Site starter → assign supervisor only → Start site.
2. 2Driver: Work → site → Create trip without loader → pick product + equipment.
3. 3Trip goes directly to driving (no loading status from loader).
4. 4Unloader completes as standard.

For yards without phones at the loading point, office generates a printed QR from site detail.

Office — generate & print

1. 1Site detail → Loader paper QR section.
2. 2Generate QR (payload includes r: paper marker).
3. 3Print and post at loading point.

Field — driver scan

1. 1Driver scans paper QR (no loader phone needed).
2. 2Backend creates new trip + accepts in one step → driving.
3. 3Unloader completes as standard.

When a site has 2+ product places, each place can have its own loader running parallel trips.

1. 1Office: site links multiple places per product (or multiple products).
2. 2Foreman: Site starter assigns one loader per place.
3. 3Each loader generates independent QR → separate trip rows.
4. 4Drivers must scan the QR from their assigned loader/place.
5. 5Unloaders complete each trip independently.

Numeric codes alongside QR for poor connectivity or sites that require manual confirmation.

When to use codes vs QR only

• QR-only: good connectivity, standard handoff.
• Codes: backup when camera fails or process requires verbal confirmation.
• Expired codes: UI shows expired — regenerate by re-showing QR or re-accepting per safety rules.

Mobile queues failed mutations locally. When back online, Work → Sync all uploads them in order.

Sync algorithm

1. 1User taps sync badge on Work tab (must be online).
2. 2Pass 1: Q1 creations → Q2 accepts → Q3 driver trips → Q4 completes.
3. 3Pass 2: retry any that failed due to ordering (e.g. accept before create landed).
4. 4Refresh cached site data (up to 15 sites per project).
5. 5If N failed: stay online, sync again, or contact support with timestamp.

Outcome scenarios

• All succeed: trips reach unloaded; queues cleared.
• Partial fail: some trips stuck — retry sync; check which queue failed.
• Idempotent retry: alreadyAccepted / alreadyCompleted treated as success.
• Duplicate guards: system blocks abusive duplicate offline payloads.

When a driver scans before the loader trip reaches the server (loader offline, driver online), the accept may be buffered instead of failing permanently.

1. 1Loader offline: shows QR locally, trip in Q1 queue.
2. 2Driver online: scans QR → server may store pending_offline_events buffer.
3. 3Loader syncs Q1 → trip created on server.
4. 4Next sync pass applies buffered accept → driving.

Foreman or coordinator can change personnel while site is Loading.

1. 1Site detail → remove driver from site personnel or change assignment.
2. 2Add new driver from project member pool.
3. 3In-flight trips keep original driver until complete.
4. 4New loader QR uses newly selected driver only.

Office engineers can correct trip data after field completion.

1. 1Open site detail or project trips table.
2. 2Select trip → edit quantity, times, plate, locations where permitted.
3. 3Save — may trigger re-verification or report recalculation.
4. 4For exceptions: use trip issue approval flow instead of raw edit.

Goal: Project exists, materials defined, sites created, people assigned — before field work begins.

Detailed order for a new LINEAR project

1. 1Create project from CSV or map points — verify chainage range on project card.
2. 2Add each material as a product with unit and target quantity.
3. 3For DELIVERY products: add LOADING places along chainage; optional UNLOADING places.
4. 4For DISPOSAL products: add DISPOSAL dump places with GPS or chainage.
5. 5Assign all field workers as project members; pick truck plate for each driver.
6. 6Create sites: delivery sites use chainage range; disposal sites tick isDisposalSite and pick dumps.
7. 7Open site detail: set foreman, average speed, loading/unloading times.

Detailed order for a new AREA project

1. 1Confirm company has area_projects feature enabled.
2. 2Create AREA project — draw closed boundary polygon on map.
3. 3Add products; for each place enter lat/lng (chainage not used).
4. 4Assign project members as above.
5. 5Manage Sites — draw site polygon inside project boundary (or use whole project area).
6. 6Verify site area displays on dashboard; click to preview map overlay.

Phase B — Field start (mobile)

Phase C — Daily operations (mobile)

1. 1Loader: assign driver, display QR (or use printed loader paper QR from web site page).
2. 2Driver: scan QR to accept trip — status becomes driving.
3. 3Driver: transport; use verification codes if your process requires them.
4. 4Unloader: scan or verify to complete unloading — trip becomes unloaded.
5. 5If offline: when back online, Work → tap sync badge to upload queued actions.

1. 1
   Open /login

   Enter phone number in international format as your organization standardizes.

2. 2
   Request code

   Backend sends a one-time code; user reads it in Telegram.

3. 3
   Enter 6-digit code

   App stores JWT and redirects to /dashboard.

4. 4
   Switch company (if applicable)

   Header → Company dropdown → pick company → new token for that company → dashboard reloads.

5. 5
   Logout

   Sidebar Logout clears session; use on shared PCs.

Quick actions (large tiles)

• Projects → project list
• Products → products report (not in narrow sidebar)
• Users → Company Users
• Account → account settings

What you see on the dashboard

• Overview cards: total cars, users, projects, active sites.
• Material delivery: each product row — planned vs delivered, progress bar; tap row for product analysis.
• Trip statistics: counts by loading, driving, unloading, unloaded, needs checking, approved.
• Site statistics: not started, loading, done, with/without foreman.
• Recent trips, sites, projects — useful for daily standups.

Route: /dashboard/CompanyUsers — used by HR / admin.

Mode A — By phone (Telegram user)

1. 1Open Add User → choose By phone.
2. 2Enter country code and phone; fetch preview if offered.
3. 3Select role from directory → Save under current company.

Mode B — Without Telegram

1. 1Choose Without Telegram — read warning: user becomes Loader_load only; role cannot be changed later.
2. 2Enter name, phone, optional username → Save.

1. 1Sidebar → Projects (/dashboard/projectsHome).
2. 2Search filters project names on the current loaded page (10 per page).
3. 3+ New project opens creation dialog.
4. 4Export CSV downloads Project Name, Cars, Workers, KPI %, Points, Chainage Range for the current filtered page — paginate if you need all projects.

Prerequisite

Login must have an active company. If the dialog says company is missing, re-login or switch company.

Mode A — Upload CSV

1. 1Tab Upload CSV → enter project name.
2. 2File must end with .csv.
3. 3Required columns: chainage, easting, northing, elevation.
4. 4Example row: 13+800,500000.0,1200000.0,1500.5
5. 5Submit Create — wait for success — page reloads.

Mode B — From map points

1. 1Tab From map points → project name.
2. 2Set interval in meters (e.g. 50) for derived chainage along the polyline.
3. 3Optional starting chainage: 0+000, 13+800, or plain meters; empty = 0+000 at first point.
4. 4Enter at least two points per line as longitude,latitude (WGS84), e.g. 38.123456,9.012345.
5. 5Optionally click the map to append points.
6. 6Submit Create project.

Route: /dashboard/projectsHome/[id]

Recommended order for a new project

1. 1Products — create each material (name, unit, targets).
2. 2Product places — for each product, define places along chainage.
3. 3+ Add / Manage Users — attach company workers; drivers must pick plate/equipment when required.
4. 4Manage Sites — create sites (see next section).
5. 5Cars dialog — maintain project vehicles as needed.

Assign existing worker to project

1. 1Open + Add / Manage Users.
2. 2Select worker from available list.
3. 3If role is driver — pick equipment / plate before assign.
4. 4Assign to project — confirm row in members table.

Invite by phone from project dialog

1. 1Enter country code and phone → fetch preview.
2. 2Choose role and status → Save (may create company worker then assign).
3. 3Tell user to log in on mobile with same phone.

Open Manage Sites from project detail. For LINEAR projects the dialog shows allowed chainage range. For AREA projects use the map-based site dialog — see AREA projects section.

After save, open the site from the table for trip management and reports.

Route: .../sites/[siteId]

Trips table

• Monitor statuses: loading, driving, unloading, unloaded, needs checking, approved.
• Trip issue banners show when driver reported an issue or foreman classified — waiting for backoffice.
• Edit trip fields where permissions allow (quantity, times, plates).

Site settings

• Set foreman / supervisor.
• Average car speed, loading time, unloading time — often required before save.

Loader paper QR

Generate printable QR for yards without phones at the loading point (paper QR creates a new trip on driver scan — see QR scenarios).

Generate report

1. 1Check whether a report already exists for the site/day.
2. 2Click Generate Report when eligible trips are complete — recalculates equipment-per-trip scores for that calendar day.
3. 3Approving a trip issue can run the same logic for that single trip only.

Finish site

When work is truly complete, use the action to set site status Done.

NONE → ISSUE_REPORTED → PENDING_APPROVAL → APPROVED
                              ↘ reject → ISSUE_REPORTED (foreman may re-classify)

Step by step

1. 1
   Driver reports issue

   Mobile — trip owner flags problem. Status: issue_reported. Excluded from product totals.

2. 2
   Foreman classifies

   Mobile or dashboard — picks one of four resolution types. Status: pending_approval.

3. 3
   Backoffice approves or rejects

   Dashboard Trip Exception panel on site/project — roles: owner, sys_admin, project_manager, office_engineer, site_engineer.

4. 4
   On approve

   reportValue snapshotted from classification. Reached intended / new useful location → trip may become unloaded + per-trip equipment report generated.

5. 5
   On reject

   Returns to issue_reported; classification cleared; foreman can submit again.

See Trip issues (exceptions) below for classification values and report impact.

1. 1Dashboard quick action → Products (/dashboard/products-report).
2. 2View aggregates across projects: target vs current, active trips hints.
3. 3Use search and filters.
4. 4Click a product for Product analysis — charts, progress, logistics views.
5. 5Approved trip issues contribute fixed report values; pending issues contribute zero.

1. 1Sidebar → Equipment Report.
2. 2Choose date range (calendar).
3. 3Optionally filter by project and site.
4. 4Generate / refresh — driver-centric compliance-style summary.
5. 5Click equipment row for individual machine view (period may default to today — check on-screen labels).

• Install from Play Store or internal channel your company provides.
• If forced update modal appears, install latest build from store.
• Grant camera (QR) and location (nearby projects, trip payloads).

Sign in

1. 1Enter phone — app normalizes 09… to 2519…, 9-digit local to 251…, keeps 251… as-is.
2. 2Send code → read Telegram → enter 6 digits on passcode screen.
3. 3Five tabs appear on success.
4. 4Logout: Account → Log out on shared phones.

• Title: Projects — subtitle Online or Offline · using saved data.
• Filter chips: All, Active, Upcoming, Completed (derived from material progress on cards).
• Sync badge (top right): upload offline queues when online.
• Project cards: name, dates, site count, progress — tap to continue.

Role priority (multiple hats)

If user has mixed roles, Work filters in order: Loader first, else Driver, else Unloader, else generic coordinator list.

1. 1
   Work → project

   Generic routing → Sites list with Active / Done / All.

2. 2
   Not Started site

   Site starter: assign loader per product place, assign supervisor, Start site when enabled.

3. 3
   Driver without loader sites

   Start may enable with supervisor only when office enabled the flag.

4. 4
   Loading / Done site

   Site detail — manage drivers, loaders, unloaders, view trucks.

5. 5
   Classify trip issues

   When driver reported issue — pick resolution type → pending_approval for backoffice.

1. 1
   Work → project

   See loader-assigned projects only.

2. 2
   Loader sites

   Lists sites in Loading status (Not Started may use Start loading flow first).

3. 3
   Loader site detail

   Refresh trucks → select driver → show QR in LoaderQRCodeDialog.

4. 4
   Wait for driver scan

   Online: immediate accept. Offline: show QR, sync later from Work.

5. 5
   Pending trips strip

   If offline at QR time, local pending items until sync succeeds.

1. 1
   Work → project → Driver sites

   Cards show chainage, pending cars, coarse status.

2. 2
   Scan QR

   Camera → scan loader QR → confirm → trip becomes driving (same trip, no duplicate).

3. 3
   Transport & codes

   Use car info and verification codes per site process.

4. 4
   Report trip issue

   If delivery went wrong — flags issue_reported for foreman.

5. 5
   Create trip without loader

   Only if site.allowDriverTripWithoutLoader — pick product + equipment; may need one online session to cache trucks.

1. 1
   Work → project → Unloading sites

   My unloading sites list.

2. 2
   Unloader site detail

   See incoming vs unloaded trucks.

3. 3
   Scan / complete unload

   Correct QR for trip → confirm → unloaded.

4. 4
   Refresh & sync

   Pull to refresh if stale; Work → sync after offline complete.

Sync all

1. 1Be online → Work → tap sync badge.
2. 2Upload order: creations → accepts → driver trips → completes (may repeat once).
3. 3Refreshes cached site data (bounded: up to 15 sites per project).
4. 4If N failed, stay online and sync again or contact support.

Some deployments use numeric codes alongside or instead of QR:

• Loader may show loader verification code with expiry on trip card.
• Driver enters or confirms driver code after scan.
• Unloader uses unloader verification code on car row.
• Expired codes show expired in UI — request regeneration per safety rules.

PHASE 5 — Office: project, products, places, sites, members
PHASE 6 — Office: foreman, speed, loading/unloading times, flags
PHASE 7 — Foreman: Site starter → assign teams → Start site (Loading)
PHASE 8 — Field:
    Loader: assign driver → QR (or paper QR / driver-create if configured)
    Driver: scan QR → driving → transport
    Unloader: scan/verify → unloaded
PHASE 9 — Office:
    GPS verification → needs checking / approved
    Trip issues → approve/reject
    Generate report → site Done

End-to-end journey map

ISSUE_REPORTED, PENDING_APPROVAL: excluded from product totals (contribution 0). APPROVED: uses snapshotted reportValue.

• On approve for +1 outcomes: per-trip equipment report runs (same logic as Generate Report for that day, that trip only).
• reportGenerated = true on the approved trip.
• Foreman can re-classify until backoffice approves or rejects.

1. 1Mobile Reports tab — pick start/end date.
2. 2Equipment list with trip counts for range.
3. 3Tap equipment → trip list with times, locations, quantity.
4. 4Web office uses dashboard + equipment report + site generate-report instead.

Econ runs automatic GPS verification after a trip reaches unloaded. The goal is to confirm that load and unload actions happened in the right place — either along a LINEAR alignment (chainage) or inside an AREA site zone polygon.

When verification runs

• Runs periodically for trips with status unloaded and not yet checked.
• Writes per-role results to the trip: loader/driver/unloader GPS checks plus an overall tripStatus label.
• Office sees the badges in Trip Details; mobile sees them as informational.

LINEAR projects (alignment / chainage)

LINEAR verification uses the survey parquet (from the project CSV) as the source of truth.

• Loader: loader GPS is compared to the selected LOADING product place (point + radius or chainage-derived point).
• Driver (unload): driver unloading GPS is compared to the survey point at the unloaded chainage.
• Unloader: unloader GPS is compared to the same survey point at the unloaded chainage.
• Typical radius: ~100m (configurable via place geofence where applicable).

AREA projects (closed polygon sites)

AREA verification combines product places (where loading happens) with the site polygon (where unloading must occur).

GPS capture points

Per-role outcomes

Verification statuses on trip

• unloaded — field work complete.
• needs checking — GPS rule mismatch; awaiting review.
• approved — passed automated or manual review; counts in compliance reports.
• tripStatus labels: verified, loader_red, driver_red, unloader_red, etc.

Spatial buffer (AREA polygons)

Polygon checks use a tolerance buffer (default 20m). DuckDB converts meters to degrees for WGS84 — otherwise far-away points could incorrectly pass.

Owner / marketplace (mobile & field web)

1. 1Home: browse equipment with filters.
2. 2Add Post: 5 steps — category, type, specs, up to 4 images, details (phone required).
3. 3Account: profile, my equipment, update location for nearby features.
4. 4Reports: usage and trips per machine (not the web Hearted placeholder).

• Phone + Telegram one-time code for web and mobile.
• Web: JWT in browser storage, company-scoped token, ~24h session guard with refresh.
• Mobile: long-lived session in device storage with refresh on 401.
• RBAC: dashboard areas (users, trip approve, reports) depend on company role keys.
• Multi-company: switch company on web header only.

Privacy policy

Can one person be loader on one project and driver on another?

Yes on server; mobile Work shows loader view if any assignment is loader (see role priority).

Where are favorites on mobile Reports tab?

Reports tab is equipment usage history, not favorites (internal name Hearted).

Who creates the site?

Geometry and products on web; starting site for field work is usually mobile foreman.

Can drivers work without loaders?

Only if office enabled Allow driver to create trip without loader on that site.

What is the difference between LINEAR and AREA?

LINEAR uses chainage along a centerline. AREA uses map polygons and GPS coordinates for places and site zones. See Project types section.

Do I need chainage on AREA projects?

No. Sites show area (m²) instead of chainage. Product places require latitude and longitude.

What happens if GPS verification fails?

Trip shows fail badges per role. Office reviews in Trip Details. Field should allow location permission and work inside the defined site zone or loading place.

Web

• /register does not submit — use User Management.
• Main /hearted is not office analytics.
• Projects status filter may be incomplete server-side.
• CSV export is current page only.

Mobile

• Forced update if store version ahead of app check.
• Role priority can confuse loader+driver users.
• Driver-create-trip offline needs one online session to cache equipment list.