00 — Business Overview

One-page entry point. Read this first; deeper docs link from here.

What this system is

The Asset Tracking System is a bilingual (English / Arabic) web application that an organization uses to register, track, transfer, audit, maintain, and check out its physical assets. Examples of "assets" in the system: laptops, vehicles, lab equipment, tools, office furniture — anything with a barcode or QR sticker that someone in the organization is responsible for.

Three things make it stand out from a basic spreadsheet:

  1. Every asset has a story. When an asset's location, organization, custodian, or status changes, the system writes a permanent history row. Auditors and managers can answer "who had this laptop in March?" without piecing together memos.
  2. Every operation is gated by permission. Roles (Transfer Approver, Auditor, Custodian, …) decide what each user can see and do. A field auditor can submit results but can't approve transfers; a transfer requester can ask but can't approve themselves.
  3. The mobile auditor walks the floor. A separate mobile-friendly UI lets field staff scan QR stickers (or type the asset code) on a phone, capture photos as evidence, and submit results — even with intermittent connectivity, since progress is saved on the server as a draft.

Who is it for

Audience What they do with it
Asset administrators (admins) Maintain the master data (organizations, locations, classifications, vendors, manufacturers, asset statuses). Onboard users and assign roles. Configure email, languages, hierarchy depth, notification templates.
Operations staff (field) Issue assets to people (check-out), receive them back (check-in), file maintenance requests, complete work orders, transfer assets between locations or organizations.
Auditors (field) Walk a defined scope, scan or type each asset's code, record what they found, attach photos, submit results from a phone or tablet.
Reviewers / managers Approve or reject transfer requests. Review audit submissions line-by-line. Approve or reject maintenance requests.
Executives / analysts Read reports — current inventory, audit history, maintenance history, transfer history, check-out activity — filtered to whatever cut they need.

A single person can wear several of these hats. Most installations have a small admin team (1–3 people) plus dozens to hundreds of operations / audit / management users.

Top-level capabilities

flowchart LR
  subgraph "Master Data"
    MD[Organizations<br/>Locations<br/>Classifications<br/>Vendors<br/>Manufacturers]
  end
  subgraph "Operational core"
    A[Assets &<br/>their history]
    AU[Audits]
    XF[Transfers]
    CO[Check-outs]
    MX[Maintenance]
  end
  subgraph "Outputs"
    NT[Notifications<br/>in-app + email]
    R[Reports<br/>XLSX + PDF]
    DOC[Document<br/>attachments]
  end

  MD --> A
  A --> AU
  A --> XF
  A --> CO
  A --> MX
  AU --> NT
  XF --> NT
  MX --> NT
  AU --> R
  XF --> R
  CO --> R
  MX --> R
  A --> R
  A --> DOC
  AU --> DOC
Capability What it does for the business Detail
Asset registry Single source of truth for every physical asset, its current location, organization, classification, status, and custodian 04 §Assets
Audit lifecycle Plan a count, assign auditors, scan / record in the field, review the results, write back the corrected reality 03 §Audit
Asset transfers Move an asset (or many) from one place / org to another with an approval gate and a paper trail 03 §Transfers
Check-out / check-in Track who has what, when it's due back, and the condition on return 03 §Check-out
Maintenance Plan recurring service, accept user-filed requests, schedule and complete work orders, track cost 03 §Maintenance
Documents Attach invoices, warranties, photos, certificates to any asset, transfer, work order, or audit line 04 §Documents
Notifications In-app bell + email alerts on the events users care about (transfer awaiting your approval, your audit was reviewed, …) 04 §Notifications
Reports Six pre-built filterable reports — inventory, audit history, audit results, transfer history, maintenance history, check-out activity — all exportable to Excel or PDF 05 §Reports
Bilingual UX Every screen and every data field can be primary + secondary language. Active users get RTL when their language is RTL. 06 §Localization

Two ways into the system

flowchart LR
  subgraph "Desktop shell"
    DT[Login → Dashboard]
    DT --> DA[Master Data &<br/>Asset CRUD]
    DT --> DA2[Audits, Transfers,<br/>Maintenance, Reports]
    DT --> DA3[Settings &<br/>Administration]
  end
  subgraph "Mobile shell"
    MO[Login → My Audits]
    MO --> MA[Open assignment]
    MA --> MC[Camera scan or<br/>typed code entry]
    MC --> MS[Submit results]
  end
  USER([User]) --> DT
  USER --> MO
  • Desktop shell — full administrative + operational interface. Side navigation, top bar with notifications, search, language picker, theme picker, user menu. Used by everyone except pure field auditors.
  • Mobile shell — stripped down to one job: do my assigned audits. No side nav, no admin pages. The user logs in, sees their list of assignments, opens one, and either scans QR codes with the camera or types codes manually. Photos and notes attach per asset.

The "Mobile Auditor" user type exists specifically so field staff land in the mobile shell automatically and can't accidentally drift into admin pages. Every other user lands in the desktop shell.

Glossary

Plain-English definitions for terms that show up across the docs.

Term What it means
Asset A physical thing the organization tracks — a laptop, printer, vehicle, etc. Each asset has a unique system-generated code (e.g. 000123CLS-LAPTOP) printed on the QR sticker.
Organization The org-chart unit an asset belongs to (department, branch, cost center). Organizations are hierarchical — e.g. Company → IT Department → Help Desk Team.
Location The physical place an asset sits — also hierarchical (Site → Building → Floor → Room). Configurable depth and labels.
Classification The category an asset falls into (Computers → Laptops → Premium Laptops). Drives whether a serial number is required, default useful life, and the asset's code suffix.
Vendor Company the asset was purchased from.
Manufacturer Company that built the asset.
Custodian The user currently holding the asset (e.g., after check-out).
Audit Plan A defined scope — "audit every laptop in Building A this quarter". Has a status (Draft → Scheduled → InProgress → Completed).
Audit Assignment One auditor's piece of work for a plan. Snapshots which assets are expected so reality can be compared to expectation.
Audit Result What the auditor submitted. Each line is one asset with an outcome (Found, NotFound, LocationMismatch, OrganizationMismatch, Extra).
Audit Review A reviewer's per-line decision: Approve (write the auditor's observation back to the asset record), Reject (ignore — asset record stays as it was), or Modify (apply a different correction).
Transfer Moving an asset (or many) from one location or organization to another. Goes Draft → Submitted → Approved → InTransit → Completed (or Rejected / Cancelled).
Check-out / Check-in Issuing an asset to a person and getting it back. Tracks expected return date and overdue items.
Maintenance Plan Recurring service schedule (monthly inspection of every fire extinguisher, etc.). Generates Work Orders on demand.
Maintenance Request A user-filed report — "the printer in room 12 is jammed". Reviewed and either promoted to a Work Order or rejected.
Work Order The actual job. Has type, priority, assignee (user or vendor), schedule, costs, completion notes.
Document An uploaded file (photo, invoice, warranty PDF, …) linked to an asset, transfer, work order, audit-result line, etc.
Notification template A bilingual subject + body with {{ merge.fields }} placeholders the system fills in (e.g., transfer.code). Admins edit them at /settings/notification-templates.
Notification preference Per-user toggle for whether to receive a given notification on a given channel (In-app or Email).
Permission A specific action a user is allowed to take — e.g., asset.create, audit-result.review. Roles bundle permissions; users get permissions through their roles plus per-user overrides.
Role A bundle of permissions with a human-readable name (Transfer Approver, Auditor, …). A user can have multiple roles.
Hierarchy config Admin-set per-tenant configuration for how deep Locations / Organizations / Classifications go and what each level is called (Site / Building / Floor / Room, vs Country / City / Branch, etc.).
Bilingual field A pair of name+description fields — primary and secondary — so the same record can carry both languages. The user's UI language picks which one shows.
Primary / Secondary language An admin setting that says which language is in the "Primary" columns and which is in "Secondary" — usually Primary = English, Secondary = Arabic, but configurable.

Reading guide — how to use these docs

If you want to… Read
Understand who does what 01 — User Roles
Look up which role can do which action 02 — Permissions Matrix
Trace an end-to-end workflow (e.g., a transfer) 03 — Business Processes
Learn what each screen looks like and what users do on it 04 — Features by Module
Understand what reports exist and who they help 05 — Reporting & Insights
Set up bilingual content / understand RTL behavior 06 — Localization & RTL

For the technical (code-level) view of the system, see the parallel docs/ folder at the repo root.

What's not in this system

To set expectations: capabilities the system does not provide today.

  • No real-time collaboration. If two reviewers open the same audit result at the same time, the second save can fail with a "the record was modified by another user" message.
  • No automated cleanup. Old request logs, login attempts, etc. accumulate forever unless an operator schedules a database purge.
  • No mobile native apps. The "mobile shell" is a responsive web UI; iOS/Android stores have no listing.
  • No barcode scanning hardware integration. Identification is QR (camera) or manual code entry only.
  • No cost accounting export. Work order costs are captured but there's no general-ledger / ERP integration.
  • No SSO yet. Login uses email + password; admins manage users directly.