Transloads Application Orientation

transloads.co is a React App project that layers AWS Amplify authentication and GraphQL APIs on top of multiple role-specific react-admin experiences (admin, yard manager, crew, carrier, customer). This guide combines high-level orientation with deeper implementation details so a new teammate can quickly understand how the pieces fit together.

Overall Architecture & Routing

src/index.js configures Amplify with the generated aws-exports settings, wraps the app in a shared UserProvider, and mounts the main <App> component. App.js listens for Amplify Hub auth events, routes unauthenticated users into a custom authenticator, and, once a user is resolved, normalizes their reload-yard and permission data before choosing the correct portal (admin, manager, crew, carrier, customer, or the registration flow). It stores the resolved user on window.appUser, manages persona selection via localStorage, and updates lightweight profile records back through GraphQL mutations when Cognito IDs change.

Routing is persona-driven: each audience has its own module under src/ (adminApp, managerApp, crewApp, carrierApp, customerApp, plus registration). Shared route definitions in src/routes.js map URLs to crew workflows (audits, shipment processing, maps), management tools (scheduling, track management), and manager reports, with authorization gates for protected screens such as the Zapier API key panel.

react-admin Shells & Persona Modules

Each persona exports a top-level <Admin> instance from React-admin (for example, AdminApp, ManagerApp, CrewApp, CarrierApp, CustomerApp). These wrappers plug in the shared Amplify-aware data provider, persona dashboards/layouts, and the set of <Resource> declarations that enable React-admin routing, CRUD views, and navigation for that audience. Resource definitions in the *App.js files determine which domains appear in the left navigation, which components handle the Create/Edit/Show/List lifecycle, and how permissions influence visibility.

Every <Resource> points to components housed inside resources/<domain> directories within the persona folder. For instance, the manager experience wires inboundShipments to InboundList, InboundCreate, InboundEdit, and InboundShow, all located under src/managerApp/resources/inboundShipments/. The admin app similarly registers commodities, registrations, logs, help pages, and announcements, each backed by sibling files under src/adminApp/resources/<resource>/. This convention makes it straightforward to locate UI, validation, and action logic for any resource that appears in the sidebar.

Create, Edit, Show & List Patterns

Resource folders encapsulate the entire CRUD lifecycle for their domain. List views typically use <List> with <Datagrid>, while edit and create flows wrap React-admin’s <Edit> or <Create> around a <SimpleForm> and custom toolbars. Show views rely on <Show> or bespoke layouts for read-only inspection. React-admin automatically wires these components to the correct routes (e.g., /, //create, //:id) based on the <Resource> configuration.

• Custom Toolbars: Toolbars frequently override the default <Toolbar> to supply tailored <SaveButton> instances, additional action buttons, or confirmation dialogs before submission.
• Transform: The transform handler reshapes form data before it reaches the data provider. Examples include fanning out inventory items, scrubbing local-only fields, and enforcing exception rules prior to saving.
• onSuccess: After the primary mutation resolves, onSuccess handlers orchestrate follow-up automation—chaining additional REST calls, enqueueing background jobs, or displaying toast notifications—while keeping the user in context.
• onFailure: Errors funnel through onFailure to ensure consistent logging via helpers like logError and to present user-friendly toasts when Amplify rejects a mutation or a REST bridge fails.

Many save toolbars also override handleSubmitWithRedirect to insert confirmation dialogs, validation passes, or multi-step workflows before invoking the data provider, demonstrating how React-admin hooks expose granular control over each CRUD phase.

Data Provider & GraphQL Layer

src/dataProvider/dataProvider.js wraps react-admin-amplify’s buildDataProvider, merging generated GraphQL queries and mutations with extensive custom operations (accounts, inventory, shipments, invoices, reload yards, and users). By exporting a shared myDataProvider, every persona leverages the same abstraction for GraphQL-backed CRUD while still enabling future overrides of methods like getList or getOne. Most forms delegate persistence to this provider, reducing the need to fire GraphQL requests manually inside components.

GraphQL documents are organized by domain under src/graphql/, mirroring backend concepts such as accounts, carriers, inventory, inbound/outbound shipments, and audit/reporting utilities. Utility helpers in src/utils/appUtils.js centralize error logging, reload yard lookups, Stripe subscription retrieval, and derived maps that are stored on window.appUser for downstream components.

REST Integrations: transREST & zapierREST

Complex orchestration and third-party automation rely on Amplify-hosted REST APIs:

• transREST: The primary in-house REST gateway handles bulk invoice updates, inbound/outbound shipment orchestration, document generation, and transactional email. React-admin forms frequently call these endpoints from onSuccess handlers to synchronize side effects after a GraphQL mutation succeeds.
• zapierREST: Automation endpoints manage Zapier API keys and trigger zaps (e.g., newEmail, invoiceUpdated) when certain workflows complete. Components and utilities conditionally invoke these hooks depending on which zaps are active for a reload yard.

These REST integrations complement the GraphQL schema by covering cross-resource side effects and third-party connectivity that would otherwise be cumbersome to express in GraphQL alone.

Shared Utilities & Components

Common UI pieces live in src/components, while reusable hooks and helpers (toast notifications, sticky state, responsive typography, date utilities, etc.) live in src/utils/. Persona shells leverage these helpers to keep behavior consistent. The user context centralizes the active user, exposes authorization helpers, and persists the active reload yard into localStorage for subsequent sessions.

Testing & Local Development

The tests/ directory mirrors runtime apps with dedicated suites for the authenticated shell, crew flows, and manager experiences, making it easy to focus on a specific persona when adding coverage. Standard CRA scripts (npm start, npm test, npm run build) are available, and the README documents Amplify maintenance tasks such as regenerating GraphQL artifacts or resetting cloud environments—critical knowledge when working with the AWS backend.

Suggested Next Steps for Newcomers

• Run the app locally: Use CRA scripts to become familiar with the role-based portals, navigation patterns, and authorization flows.
• Explore the GraphQL layer: Study documents in src/graphql/ alongside the custom data provider to understand how React-admin resources map to Amplify APIs.
• Review environment management: Reference the README for Amplify troubleshooting steps so you can regenerate schema artifacts or recover from backend drift.
• Deep-dive by persona: Walk through a specific subdirectory and its associated tests to see how screens, resources, hooks, and REST integrations collaborate.
• inspect react-admin documentation at https://marmelab.com/react-admin/doc/4.16/Tutorial.html

With these patterns in mind, a newcomer can trace how menu entries map to resource components, how forms flow through React-admin’s hooks, and how the app balances GraphQL with Amplify-hosted REST endpoints to deliver the full operations experience.