Sample scope of work: a customer order-status portal.

Larkfield Industrial Supply (“the Client”) is a mid-sized distributor of industrial parts, selling to business customers and dealers, many of them with several ship-to locations. Customers who want to know where an order is call or email the Client's customer service team, who look the order up in the Client's order system and then on the carrier's website, and reply by phone or email. The same questions reach the sales representatives, who do the same lookups. Nobody outside the Client can check an order themselves.

This project delivers a web portal where people at each customer or dealer account sign in and see the status of their own account's orders and shipments, read from the Client's order system without changing it, and where the Client's sales staff see the same view across every account. The goals are:

• Customer users see the status of their account's orders and shipments, with carrier tracking, at any time, without calling or emailing the Client.
• Each person sees only what their account and role allow. Which account and ship-to locations a request may reach is decided on the server from the signed-in session, never from anything the browser sends.
• The Client's sales staff see every account in the same portal, signed in with their existing staff accounts.
• The order system is read, never written. Customer traffic doesn't reach it directly, and the Client's staff keep working in it as they do today.
• The Client's IT team can run, change and extend the system after handover without us.

• Order list and search. Signed-in users see the orders they are allowed to see, newest first, with the order number, their own purchase order number, ship-to location, date received and status. Search by order number, purchase order number, item or tracking number, and filters by status, ship-to location and date.
• Order detail. Order lines with quantities ordered and shipped, holds with the reason the Client chooses to show customers, and each shipment with its carrier, tracking number and milestones. Status is derived from the shipments, as recorded in the order system and reported by the carrier.
• Carrier tracking. Every tracking number links to the carrier's own tracking page, from a link template per carrier that administrators maintain. For the carriers named in phase 1, milestone updates (picked up, in transit, out for delivery, delivered) are read from each carrier's tracking service through the Client's own carrier accounts.
• Roles. Three roles: customer user (their account's orders, limited to the ship-to locations they are assigned), customer admin (every order for their account, and the people who can sign in for it) and internal sales (every account, with the account and ship-to location on each order). A Client administrator role sets up accounts and their first customer admin.
• Account-scoped access, enforced on the server. Every API request is filtered by the account and ship-to locations of the signed-in session. An order outside that scope gets exactly the same response as an order that doesn't exist, so the portal never confirms that it does.
• Customer sign-in. A customer identity service (Amazon Cognito, in the Client's AWS account) for customer and dealer users: sign-in by invitation only, multi-factor authentication, password reset, and each user's account, role and ship-to locations stored with their sign-in. Customer admins invite and deactivate people for their own account and set each person's ship-to locations.
• Staff sign-in. Single sign-on for the Client's staff through the Client's existing staff identity provider (over OpenID Connect), with the internal sales and administrator roles taken from groups the Client's IT team manages.
• Order data. A read-only connection to the order system, through named database views, a read replica or the order system's own API, chosen with the Client's IT team in phase 1. A sync copies the order, line and shipment fields in the data dictionary into the portal's own read store at an interval agreed in phase 1, and every screen shows when the data was last updated. Cost prices, margins and internal notes are not copied.
• Access log. Who opened which order, and every search, recorded per account with the user and time, searchable by Client administrators for security reviews and customer questions.
• Infrastructure and delivery. Infrastructure defined as code (AWS CDK), deployed through a CI/CD pipeline (GitHub Actions) into separate test and production environments.
• Monitoring. Alarms for application errors, a sync that fails or falls behind, carrier tracking errors, invitation emails that fail to send and unusual sign-in failures.
• Documentation and handover. Runbooks, a data dictionary, architecture and security documentation, and knowledge-transfer sessions, as set out in section 11.

• Placing, changing or cancelling orders, reorders and quote requests. The portal shows status only; orders keep reaching the Client the way they do today.
• Payments, invoices, statements and credit information.
• Returns and return authorizations.
• Any write to the order system, including customer, contact and ship-to records. Account and ship-to data is maintained in the order system, as today, and read by the portal.
• Prices, price lists and product availability.
• Email or text notifications of order and shipment changes. A candidate for a later phase, quoted separately.
• Milestone updates for carriers not named in phase 1. Their tracking numbers still link to the carrier's own tracking page.
• Mobile apps and offline use.
• Integration with any other business system.
• Hardware, network changes and software licenses. We specify what is needed; the Client's teams make the changes and hold the licenses and accounts.
• Support, maintenance or new features after handover. Available as separately quoted work.

• The Client provides the access in section 4 before the build phase starts. If access arrives later, the schedule moves with it; the price changes only if the scope does.
• The order system can provide read-only access by at least one of the three routes in section 4, and the Client's IT team and order system administrator agree the route in phase 1. Any change to the order system itself is the Client's.
• Account and ship-to data in the order system is correct, and each order carries its account and ship-to location. Where it isn't, the Client corrects it in the order system; the portal's read store is refreshed from the order system and never edited in the portal.
• Customer service agrees in phase 1 which fields customers may see, including which hold reasons are shown and how.
• The Client holds an account with each carrier named in phase 1 that allows tracking lookups through the carrier's API.
• The Client sets up the first customer admin for each account through the administrator screen, or supplies a list for a one-time import using the template in the data dictionary.
• The Client names one product owner who can answer questions and accept deliverables, and one contact each in customer service, sales and IT security.
• The test environment uses test accounts and a copy of the order views with test data. No production customer data is used in test.
• Hosting, license and other third-party costs are billed to the Client's own accounts.

• Source code for the portal and the sync, with automated tests, in the Client's repositories.
• Automated access tests for every role, including the cross-account tests in AC3, run by the pipeline on every change.
• Database migration scripts for the portal's read store, run by the pipeline, so the schema is versioned with the code.
• Infrastructure as code (AWS CDK) for the test and production environments.
• A CI/CD pipeline (GitHub Actions) that tests, builds and deploys every change, authenticating to AWS with OIDC so no AWS keys are stored.
• An architecture and data-flow document for the Client's security review, including every network rule with its source, destination, port and purpose.
• A data dictionary covering every field the portal reads from the order system and from carriers, which roles see it, and the first-admin import template.
• Runbooks: deploy, roll back, rotate credentials, set up an account and its first customer admin, deactivate a user, add a carrier link template, rerun or pause the sync, look up the access log, and respond to each alert.
• Knowledge-transfer sessions, listed in section 11.

The system is accepted when every criterion below passes in production. Each one is checked together with the Client's product owner.

Sync interval, the carriers with milestone updates and the fields customers may see: stated here in the real document, agreed with the Client in phase 1.

Acceptance is judged against these criteria only. Anything not listed here is not a reason to withhold acceptance, and is not in the price; it can be raised as a change (section 9).

Work runs in five phases. Each phase ends on a written exit criterion, and working software is reviewed with the Client in the test environment throughout phases 2 and 3.

Milestone dates: stated here in the real document, agreed with the Client before work starts.

1. Either party raises a change in writing: what is needed and why.
2. We reply in writing with its effect on scope, price and schedule, or confirm that it has none.
3. Nothing changes until the Client's product owner approves it in writing. Approved changes are added to this document as numbered amendments.
4. A change that isn't approved isn't built, and the original scope and price stand.

Until the system is accepted, fixing something that fails an acceptance criterion in section 7 is not a change. It is covered by the fixed price.

The following are prepared for the Client's IT and security teams during phase 1, before the portal connects to any Client system or any customer is invited:

• A data-flow diagram showing every connection and its direction. The only connection into the Client's network is the sync's read-only connection to the order system (over the site-to-site VPN, unless the order system's API is chosen), on a single network rule the Client's network team controls. Customer requests never reach the order system.
• A network rule list: source, destination, port, protocol and purpose for each rule.
• Order system access: one read-only login or read-only API credential for the sync, named and documented. No shared or personal credentials in the running system.
• Access checked on the server for every screen and API call, from the signed-in session: the user's role, account and ship-to locations. Order numbers and other identifiers in a request are never trusted to decide scope.
• The cross-account tests in AC3 kept in the pipeline, so a change that widens what a customer can see fails before it reaches production.
• Customer sign-in by invitation only, with multi-factor authentication, lockout after repeated failures and password reset, using the customer identity service's own controls as of 2026. Staff sign in only through the Client's own identity provider, so its existing multi-factor and conditional access policies apply.
• Secrets, including carrier API credentials, kept in AWS Secrets Manager, never in code, configuration files, tickets or email.
• Encryption in transit on every connection, and at rest for the read store, the access log and backups.
• Logging of sign-ins, deployments, sync runs and application errors to CloudWatch, and the access log, retained according to the Client's policy.
• Dependency scanning in the pipeline, with findings reported to the Client before each release.
• Data classification: customer and dealer names, ship-to addresses, order and purchase order numbers, items and quantities, tracking numbers, and the names and work email addresses of portal users. Cost prices, margins, internal notes and payment data are not copied into the portal.
• Answers to the Client's security questionnaire, and an architecture walkthrough for the security team.

Handover is part of the fixed price. It is complete when the Client's team has deployed a change, rolled it back and responded to a test alert themselves, using only the documentation. It includes:

• Everything in section 6, confirmed in the Client's repositories and accounts.
• Knowledge-transfer sessions: architecture walkthrough, code tour, supervised deployment, rollback and recovery, setting up an account and its first customer admin, running the cross-account tests, and a test incident.
• Access and credentials: every account confirmed as the Client's, secrets rotated, and our access removed or reduced to whatever support is agreed.

The full contents of a handover package are shown in the sample handover package. It was written for a different invented project, a plant-floor dashboard, but it is organized the same way for a portal like this one.

• The Client owns all code, infrastructure definitions, documentation and data produced under this scope. There is no license fee and no lock-in.
• Everything is built in the Client's repositories and AWS account. Nothing runs in accounts we control.
• Open-source components remain under their own licenses, which are listed in each repository.
• Confidentiality is covered by the NDA signed before this engagement.

Fixed price: stated here in the real document.

The fixed price covers everything in sections 2, 6, 7 and 11: design, build, testing, deployment to test and production, documentation, knowledge transfer, handover, and fixing anything that fails an acceptance criterion before acceptance.

It does not cover:

• Anything listed as out of scope in section 3.
• Approved changes under section 9, each priced before it starts.
• Hosting, software licenses and other third-party costs, billed directly to the Client's accounts.
• Support, maintenance or new features after handover, quoted separately if wanted.

Invoicing schedule and payment terms: stated here in the real document.

Nothing is built until this scope is accepted. Signing below accepts the scope and the fixed price stated in section 13.