System Requirements Document for hvac-duct-cleaning

1. Introduction

Product intent. hvac-duct-cleaning is a first-party web application that lets offshore platform accommodation maintenance teams capture HVAC duct cleaning findings and compile them into a formal HVAC Duct Cleaning Report delivered as a Microsoft Word document (.docx). The product exists to make the cleaning work on an offshore platform's accommodation HVAC system documented accurately and completely enough to produce an audit-ready Word report for handover.

Audience. Two active human roles use the product: the HVAC Duct Cleaning Technician, who performs the duct cleaning work and captures the findings, and the Report Preparer, who assembles those findings into a structured report and exports it as a Word document. Both work in harsh marine environments and need calibrated, industrial-precision tooling rather than a generic SaaS interface.

Scope of this document. The document specifies the current delivery: anonymous entry, self-service identity establishment, durable cleaning-record capture, report assembly, and Word (.docx) export. It preserves the explicit hard constraint that the report must be delivered as a Word document.

2. System Overview

The product is a single first-party web application with a shared backend. It provides:

• An anonymous Landing page that explains the product, its offshore accommodation context, and its Word report output.
• Anonymous Sign Up (self-service first-use enrollment) and Login (returning verification) surfaces.
• A protected Cleaning Records destination where the HVAC Duct Cleaning Technician durably captures and revisits duct cleaning details and findings for the offshore platform accommodation.
• A protected Reports destination where the Report Preparer assembles captured cleaning details into the HVAC Duct Cleaning Report and exports the completed report as a Word .docx document.

Actors. Two active human personas (HVAC Duct Cleaning Technician, Report Preparer) and one supporting system actor (the application backend, which persists records and generates the .docx file). No provider-owned or external-destination surfaces are in scope.

Narrow exclusions. The product does not include scheduling, work-order dispatch, inventory, billing, or multi-tenant administration. It does not produce PDF or other non-Word report formats as a current capability. It does not include photography of people, and it does not use light backgrounds, blue/indigo primaries, pill buttons, gradient blobs, glassmorphism, or playful/bouncy animation.

2a. Product Interpretation and Delivery Boundary

The accepted requirement is narrow and specific: prepare an HVAC duct cleaning report for an offshore platform accommodation in a Word document. Everything in the current product serves that outcome. The application owns identity because cleaning records and generated reports are durable, actor-specific state that must be privately owned and resumable; therefore first use is a self-service Sign Up, returning use is Login, and the two working destinations (Cleaning Records, Reports) require login. The Landing, Login, and Sign Up surfaces are anonymously reachable.

The Word document is the delivery format for the report. The application generates the .docx file server-side and makes it available for download from the Reports destination. No other report format is a current commitment. Future ideas (for example, additional export formats or template libraries) are out of scope for this generation and are not acceptance criteria.

2b. Source Content Inventory

Not applicable — no reference directive declares a content_source.

2c. Page Content and Component Coverage

Landing

• Purpose and access. Anonymous public entry surface. Explains the HVAC duct cleaning reporting product, its offshore platform accommodation context, and its Word report output before any sign-in.
• Information and state. Oversized condensed headline "HVAC Duct Cleaning Report" stacked in two lines; Saira subhead describing offshore platform accommodation duct cleaning reporting; a macro duct-interior image with a circular "Duct Cleanliness Index" gauge in champagne; a primary CTA "Start Report" in champagne; secondary links to Login and Sign Up.
• Primary actions. "Start Report" routes an unauthenticated visitor to Sign Up (first use) or Login (returning). Secondary "Log in" and "Sign up" links.
• Supporting actions. None beyond navigation into the identity surfaces.
• Domain entities. None persisted on this page; it presents product context only.
• Component responsibilities. Hero composition (asymmetrical, gauge partially bleeding off the right edge), condensed headline block, subhead, CTA button, gauge component with needle sweep on load, top instrument-style navigation bar.
• States. Loading: hero image and gauge render with a needle sweep; no data fetch required. Empty: not applicable. Success: CTA navigates to Sign Up or Login. Error: if navigation fails, an inline message with a retry link. Recovery: retry navigation; the page remains usable without JavaScript-driven motion under prefers-reduced-motion.

Login

• Purpose and access. Anonymous identity-access surface for returning verification of technicians and report preparers who control durable cleaning records and reports.
• Information and state. Email and password fields; submit control; link to Sign Up; link back to Landing.
• Primary actions. Submit credentials to verify identity and establish a session; on success, route to Cleaning Records (technician) or Reports (preparer) as the default working destination.
• Supporting actions. Navigate to Sign Up; return to Landing.
• Domain entities. User identity (email, credential).
• Component responsibilities. Credential form, validation messaging, session establishment, post-login routing.
• States. Loading: submit disabled with progress indicator during verification. Empty: fields blank with inline hints. Success: session established and redirect to the working destination. Error: invalid credentials show an inline, non-revealing error and preserve entered email. Recovery: correct credentials and resubmit; or use Sign Up if no account exists.

Sign Up

• Purpose and access. Anonymous self-service first-use enrollment for actors who independently begin capturing cleaning findings and preparing reports.
• Information and state. Email, password, and confirmation fields; submit control; link to Login; link back to Landing.
• Primary actions. Create an application-owned identity and establish a session; on success, route to Cleaning Records.
• Supporting actions. Navigate to Login; return to Landing.
• Domain entities. User identity (email, credential).
• Component responsibilities. Enrollment form, client-side validation (required fields, email format, password confirmation match), server-side duplicate-email handling, session establishment.
• States. Loading: submit disabled with progress indicator during account creation. Empty: fields blank with inline hints. Success: account created, session established, redirect to Cleaning Records. Error: duplicate email or validation failure shows an inline message identifying the field. Recovery: correct the field and resubmit, or use Login if the account already exists.

Cleaning Records

• Purpose and access. Protected destination (login required) where the HVAC Duct Cleaning Technician durably captures and revisits HVAC duct cleaning details and findings for the offshore platform accommodation that the report must contain.
• Information and state. A dense but ordered table of cleaning records with aligned label/value pairs and circular status indicators; per-record detail view showing the captured cleaning details and findings; a create-record control; edit and revisit controls.
• Primary actions. Create a new cleaning record; enter and save cleaning details and findings; revisit and edit an existing record.
• Supporting actions. Filter or scan the record table; navigate to Reports.
• Domain entities. Cleaning Record (identifier, duct/system location within the accommodation, cleaning date, cleaning method, findings, cleanliness/compliance reading, technician identity, status).
• Component responsibilities. Record table with hairline dividers and circular status indicators; record form with validated fields; persistence to the backend; ownership binding to the signed-in technician.
• States. Loading: table skeleton with gauge/needle placeholder. Empty: message that no cleaning records exist yet, with a prominent create-record control. Success: saved record appears in the table with a confirmation. Error: save failure shows an inline error and preserves entered values for retry. Recovery: retry save; unsaved changes remain in the form.

Reports

• Purpose and access. Protected destination (login required) where the Report Preparer assembles captured cleaning details into the HVAC Duct Cleaning Report and exports the completed report as a Word .docx document.
• Information and state. A structured document preview assembled from captured cleaning records; a prominent export control; report metadata (platform accommodation identifier, report date, preparer); a list of included cleaning records.
• Primary actions. Generate the report from captured cleaning details; export the completed report as a Word .docx file.
• Supporting actions. Review the assembled preview; navigate to Cleaning Records to add missing details.
• Domain entities. Report (identifier, platform accommodation reference, included cleaning records, generated document, export status, preparer identity).
• Component responsibilities. Report assembly from persisted cleaning records; document preview panel with champagne left border and subtle inner glow; .docx generation on the backend; download delivery of the generated file.
• States. Loading: preview panel shows a progress state while the report is assembled. Empty: if no cleaning records exist, the page states that cleaning details must be captured before a report can be generated and links to Cleaning Records. Success: preview renders and the export control downloads the .docx. Error: generation or export failure shows an inline error with retry. Recovery: retry generation or export; return to Cleaning Records to complete missing details.

3. Functional Requirements

FR-1 — Prepare an HVAC duct cleaning report for an offshore platform accommodation. (explicit) As a Report Preparer, I should assemble the captured HVAC duct cleaning details for the offshore platform accommodation into a structured report, so that the cleaning work is documented in a formal report. Lifecycle: the Report Preparer opens Reports (login required), selects the captured cleaning records to include, and generates the report; the assembled preview is the observable result. Failure: if no cleaning details exist, the page states that details must be captured first and links to Cleaning Records. Continuation: after generation, the Report Preparer proceeds to export. Acceptance: a generated report exists that reflects the captured cleaning details for the offshore platform accommodation.

FR-2 — Deliver the report as a Word document (.docx). (explicit) As a Report Preparer, I should export the generated report as a Word .docx document, so that the report is delivered in the required Word format. Lifecycle: from the generated report on Reports, the Report Preparer triggers export; the backend produces a .docx file and the browser downloads it. Failure: export failure shows an inline error with retry. Continuation: the downloaded file is available for handover. Acceptance: the downloaded file is a valid .docx Word document containing the report content.

FR-3 — Self-service enrollment for first use. (required_inference) As an HVAC Duct Cleaning Technician or Report Preparer, I should create my own account on first use, so that I can privately own and resume my cleaning records and reports. Lifecycle: an anonymous visitor on Landing selects "Start Report" and reaches Sign Up; on successful enrollment a session is established and the actor is routed to Cleaning Records. Failure: duplicate email or validation error shows an inline message. Continuation: the actor proceeds to capture cleaning details. Acceptance: a new identity is created and the actor is signed in.

FR-4 — Returning verification before accessing protected cleaning records and reports. (required_inference) As a returning HVAC Duct Cleaning Technician or Report Preparer, I should verify my identity on Login, so that only I can access my durable cleaning records and reports. Lifecycle: an anonymous visitor on Landing or Login submits credentials; on success a session is established and the actor is routed to the working destination. Failure: invalid credentials show a non-revealing inline error. Continuation: the actor resumes work on Cleaning Records or Reports. Acceptance: protected destinations are inaccessible without a verified session.

FR-5 — Captured cleaning details must exist before a report can be generated. (required_inference) As an HVAC Duct Cleaning Technician, I should capture and save HVAC duct cleaning details and findings for the offshore platform accommodation, so that the report has content to assemble. Lifecycle: the signed-in technician opens Cleaning Records, creates a record, enters the cleaning details and findings, and saves; the saved record appears in the table. Failure: save failure shows an inline error and preserves entered values. Continuation: the technician revisits or edits the record, or the Report Preparer proceeds to generate the report. Acceptance: persisted cleaning records exist and are available to Reports.

FR-6 — Report must be generated before it can be exported as a Word document. (required_inference) As a Report Preparer, I should generate the report before exporting, so that the exported .docx contains the assembled content. Lifecycle: the Report Preparer generates the report on Reports; the export control becomes available only for a generated report. Failure: attempting export before generation is prevented or shows a message to generate first. Continuation: after generation, export proceeds per FR-2. Acceptance: export is only possible for a generated report.

4. User Personas

HVAC Duct Cleaning Technician

• Product context. Performs duct cleaning work on an offshore platform's accommodation HVAC system in a harsh marine environment. Needs to capture cleaning findings and results so they can be compiled into a formal report.
• Primary goal. Document the cleaning work accurately and completely enough to produce the Word report.
• Distinct accepted responsibilities. Creates and saves cleaning records on Cleaning Records; enters cleaning details and findings; revisits and edits records. This role is the originator of the report's content.
• Relevant inputs or decisions. Duct/system location within the accommodation, cleaning date, cleaning method, findings, cleanliness/compliance readings, and record status.
• Interactions with other accepted participants. Supplies the cleaning details that the Report Preparer assembles into the report. Both roles share the same identity surfaces (Sign Up, Login) and the same application-owned identity model.
• Observable success. Saved cleaning records appear in the Cleaning Records table and are available to the Reports destination.
• Provenance. Required inference from the accepted journey; no unsupported biography, demographics, or permissions are asserted.

Report Preparer

• Product context. Assembles the HVAC duct cleaning findings for the offshore platform accommodation into a structured report and exports it as a Word document.
• Primary goal. Produce a complete, correctly formatted .docx report available for handover.
• Distinct accepted responsibilities. Generates the report on Reports from captured cleaning details; reviews the assembled preview; exports the completed report as a Word .docx file.
• Relevant inputs or decisions. Which captured cleaning records to include, report metadata (platform accommodation identifier, report date, preparer), and when to export.
• Interactions with other accepted participants. Consumes the cleaning details captured by the HVAC Duct Cleaning Technician; both roles share the same identity surfaces and application-owned identity model.
• Observable success. A generated report preview renders and the exported .docx file downloads successfully.
• Provenance. Required inference from the accepted journey; no unsupported biography, demographics, or permissions are asserted.

5. Core User Flows

Flow A — First-use enrollment and first cleaning record (HVAC Duct Cleaning Technician)

1. The technician opens the application anonymously and lands on Landing, which explains the HVAC duct cleaning reporting product, its offshore accommodation context, and its Word report output.
2. The technician selects the primary CTA "Start Report".
3. The application routes the technician to Sign Up.
4. The technician enters email, password, and password confirmation and submits.
5. On success, the application creates the identity, establishes a session, and routes the technician to Cleaning Records. On failure (duplicate email or validation error), an inline message identifies the field and the technician corrects and resubmits.
6. On Cleaning Records, the technician selects the create-record control, enters the cleaning details and findings for the offshore platform accommodation, and saves.
7. The saved record appears in the ordered table with a circular status indicator and a confirmation. On save failure, an inline error appears and the entered values are preserved for retry.
8. The technician may revisit or edit the record later; the persisted record is available to the Reports destination.

Flow B — Returning verification and continued capture (HVAC Duct Cleaning Technician)

1. The returning technician opens Landing and selects Log in.
2. On Login, the technician enters email and password and submits.
3. On success, the application establishes a session and routes the technician to Cleaning Records. On failure, a non-revealing inline error appears and the entered email is preserved.
4. The technician revisits an existing record, updates findings, and saves; the updated record appears in the table.

Flow C — Report generation and Word export (Report Preparer)

1. The Report Preparer opens Landing and selects Log in (or Sign Up on first use, per Flow A steps 1–5).
2. On Login, the preparer submits credentials; on success the application establishes a session and routes the preparer to the working destination.
3. The preparer navigates to Reports.
4. If no cleaning records exist, Reports states that cleaning details must be captured before a report can be generated and links to Cleaning Records; the preparer coordinates with the technician or captures details as permitted, then returns.
5. The preparer selects the captured cleaning records to include and generates the report.
6. The application assembles the report and renders the structured document preview with a champagne left border and subtle inner glow.
7. The preparer reviews the preview and selects the prominent Export control.
8. The application generates the .docx file on the backend and the browser downloads it. On generation or export failure, an inline error appears with a retry control.
9. The downloaded Word document is available for handover.

6. Visuals Colors and Theme

Muse and headline. MARQ by Garmin — precision instrument reporting for offshore HVAC. Headline: "HVAC Duct Cleaning Report" set in Barlow Condensed uppercase, stacked in two lines.

Mode. Dark mode only.

Color tokens (exact hex by role).

Typography. Headings: Barlow Condensed, uppercase for labels and data headers, medium-to-bold weights, tight tracking. Body: Saira. Modular scale 1.25: 56/44/35/28/22/18/16/14. Mobile hero 36px, desktop 64px. Data labels 12px uppercase with 0.08em tracking. Data values set in tabular figures with generous letter-spacing.

Shape language. Circular gauges and bezels for metrics; ruled data rows with hairline dividers; edge-to-edge product photography with macro material detail; dark UI panels with subtle inner glow. Rounded-rectangle controls with 4px radius; no soft blobs, no pill buttons.

Spacing rhythm. Consistent 4px base unit; generous vertical rhythm between ruled data rows; dense but ordered table spacing on Cleaning Records.

Imagery style. Macro photography of duct interiors and HVAC components on dark titanium grounds; engineered textures (brushed metal, topographic lines); offshore platform accommodation exteriors in moody marine light; circular gauge overlays on imagery. No photography with people.

Avoid. White or light backgrounds; blue/indigo primary colors; rounded pill buttons; gradient blobs or glassmorphism; playful or bouncy animations; Inter, Roboto, or generic sans-serifs; identical hover-lift cards; photography with people.

7. Signature Design Concept

Public entry concept — "Instrument Panel Hero." The Landing page is a full-bleed dark hero (#0E1114) with an asymmetrical composition. On the right, a macro photograph of a clean duct interior on a dark titanium ground is overlaid with a circular gauge showing "Duct Cleanliness Index" in champagne (#C9A86A); the gauge partially bleeds off the right edge as decoration only. On the left, the oversized condensed headline "HVAC Duct Cleaning Report" is stacked in two lines in Barlow Condensed uppercase with tight leading, followed by a Saira subhead and the primary CTA "Start Report" in champagne. A slim top bar carries instrument-style tabs for Login and Sign Up. The image is the dominant element; no gradient blobs. All readable text and controls remain whole inside the viewport at 375px, 768px, and 1280px; only imagery and the gauge decoration may bleed or crop.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: dimensional_css

Landing Hero Motion Brief.

• Focal subject. Macro duct-interior photograph on a dark titanium ground, overlaid with a circular "Duct Cleanliness Index" gauge in champagne.
• Input → transformation → outcome thesis. On load, the gauge needle sweeps to the displayed cleanliness value and the metric counts up in tabular figures; the hero image performs a slow product turntable. The outcome is a composed, instrument-like first frame that communicates calibrated precision without playful motion.
• Motion vocabulary. Needle sweeps on gauge load; counting numbers for metrics; slow product turntable on hero imagery; scroll-triggered reveals of data panels with 200ms ease-out. No bounce, no particles.
• Composed first frame. Headline, subhead, and CTA fully visible on the left; gauge partially bleeding off the right edge; image dominant.
• Reduced-motion state. Under prefers-reduced-motion, the gauge renders at its final value with no sweep, numbers render statically, the turntable is replaced by a static image, and scroll reveals become immediate. All text and controls remain fully readable and operable.

9. Non-Functional Requirements

• NFR-1 — Word document delivery. (explicit) The report must be delivered as a Word document (.docx). The backend must generate a valid .docx file containing the assembled report content. Rationale: explicit hard constraint in the authoritative user evidence.
• NFR-2 — Durable state. (required_inference) Cleaning records and generated reports must persist across sessions and be bound to the owning identity. Rationale: the accepted journey requires revisiting records and generating reports from them.
• NFR-3 — Access control. (required_inference) Cleaning Records and Reports require an authenticated session; Landing, Login, and Sign Up are anonymously reachable. Rationale: durable actor-specific state must be privately owned and resumable.
• NFR-4 — Readability at all viewports. (explicit design constraint) Headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...)) to fit; no other element covers any part of them. Imagery, decoration, and motion may crop, bleed, overlap, or rotate as the direction asks, provided they cover no readable text or control.
• NFR-5 — Reduced motion. (explicit design constraint) With prefers-reduced-motion, provide a usable static arrangement; scrollable or moving content must allow every item to be brought fully into view.
• NFR-6 — Visual constraints. (explicit design constraint) No white or light backgrounds, no blue/indigo primary colors, no pill buttons, no gradient blobs or glassmorphism, no playful or bouncy animations, no Inter/Roboto/generic sans-serifs, no identical hover-lift cards, no photography with people.

10. Tech Stack

• Frontend. React (single-page application) with the specified Barlow Condensed and Saira fonts, dark-mode design tokens, and CSS-based gauge and motion components.
• Backend. Python / FastAPI, extending a single shared backend process for identity, cleaning-record persistence, report assembly, and .docx generation.
• Storage. A relational database for user identities, cleaning records, and generated reports, with generated .docx files stored and served for download.
• Document generation. A Python .docx generation library on the backend to produce the Word report.
• Deployment. Docker and docker-compose for the frontend, backend, and database services. Kubernetes is not required for the current deployment.

11. Assumptions and Constraints

• A-1. The application owns identity; first use is self-service Sign Up and returning use is Login. (required_inference)
• A-2. Cleaning Records and Reports require login; Landing, Login, and Sign Up are anonymous. (required_inference)
• A-3. The report is generated from captured cleaning records; no report can be generated without captured cleaning details. (required_inference)
• A-4. The report must be generated before it can be exported as a Word document. (required_inference)
• A-5. The Word document (.docx) is the only current report delivery format. (explicit)
• A-6. The product is scoped to a single offshore platform accommodation context; multi-platform administration is not a current capability.
• A-7. No provider-owned or external-destination surfaces are in scope.
• A-8. The reusable soc-report-copilot skill is not adopted; it is a security-operations report generator unrelated to HVAC duct cleaning reporting.

12. Glossary

• HVAC Duct Cleaning Report — The formal report documenting HVAC duct cleaning work on the offshore platform accommodation, delivered as a Word document.
• Cleaning Record — A durable, identity-bound record of duct cleaning details and findings for a specific duct/system location within the accommodation.
• Report Preparer — The persona who assembles captured cleaning details into the report and exports it as a Word document.
• HVAC Duct Cleaning Technician — The persona who performs duct cleaning work and captures the findings.
• .docx — The Microsoft Word document format in which the report must be delivered.
• Duct Cleanliness Index — The gauge metric displayed on the Landing hero to communicate calibrated cleanliness readings.
• Offshore platform accommodation — The living-quarters HVAC system on an offshore platform whose duct cleaning is documented by the report.