System Requirements Document for mail-storage-deliveries

1. Introduction

mail-storage-deliveries is a mail and package storage service for deliveries that people are not home to receive. The product exists so that a delivery can be received and held at a storage location until the person it belongs to is able to collect it, instead of being returned, abandoned, or left on a doorstep.

The product serves a two-sided audience. On one side are individual residents who receive their own mail and packages and need somewhere safe for those deliveries to wait. On the other side are delivery-service businesses — couriers, locker services, and similar operators — that manage deliveries for many people and need to coordinate where each delivery is held.

Two things about this product are deliberately not fixed, and both are treated as variable options throughout this document:

• The main user is variable. The product supports both an individual resident receiving their own mail and a business such as a courier or locker service managing deliveries for many people. Neither is the default; both are first-class.
• The core idea is variable. The product supports both a physical locker location and a digital system for tracking and coordinating where deliveries get held. Neither is the default; both are first-class, and they are expected to work together.

The audience for this document is the team building the product: engineers, designers, and reviewers who need one internally consistent statement of what is being built, who it is for, where each responsibility lives, and what is explicitly out of scope.

2. System Overview

mail-storage-deliveries is delivered as a first-party web application with its own identity and its own custom interface. It has a backend that persists delivery records, storage locations, and the association between them, so that a held delivery can be tracked across sessions and retrieved later.

Actors. Two accepted human roles use the product: the Resident Recipient, who arranges for a delivery to be held and later collects it, and the Delivery Service Operator, who handles deliveries for multiple recipients and coordinates the storage locations where those deliveries are held. Both roles are variable expressions of the same product: a single person may act as a resident, a business may act as an operator, and the product does not privilege either.

Accepted behavior. The product lets an actor arrange for a delivery to be received and held at a storage location, track that delivery and its current storage location, and complete collection of a held delivery. Operators additionally manage deliveries across multiple recipients and manage the storage locations used to hold deliveries. Because a delivery must be associated with a storage location before it can be tracked or retrieved, and because operator work spans many recipients and locations, the product distinguishes resident-facing work from operator-authorized work.

Identity and access. The product owns its identity. Actors enroll themselves before first use, and returning actors verify themselves before reaching protected delivery, pickup, operator, or location workflows. The public entry surface is reachable without identity; everything that carries durable delivery or location state is not.

Narrow exclusions. This document does not add capabilities beyond the accepted thread. It does not introduce payment, billing, shipping-rate calculation, carrier label generation, address validation services, notification delivery channels, analytics, or administrative back-office tooling. It does not fix the product to a single user type or a single storage medium, because the source explicitly makes both variable.

2a. Product Interpretation and Delivery Boundary

The product is a first-party application. Its pages, its identity, and its delivery and location records are owned and served by the application itself; there is no provider-owned or external surface that carries accepted product state.

Access is split into two boundaries. The public boundary is the Landing page, which is reachable without identity and explains what the service does, who it is for, and how the physical and digital options relate. The protected boundary covers everything that carries durable state: a resident's held deliveries and their collection, and an operator's multi-recipient delivery management and storage-location management. Reaching the protected boundary requires identity, established either by self-service enrollment or by returning verification. The interaction that establishes access is itself anonymous — Login and Sign Up are reachable without identity, and protected state stays unavailable until identity is established.

Both variable options are current. A resident acting alone and a delivery-service business acting for many recipients are both supported now, and a physical locker location and a digital tracking and coordination layer are both supported now. Nothing in this document defers either option to a future horizon.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source, so no source content inventory is produced.

2c. Page Content and Component Coverage

The page inventory is fixed and ordered: Landing, Login, Sign Up, Deliveries, Delivery Setup, Pickup, Operator Deliveries, Locations. Each page appears exactly once below.

Landing

• Information and state. Anonymous public entry. Explains mail storage for deliveries that people are not home to receive. Presents the two variable user options — individual residents receiving their own mail, and a business such as a courier or locker service managing deliveries for many people — as two visible lanes of equal weight. Presents the two variable operating options — a physical locker location and a digital system for tracking and coordinating where deliveries get held — as complementary rather than competing. No identity required; no protected state shown.
• Primary actions. Enter the resident lane and begin arranging storage; enter the delivery-service lane and begin managing deliveries for many people; proceed to Login; proceed to Sign Up.
• Supporting actions. Read the four-stage explanation of how a delivery moves (arrange, drop, hold, collect); read the description of the physical locker option; read the description of the digital tracking option.
• Domain entities. Delivery (conceptual), storage location (conceptual), resident, delivery service.
• Component responsibilities. A wayfinding headline block; a full-width status band carrying the four uppercase stage micro-labels; a schematic route panel showing a courier lane entering a locker bank with numbered compartments and status chips; a two-lane split presenting the resident option and the delivery-service option with the same numbered steps in each; a primary call to action and a secondary text link.
• States. Loading: static content, no loading state required. Empty: not applicable — the page always carries its explanatory content. Success: the visitor understands both variable user options and both variable operating options and chooses a lane or an access action. Error: not applicable to static content; if a lane link fails to resolve, the visitor remains on Landing and can retry. Recovery: the visitor can always reach Login or Sign Up from the same screen.

Login

• Information and state. Anonymous access surface for returning actors. Accepts returning verification credentials for both residents and delivery-service operators. No protected delivery, pickup, operator, or location state is displayed before verification succeeds.
• Primary actions. Submit returning credentials to resume control of durable delivery records and storage coordination.
• Supporting actions. Move to Sign Up when the actor has not enrolled before.
• Domain entities. Actor identity, session.
• Component responsibilities. Credential entry fields; submit control; link to enrollment; inline validation messaging.
• States. Loading: submit control shows a pending state while verification is checked. Empty: fields start empty with labels. Success: the actor is verified and continues to the protected destination appropriate to their work. Error: invalid or unrecognized credentials produce an inline message and the actor remains on Login with entered values preserved. Recovery: the actor can correct credentials and resubmit, or move to Sign Up.

Sign Up

• Information and state. Anonymous enrollment surface for first use. Establishes a first-party identity for an actor who will either arrange storage for their own deliveries or manage deliveries for many people. Collects only what is needed to establish the identity and to know which kind of work the actor is beginning.
• Primary actions. Complete self-service enrollment and establish identity.
• Supporting actions. Move to Login when the actor already has an identity.
• Domain entities. Actor identity, actor kind (resident or delivery service).
• Component responsibilities. Enrollment fields; the choice between beginning as an individual resident and beginning as a delivery service; submit control; link to Login; inline validation messaging.
• States. Loading: submit control shows a pending state while enrollment is recorded. Empty: fields start empty with labels. Success: identity is established and the actor continues into the protected workflow matching the kind of work they chose. Error: missing or rejected enrollment input produces an inline message and the actor remains on Sign Up with entered values preserved. Recovery: the actor can correct input and resubmit, or move to Login if an identity already exists.

Deliveries

• Information and state. Protected, resident-facing overview of the actor's held deliveries and the storage location currently holding each one. Each delivery row shows its identity, its current storage location, and its current status. Status is presented in a fixed column position so a list can be read by scanning one column.
• Primary actions. Open a delivery to see its detail and current storage location; begin arranging a new delivery to be held.
• Supporting actions. Move to Pickup to collect a delivery that is ready; filter or scan the list by status.
• Domain entities. Delivery, storage location, delivery status, recipient.
• Component responsibilities. Delivery list with ruled rows and aligned label/value columns; a fixed-position status column; a control to begin a new delivery arrangement; a link into Pickup for a delivery that is ready.
• States. Loading: list region shows a pending state while deliveries are retrieved. Empty: no deliveries yet — the page explains that no delivery is currently held and offers the action to arrange one. Success: held deliveries and their storage locations are listed with current status. Error: if deliveries cannot be retrieved, the page states the failure and offers retry. Recovery: retry reloads the list; the actor can also begin a new arrangement from the same page.

Delivery Setup

• Information and state. Protected, focused workflow for arranging a delivery to be received and held at a storage location. Captures the delivery's identifying details and the storage location at which it should be held, because a delivery must be associated with a storage location before it can be tracked or retrieved. Available to a resident arranging their own delivery and to an operator arranging a delivery on behalf of a recipient.
• Primary actions. Select or specify the storage location that will hold the delivery; confirm the arrangement so the delivery becomes trackable.
• Supporting actions. Review the chosen storage location before confirming; return to Deliveries without confirming.
• Domain entities. Delivery, storage location, recipient, delivery status.
• Component responsibilities. Delivery detail fields; storage location selection; confirmation control; cancel/return control; inline validation messaging.
• States. Loading: location options show a pending state while available storage locations are retrieved. Empty: if no storage location is available to select, the page states this plainly and does not allow confirmation. Success: the delivery is arranged and associated with its storage location, and the actor continues to Deliveries where it appears as held. Error: missing required delivery details or an unselected storage location produce an inline message and the arrangement is not created. Recovery: the actor corrects the input and confirms again, or returns to Deliveries and starts over.

Pickup

• Information and state. Protected, resident-facing completion surface for retrieving a held delivery from its storage location. Shows the delivery being collected, the storage location holding it, and the collection code that identifies the collection. The collection code is the product's single expressive moment: a four-digit code revealed digit by digit inside a ring that draws itself.
• Primary actions. Present the collection code to complete retrieval of the held delivery from its storage location.
• Supporting actions. Review the delivery and its storage location before collecting; return to Deliveries if the delivery is not the intended one.
• Domain entities. Delivery, storage location, collection code, delivery status.
• Component responsibilities. Delivery and location summary; collection code reveal with its ring; confirmation control that completes collection; return control.
• States. Loading: the collection code region shows a pending state while the code is retrieved. Empty: if no delivery is ready for collection, the page states this and points back to Deliveries. Success: collection is completed, the delivery's status becomes collected, and the actor continues to Deliveries where the delivery shows as collected. Error: if the code cannot be retrieved or collection cannot be completed, the page states the failure and the delivery remains held. Recovery: the actor can retry the reveal or the completion, and the delivery stays held until collection actually succeeds.

Operator Deliveries

• Information and state. Protected, operator-authorized overview for managing held deliveries for multiple recipients and coordinating the storage locations where each is held. Rows carry the recipient, the delivery, its storage location, and its status, with status in a fixed column position so a dense list can be scanned.
• Primary actions. Open a delivery to see its detail, recipient, and current storage location; begin arranging a delivery for a recipient.
• Supporting actions. Move to Locations to manage the storage locations used to hold deliveries; scan or filter the list by status.
• Domain entities. Delivery, recipient, storage location, delivery status.
• Component responsibilities. Multi-recipient delivery list with ruled rows and aligned columns; fixed-position status column; control to begin a new delivery arrangement; link into Locations.
• States. Loading: list region shows a pending state while deliveries are retrieved. Empty: no deliveries are currently held — the page states this and offers the action to arrange one. Success: deliveries for multiple recipients are listed with their storage locations and current status. Error: if deliveries cannot be retrieved, the page states the failure and offers retry. Recovery: retry reloads the list; the operator can also begin a new arrangement from the same page.

Locations

• Information and state. Protected, operator-authorized destination for managing the storage locations used to hold deliveries. Each location carries its identity and the deliveries currently held there. This is where the physical locker option and the digital tracking option meet: a location is the physical place, and its record is the digital coordination layer.
• Primary actions. Add a storage location; open a storage location to see the deliveries it currently holds.
• Supporting actions. Return to Operator Deliveries to work the delivery list.
• Domain entities. Storage location, delivery, delivery status.
• Component responsibilities. Storage location list with ruled rows and aligned columns; control to add a location; per-location view of held deliveries.
• States. Loading: list region shows a pending state while storage locations are retrieved. Empty: no storage locations exist yet — the page states this and offers the action to add one. Success: storage locations are listed with the deliveries each currently holds. Error: if storage locations cannot be retrieved, the page states the failure and offers retry. Recovery: retry reloads the list; the operator can also add a location from the same page.

3. Functional Requirements

Each requirement below is a distinct story point. Provenance is marked explicit for source-stated behavior, basic_default for accepted defaults, and required_inference for indispensable inferred mechanics.

FR-1 — Resident arranges storage for a delivery. Provenance: explicit. As a Resident Recipient, I should arrange for a delivery to be received and held at a storage location, so that mail and packages arriving while I am not home are received rather than returned or left on a doorstep. Trigger: I have a delivery coming and will not be home. Input: the delivery's identifying details and the storage location that will hold it. Observable result: the delivery is associated with that storage location and appears in my Deliveries list as held. Access state: protected; I must be verified. Failure/recovery: if required details are missing or no storage location is selected, the arrangement is not created and I am told what to correct. Continuation: I return to Deliveries, where the delivery is listed with its storage location and status.

FR-2 — Resident tracks held deliveries and their storage locations. Provenance: explicit. As a Resident Recipient, I should see the deliveries currently held for me and the storage location holding each one, so that I know where my mail is and what state it is in. Trigger: I open Deliveries. Input: none beyond my identity. Observable result: a list of my held deliveries, each with its current storage location and current status. Access state: protected; I must be verified. Failure/recovery: if the list cannot be retrieved, I am told and can retry. Continuation: I open a delivery for detail or move to Pickup for one that is ready.

FR-3 — Resident collects a held delivery. Provenance: explicit. As a Resident Recipient, I should retrieve a held delivery from its storage location, so that the delivery completes its journey to me. Trigger: a delivery is held and I am able to collect it. Input: the collection code for that delivery. Observable result: the collection is completed and the delivery's status becomes collected. Access state: protected; I must be verified. Failure/recovery: if the code cannot be retrieved or collection cannot be completed, the delivery remains held and I am told. Continuation: I return to Deliveries, where the delivery shows as collected.

FR-4 — Operator manages deliveries for multiple recipients. Provenance: explicit. As a Delivery Service Operator, I should manage held deliveries for many recipients in one place, so that I can coordinate where each delivery is held and keep deliveries from failing. Trigger: I open Operator Deliveries. Input: none beyond my operator-authorized identity. Observable result: a list of deliveries across recipients, each with its recipient, storage location, and current status. Access state: protected and operator-authorized. Failure/recovery: if the list cannot be retrieved, I am told and can retry. Continuation: I open a delivery for detail or move to Locations to manage storage.

FR-5 — Operator arranges a delivery for a recipient. Provenance: explicit. As a Delivery Service Operator, I should arrange for a delivery to be received and held at a storage location on behalf of a recipient, so that a delivery in my care reaches a storage location instead of failing. Trigger: I have a delivery for a recipient who is not home. Input: the delivery's identifying details, its recipient, and the storage location that will hold it. Observable result: the delivery is associated with that storage location and appears in Operator Deliveries as held. Access state: protected and operator-authorized. Failure/recovery: if required details are missing or no storage location is selected, the arrangement is not created and I am told what to correct. Continuation: I return to Operator Deliveries, where the delivery is listed.

FR-6 — Operator manages the storage locations used to hold deliveries. Provenance: explicit. As a Delivery Service Operator, I should manage the storage locations used to hold deliveries, so that the physical places and their digital records stay in step. Trigger: I open Locations. Input: the storage location's identity. Observable result: storage locations are listed with the deliveries each currently holds, and a newly added location becomes available for holding deliveries. Access state: protected and operator-authorized. Failure/recovery: if storage locations cannot be retrieved or a new one cannot be added, I am told and can retry. Continuation: I return to Operator Deliveries to work the delivery list.

FR-7 — Both user options are supported as variable. Provenance: explicit. As a product owner, I should have the product support both an individual resident receiving their own mail and a business such as a courier or locker service managing deliveries for many people, so that neither user type is treated as the default or the exception. Trigger: any actor begins using the product. Input: the actor's choice of the kind of work they are beginning. Observable result: the product serves the resident path and the delivery-service path with equal standing, and neither is gated behind the other. Access state: the choice is made at enrollment and reflected in the protected workflows the actor reaches. Failure/recovery: if the actor's chosen kind of work does not match what they need, they can return to the access surfaces and establish the appropriate identity. Continuation: the actor proceeds into the workflow matching their kind of work.

FR-8 — Both operating options are supported as variable. Provenance: explicit. As a product owner, I should have the product support both a physical locker location and a digital system for tracking and coordinating where deliveries get held, so that neither operating model is treated as the default or the exception. Trigger: a delivery is arranged or a storage location is managed. Input: the storage location used to hold the delivery. Observable result: a delivery is held at a physical storage location and simultaneously tracked and coordinated through the product's digital records. Access state: protected. Failure/recovery: if a delivery cannot be associated with a storage location, it cannot be tracked or retrieved, and the actor is told. Continuation: the delivery proceeds through its held state to collection.

FR-9 — Actor enrolls before first use. Provenance: required_inference. As a first-time actor, I should complete self-service enrollment before first use, so that the deliveries and locations I control are bound to me and can be resumed later. Trigger: I have no identity and need to arrange or manage deliveries. Input: the information needed to establish my identity and the kind of work I am beginning. Observable result: my identity is established and I continue into the protected workflow matching my kind of work. Access state: anonymous entry; the enrollment interaction itself is reachable without identity. Failure/recovery: missing or rejected input produces an inline message and I remain on Sign Up with my input preserved. Continuation: I proceed into the protected workflow, or move to Login if an identity already exists.

FR-10 — Returning actor verifies before protected work. Provenance: required_inference. As a returning actor, I should verify myself before reaching protected delivery, pickup, operator, or location workflows, so that durable delivery records and storage coordination remain under my control. Trigger: I return to the product with an existing identity. Input: my returning credentials. Observable result: I am verified and reach the protected destination appropriate to my work. Access state: anonymous entry; protected state stays unavailable until verification succeeds. Failure/recovery: invalid or unrecognized credentials produce an inline message and I remain on Login with my input preserved. Continuation: I correct and resubmit, or move to Sign Up.

FR-11 — A delivery is bound to a storage location before it can be tracked or retrieved. Provenance: required_inference. As the product, I should require that a delivery be associated with a storage location before it can be tracked or retrieved, so that a held delivery always has a known physical place. Trigger: a delivery arrangement is confirmed. Input: the selected storage location. Observable result: the delivery is trackable and retrievable only once that association exists. Access state: protected. Failure/recovery: if no storage location is selected, the arrangement is not created and the actor is told. Continuation: the actor selects a location and confirms.

FR-12 — Operator work requires an operator-authorized role. Provenance: required_inference. As the product, I should require an operator-authorized role before an actor manages deliveries for multiple recipients or manages storage locations, so that multi-recipient and location management remain with the delivery-service role. Trigger: an actor attempts to reach Operator Deliveries or Locations. Input: the actor's verified identity and its kind of work. Observable result: operator-authorized actors reach those destinations; actors without that authorization do not. Access state: protected and operator-authorized. Failure/recovery: an actor without operator authorization is not shown operator state and is directed to the workflows matching their own work. Continuation: the actor continues in the resident-facing workflows.

4. User Personas

Resident Recipient

Product context. A person who is not home to receive deliveries. Mail and packages arrive while they are out, and without somewhere for those deliveries to wait they risk being returned, abandoned, or left on a doorstep. They use the product because they want their deliveries received and held safely until they can collect them.

Primary goal. Have a delivery received and held at a storage location, know where it is, and collect it when they are able.

Distinct accepted responsibilities. The Resident Recipient arranges storage for their own deliveries, tracks the deliveries currently held for them and the storage location holding each one, and completes collection of a held delivery from its storage location. Their work is scoped to their own deliveries; they do not manage deliveries for other people and they do not manage the storage locations themselves.

Relevant inputs and decisions. They decide which storage location should hold a given delivery, they provide the delivery's identifying details when arranging it, and they present the collection code when collecting. Their recurring decision is whether a held delivery is the one they are collecting and whether it is ready.

Interactions with other accepted participants. The Resident Recipient is the counterparty to the Delivery Service Operator: an operator may arrange a delivery on their behalf, and the resident then sees that delivery in their own list and collects it. The resident does not need to coordinate with the operator inside the product for this to work — the delivery's association with a storage location is what connects the two sides.

Observable success. Their deliveries appear as held with a known storage location, and they complete collection so the delivery shows as collected rather than returned or left on a doorstep.

Delivery Service Operator

Product context. A courier, locker, or delivery-service role that handles deliveries for many people and needs somewhere for those deliveries to be held and coordinated. They work under time pressure and across volume: many deliveries, many recipients, and one or more storage locations. They use the product because a delivery that cannot be held is a delivery that fails.

Primary goal. Handle deliveries for multiple recipients and coordinate where each delivery is held, so that deliveries reach recipients instead of failing.

Distinct accepted responsibilities. The Delivery Service Operator manages held deliveries for multiple recipients in one place, arranges deliveries to be held at storage locations on behalf of recipients, and manages the storage locations used to hold deliveries. Their work is inherently multi-recipient and multi-location, which is what distinguishes it from the resident's single-recipient work.

Relevant inputs and decisions. They provide each delivery's identifying details and its recipient when arranging it, they decide which storage location will hold each delivery, and they decide when a new storage location needs to be added. Their recurring decision is where a given delivery should be held given the locations available.

Interactions with other accepted participants. The Delivery Service Operator acts on behalf of Resident Recipients. When they arrange a delivery for a recipient, that delivery becomes visible to the recipient as a held delivery with a storage location, and the recipient completes collection. The operator's success depends on the recipient being able to find and collect what was held.

Observable success. Deliveries across recipients are listed with their storage locations and current status, storage locations reflect the deliveries they hold, and deliveries reach recipients instead of failing.

5. Core User Flows

Flow 1 — Resident arranges storage for a delivery

1. The Resident Recipient is not home and has a delivery coming. They open the product and reach the Landing page, which explains that deliveries can be received and held rather than left on a doorstep.
2. They proceed to Sign Up and complete self-service enrollment, choosing to begin as an individual resident. Their identity is established and they continue into the resident-facing workflow.
3. They open Delivery Setup and enter the delivery's identifying details.
4. They select the storage location that will hold the delivery. This step is required: a delivery must be associated with a storage location before it can be tracked or retrieved.
5. They confirm the arrangement. The delivery is associated with that storage location and becomes trackable.
6. They continue to Deliveries, where the delivery appears as held with its storage location and current status.