SmartCrew Mobile App Documentation

This document describes the SmartCrew mobile application, the full screen catalog, and the core operational flows used in production.

1. Product Overview

SmartCrew Mobile is used by field employees and supervisors to track time, document work, submit reports, and coordinate with the office. The app connects directly to the SmartCrew Admin Console for approvals and reporting.

Primary user roles

• Crew member: clock in/out, submit reports, post updates, chat with crew.
• Supervisor: all crew features plus review and approval controls.
• Mobile admin: lightweight access to admin modules from mobile.

Main navigation

The main dashboard is a tab container with access to Home, Summary, Posts, Projects, Logs, and Profile. Some workspaces also show the Supervisor or Admin dashboards.

2. Screen Catalog (All Pages)

2.1 Authentication and Onboarding

• Splash screen: loads configuration and checks auth state.
• Login screen: phone-based login and OTP verification.
• Onboarding screen: first-time setup, permissions, and name confirmation.
• Choose company screen: select or switch active workspace.

2.2 Core Tabs and Daily Work

• Main dashboard screen (tab container): holds the primary tabs.
• Home screen: daily time tracking, clock in/out, and active log status.
• Summary screen: weekly totals, day status, and summary submission.
• Posts screen: company feed and post details.
• Crew chat details screen: threaded crew messages and attachments.

2.3 Projects and Documents

• Projects list screen: list of active and archived projects.
• Jobsite document screen: project documents and related files.
• PDF viewer screen: view project PDFs in-app.
• Project map screen: jobsite location and navigation helpers.

2.4 Logs, Reports, and Scheduling

• Logs screen: report categories, history, and submission entry point.
• Service queue screen: open service requests and assignments.
• Documents category screen: grouped document/report categories.
• Report history screen (modal): list of submitted reports.
• Report history detail screen (modal): report detail with status and files.
• Incident report screen: safety incidents with photos and notes.
• Service request report screen: request service from the field.
• Add service report screen: log completed service work.
• Add service from request screen: convert request into a service record.
• Hauling report screen: log haul details and quantities.
• Inspection report screen: equipment or site inspection checklist.
• Time off report screen: request PTO or day off.
• Material field usage report screen: log on-site material usage.
• Material shopping report screen: request or log purchases.
• Scheduling calendar screen: view scheduled work and service items.

2.5 Profile and Requests

• Profile screen: user details, permissions, and settings.
• My requests screen: time off and service requests history.
• Time off calendar screen: calendar view of time off.

2.6 Supervisor and Mobile Admin

• Supervisor dashboard screen: supervisor shortcuts and approvals.
• Admin dashboard screen (mobile admin): lightweight admin entry.
• Admin dashboard loading screen: data bootstrap for admin view.
• Admin overview screen: high-level admin summary.
• Admin projects screen: manage projects on mobile.
• Admin labor screen: view labor summaries and logs.
• Admin equipment screen: equipment lists and status.
• Admin materials screen: materials overview and activity.
• Admin time cards screen: time card review on mobile.
• Admin customers screen: customer list and details.
• Admin vendors screen: vendor list and details.

2.7 Modals, Dialogs, and Bottom Sheets

• Crew message modal: compose and send crew messages.
• Edit profile modal: update personal details.
• Edit time off modal: edit pending time off requests.
• Manual log modal: create or edit manual logs.
• Manual clock out modal: override clock out time.
• Timecard accurate modal: confirm time card accuracy.
• Manual task modal: add manual task entry.
• Additional notes modal: add comments and notes.
• Project selection modal: choose project for actions.
• Edit working time modal: adjust log start/end time.
• Edit project tasks modal: edit tasks linked to a log.
• Request day off modal: create a time off request.
• Take break modal: start or end a break.
• Field note modal: capture field notes and photos.
• Submit summary modal: submit daily summary.
• Edit log switch modal: switch active log.
• Task edit modal: edit a specific task entry.
• Project edit modal: edit project selection in a log.
• Equipment time entry modal: log equipment hours or miles.
• Clock in modal: select project/task and start clock.
• Time picker modal: select time values.
• Simple checkout questions modal: quick end-of-day questions.
• App dialog (generic confirm): shared confirm dialog.
• Confirm delete dialog (admin): confirm deletions in admin mode.
• Image preview dialog: preview images and attachments.
• Admin image preview dialog: admin version with controls.
• Stop active log dialog (switch workspace): force stop before switch.
• Remove field note dialog: confirm note deletion.
• Cancel request dialog (report history): cancel pending report.
• Delete account confirmation dialog: confirm account deletion.
• Deleting account progress dialog: progress indicator.
• Delete time off request dialog: delete a pending request.
• Delete manual task dialog (manual logs): delete manual task entry.
• Delete manual task dialog (task edit): delete task from edit screen.
• QuickBooks sync result dialog: show sync summary.
• QuickBooks sync error dialog: show sync failure details.
• Crew chat message actions dialog: reply, copy, or delete actions.
• Crew chat image preview dialog: preview chat images.
• Switch workspace bottom sheet: switch company/workspace.
• Reactions list bottom sheet: view message reactions.
• Hours/miles type picker bottom sheet: choose unit for equipment time.

3. Core Feature Areas

3.1 Authentication and Workspace

• Phone-based login with OTP verification.
• Workspace selection and switching.
• Role-based access controls for supervisor/admin modes.

3.2 Home and Time Tracking

• Clock in with project, task, location, equipment, and materials.
• Clock out with validation and end-time confirmation.
• Break tracking with validation.
• Manual logs for corrections and backdated entries.
• Daily timeline with task history and field notes.
• Weekly summary totals and day status.

3.3 Projects

• Project list with status and quick actions.
• Jobsite details with map and directions.
• Project documents and field notes.
• Materials overview per project.

3.4 Logs and Reports

• Report categories and history list.
• Incident, service, hauling, inspection, time off, and materials reports.
• Service queue and calendar scheduling.
• Report detail view with status and attachments.

3.5 Posts and Crew Communication

• Post feed with company updates.
• Crew chat with text, image, audio, and file messages.
• Reactions and replies with threading.

3.6 Profile

• Profile details and role visibility.
• Permission hints and access guidance.
• Settings and logout.

4. Notifications and Feedback

SmartCrew Mobile uses toasts and snackbars for user feedback, including:

• Auth and onboarding feedback (login, permissions, workspace selection).
• Time tracking validations (clock in/out, break rules, manual logs).
• Report submission and status updates.
• Admin actions on mobile (save/delete results).
• Media and file upload errors.
• Crew chat permissions and message actions.

5. Key Operational Flows

5.1 Clock In and Clock Out

1. Open Home and select the current day.
2. Validate location permissions and active workspace.
3. Select project and task, then start clock in.
4. Optionally select equipment and materials.
5. Add field notes or photos during work.
6. Clock out with end time validation.
7. Confirm summary and sync to admin.

5.2 Report Submission and Review

1. Open Logs and choose a report type.
2. Complete required fields and attach files.
3. Submit report (status: pending).
4. Admin reviews in the console and updates status.
5. Status syncs back to mobile history.

6. Release Test Suite (Beta to Prod Gate)

6.1 Mobile App Automated Suite

• Auth: login, onboarding, workspace selection.
• Home: clock in/out, breaks, task changes, manual logs.
• Summary: weekly totals and day status.
• Projects: list, map, and documents.
• Reports: submit all report types with attachments.
• Report history: status updates after admin actions.
• Posts and chat: feed, chat messages, media uploads.
• Profile: permissions display and logout.