This document is the browser-friendly companion to LANEAWARD_SETUP_LOG.md. The original log remains the chronological source of truth. This reference reorganizes that history into the current architecture, workflows, roles, operating rules, and design decisions so a new maintainer can understand the project without decoding the full timeline first.
LaneAward started in this log as a broader server and reporting effort, then narrowed into a workforce and production-floor system, and finally consolidated around two active frontends backed by one shared SQLite database: the contributor-facing Time On Tasks app and the desktop-first Operations Console. The current design intentionally keeps contributor workflow simple while allowing administration, tester onboarding, and later reporting to grow from the same shared data foundation.
The most important architectural decision preserved across the recent changes is the shared database model. Customer and order search, contributor task setup, user management, and future reporting all depend on the same SQLite file and shared API. That keeps the separate interfaces harmonized without duplicating business rules or reference data.
staging.timeontasks.laneaward.com serves Time On Tasks; staging.console.laneaward.com serves the combined admin-and-reports console shell. Both are also reachable via the legacy staging.laneaward.com host.https://staging.timeontasks.laneaward.com/ and https://staging.console.laneaward.com/ are the canonical staging subdomains. Legacy https://staging.laneaward.com/ remains active for backward compatibility. Legacy /workforce/ redirects to root.Owner can exist; all other roles can have multiple accounts.
The log begins with a broad LaneAward server build on the Ubuntu VM: Nginx on port 8081,
an initial SQLite database named engagement.db, migration scaffolding, and early customer,
order, invoice, and reporting prototypes.
On 2026-03-11 the project pivoted into a dedicated workforce tracking module under workforce_app. This introduced the contributor time-and-materials direction, role hierarchy, task states, and the first SQLite-backed workforce schema.
By 2026-03-24 the project consolidated into the current two-frontend model: the
Time On Tasks contributor app at root
and the Operations Console at
staging.console.laneaward.com, both backed by the same API and SQLite database.
Historical note: the old broad reporting prototype and several demo-only design phases remain important as context, but they are no longer the primary runtime model. The current system should be understood as a workforce platform with shared reference data and role-aware interfaces, not as a general CRM or quoting app.
| Frontend split | staging.timeontasks.laneaward.com = contributor app; staging.console.laneaward.com = console; /workforce/ = legacy route redirected to root; staging.laneaward.com = legacy alias (backward compat). |
|---|---|
| Backend | Python HTTP service in workforce_app/backend/server.py. |
| Shared database | workforce_app/data/workforce.db locally and /var/lib/laneaward-staging/workforce.db on AWS staging. |
| Reference data source | ProfitMaker DBF-family snapshots promoted into pm_database, then imported into SQLite. |
| Staging endpoint | https://staging.timeontasks.laneaward.com/ (Time On Tasks) and https://staging.console.laneaward.com/ (Console) are the canonical staging subdomains. https://staging.laneaward.com/ remains active as a legacy alias. |
| Public landing host | https://ai.laneaward.com/ is the public landing page for app links and launch access. |
| Shared route rule | Canonical API base is /api/; the backend still normalizes legacy /api/workforce/... paths during transition. |
| Environment parity rule | Development, AWS staging, and the public runtime should stay aligned on Python version, SQLite version, schema level, refreshed database content, backend code, frontend code, and service configuration so report and workflow behavior stays consistent. |
Mac workspace in /Users/donaldscott/Project-Code/laneaward/repo. Source of truth for app code, docs, scripts, and local SQLite refreshes.
AWS staging runtime at https://staging.timeontasks.laneaward.com/ and https://staging.console.laneaward.com/ with dedicated web roots (/var/www/laneaward-staging and /var/www/laneaward-staging-console), shared database, and backend service for public staging validation and reliability testing.
Public production server at ai.laneaward.com with matching ARM64 Ubuntu, Nginx, and SQLite assumptions. Its current role is the production landing page that links into the live app family.
Audience: manufacturing contributors first, with tightly scoped shop-floor workflow. This is the tablet and mobile-first app used to sign in by PIN, set up workload entries, manage queued and paused tasks, and track active session time.
Primary source: /Users/donaldscott/Project-Code/laneaward/repo/timeontasks
Audience: administrative and supervisory roles. This is the desktop-first shell used for user management, staging preparation, task-template assignment, and eventually reporting.
View Tasks opens the reusable task-list modal for Team Lead, Foreman, and Manufacturing Contributor accounts.Primary source: /Users/donaldscott/Project-Code/laneaward/repo/ops_console
The contributor app and the console intentionally use different frontend codebases while sharing one backend, one schema, and one SQLite file. This was a deliberate design choice so contributor workflow could stay clean and mobile-first while admin and reporting tools could evolve separately without forking business logic.
The role model evolved from the original OWNER / DEVELOPER / MANAGER / TEAM_LEAD / CONTRIBUTOR
hierarchy and now includes Senior Management and Foreman. The current console rules are the most relevant
operational version for handoff.
| Owner | Highest business authority. Only one owner account may exist. Sees active roles only, and intentionally does not see inactive users or the deactivate button in the console. The backend can still expose broad task visibility to this role, but the intended long-term surface for that visibility is the read-only reports experience rather than the contributor tablet workflow. |
|---|---|
| Developer | Same top-level system authority as Owner for management purposes. Sees inactive users and can see every console document tab, including Topology and Runbook. |
| Senior Management | Can create and deactivate all non-owner roles. Does not see Owner. Can use the console correction workflow on eligible accounts and sees User Guide, Reports, and Reference, but not Topology or Runbook. |
| Manager | Can create and deactivate Team Lead, Foreman, and Manufacturing Contributor users. Does not see Owner, Developer, or Senior Management. Can correct tracked time on eligible accounts and sees User Guide, Reports, and Reference. |
| Team Lead | Can create and deactivate Manufacturing Contributor users only. Does not see higher roles. Can correct tracked time on eligible contributor-style accounts within that scope, but sees only the User Guide tab in the console and does not see compensation data there. |
| Foreman | Shop-floor foreman role modeled after an industry quote-shop foreman. This is still a production contributor role, so it can create work, log time, and use contributor task templates in Time On Tasks. In the Operations Console it inherits Team Lead-level permissions, sees only the User Guide tab, and does not see compensation data there. |
| Manufacturing Contributor | Direct production-floor user. Uses Time On Tasks for workload setup, session timing, and task progression. |
Pay Type or Amount in the Accounts tab or selected-account workspace.User Guide.Reports is limited to Owner, Developer, Senior Management, and Manager.Topology and Runbook are limited to Owner and Developer.Reference is limited to Owner, Developer, Senior Management, and Manager.
The Reports tab now hosts two read-only report drafts behind one Report selector.
Contributor Task Activity summarizes contributor and team-lead workload without disturbing the
shared SQLite data. Order Profitability now combines invoice-backed orders and labor-backed
orders inside the selected period, then joins invoice-linked order data so the console can show invoice
number, taxes collected, shipping collected, tracked labor cost, current total cost, retail price, and
margin percentage in one place.
The order profitability draft currently uses these order-level fields from the shared SQLite data:
invoice_number, invoice_date, and billed_total as the current retail
price field. That retail value is imported from the ProfitMaker invoice amount when available, with a
fallback to the order line-total summary when the invoice amount comes through as zero. The same report also
uses taxes_collected, shipping_collected, and a reserved admin_cost
column that is not populated yet. Total cost currently reflects tracked hourly labor plus admin cost when it
exists. Salary-style compensation remains visible as stored account data, but salary labor totals are not yet
derived until a formal conversion rule is approved. Changing Period or either
Date Range calendar now refreshes the report data automatically, while the
Refresh button remains as a manual retry control.
Time On Tasks should be treated as an operational contributor tool, not a universal workforce dashboard. Manufacturing Contributors, Foremen, and Team Leads are the intended daily users. Owner and Senior Management may still benefit from broad task visibility in the shared backend, but that visibility is being preserved primarily so the future reports view can show the full picture of open work without re-implementing task logic somewhere else.
When a contributor forgets to start, pause, or stop on time, the correction path is intentionally human-first: the contributor reports it to a Team Lead, Foreman, or Manager, and leadership applies the fix in the Operations Console with a required reason and an audit trail.
This project deliberately uses one shared SQLite database for all active interfaces. That decision supports a harmonious relationship between contributor workflow, user management, and future reporting.
The import path is not trying to clone the full source system. Its current high-value purpose is to keep contributor-facing search useful by importing current customers, order numbers, and ranked order descriptions.
customer_account rows.sales_order rows.LNITM.DBF so hover/detail text uses real product descriptions.asidta_file_* snapshot is auto-detected if no folder is passed.Copy of ... are ignored.Key scripts: refresh_workforce_reference_snapshot.sh, refresh_workforce_reference_data.sh, import_profitmaker_reference.py
A user_task_template table was added so contributor users can have reusable task descriptions
associated with them. These are created and managed from the console and then appear as fuzzy-search options
inside Workload Setup in Time On Tasks.
A default standard set was seeded on 2026-03-24, including Order Intake,
Artwork Preparation, Assembly, Packaging, and
Shipping, with room for more contributor-specific templates over time.
Time On Tasks files publish to /var/www/laneaward-staging/ and console files publish to /var/www/laneaward-staging-console/ on the AWS server.
The VM service is laneaward-workforce-api.service. Nginx fronts the static apps and proxies API requests to the Python service.
Staged databases are promoted with the VM cutover script, which validates, backs up, swaps, restarts, and verifies the service.
customer_account = 3245 and sales_order = 4912./workforce/ is no longer the main contributor route and now redirects to root.502 Bad Gateway responses observed during backend restarts have been documented as restart-window artifacts rather than persistent failure.datalist were resolved by replacing them with custom lookup menus.001.The project intentionally treats this as a web app rather than a static mock. A web-app manifest, Home Screen icons, Apple metadata, and iPad standalone refinements were added so tablet install behavior and coarse-pointer layouts remain workable. Offline support and service-worker behavior were explicitly not completed in the current pass.
The original setup log also documents the early reporting prototype, migration experiments, and demo-heavy Time On Tasks design evolution. That history still matters for context, but it should not be confused with the current runtime architecture described here.
Do not split the contributor app, console, and reporting logic onto separate databases unless there is a compelling operational reason. The project is cleaner because user records, task templates, and reference search all live in one place.
Update both the chronological log and the browser-facing docs whenever routes, roles, scripts, or workflows change. The handoff burden grows quickly if changes land only in chat or in code comments.
Use the VM cutover and status scripts, refresh reference data before testing, and validate the actual staged app behavior on Safari and tablet-class devices before treating a change as ready.
Recommended next documentation step: add a deeper table of contents and, if desired, split this reference into sub-documents for architecture, UI specification, and operational procedures. For now, this page is intended to be the first-stop overview for anyone inheriting the project.