Business & Product

Product Requirements Document

Purpose

This PRD defines the MVP requirements for Your Solar Guy. It gives product, design, and engineering a shared view of the intended user experience, the safety boundaries, and the decisions that need to remain predictable.

Product overview

Your Solar Guy will help homeowners turn solar, battery, and inverter manuals into maintenance actions, supported dates, calendar events, and document-grounded answers. Users may submit documents through the web or email, then return through a private workspace link.

The MVP focuses on document understanding and follow-through. It excludes equipment monitoring, direct calendar synchronization, and professional service decisions. These boundaries keep the first release centered on a problem that can be tested with manuals users already have.

Problem statement

Important maintenance instructions are often buried in long equipment manuals. Owners need a clear, evidence-backed view of actions and dates without having to interpret every document themselves.

Product goals

1. Goals

• Accept supported manuals through web and email.
• Extract maintenance, inspection, service, and replacement requirements.
• Calculate dates only when source timing and an allowed baseline support them.
• Provide source references for verification.
• Create eligible all-day calendar events.
• Answer questions across retained workspace documents.
• Preserve privacy, uncertainty, and recoverable workflow state.

2. Non-goals

• Live equipment monitoring or control
• Energy optimization or dispatch
• Purchasing or installer management
• Legal, warranty, or professional safety advice
• Direct calendar-provider synchronization
• Account and password sign-in

Target users and jobs

1. Primary user

A homeowner or household member responsible for solar, battery, or inverter equipment.

2. Operating user

An operator responsible for service configuration, provider access, privacy, and support.

Core use cases

Functional requirements

1. Workspace access and lifecycle

• A private bearer link grants access to one workspace.
• Public forms must not reveal whether a mailbox already has a workspace.
• A workspace expires 15 days after its original creation time.
• Expiry removes private files and workspace-owned records.

2. Web document intake

• Accept up to five files per submission.
• Accept PDF, scanned PDF, JPG, JPEG, and PNG.
• Limit each file to 10,000,000 bytes.
• Support English documents.
• Validate stored content before AI processing.

3. Extraction and preliminary results

• Cover every page through bounded chunks.
• Extract devices, actions, timing rules, conditions, importance, and source references.
• Preserve successful page results when another page fails.
• Keep untrusted document instructions from changing system authority.

4. Installation baseline and timeline

• Installation date is optional.
• Accept exact dates and month/year estimates.
• Use the 15th for month/year estimates and retain estimated provenance.
• Respect explicit manufacturer triggers.
• Do not create dates for warranty periods, condition-only actions, ongoing tasks, or short operating durations.
• Calculate recurrence with deterministic calendar arithmetic.

5. Results presentation and deletion

• Present Action Timeline, Important Notes, then Condition-Based Actions.
• Group recurring actions for display while retaining underlying occurrences.
• Limit Important Notes and Condition-Based Actions to three prioritized items each.
• Show full HIGH, MEDIUM, and LOW importance labels.
• Keep results read-only.
• Deleting a document removes its derived results, vectors, and citations.

6. Calendar creation and delivery

• Include valid future dated actions.
• Produce all-day ICS events with a requested 14-day reminder.
• Allow download and authorized email delivery.
• Exclude individual actions that cannot produce valid events.
• Bind email approval to the current result version and event set.

7. Email invitation and inbound workflow

• Verify provider webhooks and message identity.
• Save messages and attachments before processing.
• Support multi-day conversations and missing-information replies.
• Recognize RETRY and approval commands from newly authored reply text.
• Use a durable outbox for outbound email.
• Prevent duplicate jobs and sends.

8. Document Q&A

• Index retained documents when the first question requires it.
• Retrieve evidence only from the authorized workspace.
• Cite supporting file and page references.
• Return a clear not-found response when evidence is absent.
• Prevent Q&A from creating dates or calendar events.

9. QA/QC release gates

• Review extraction, results, email, and calendar artifacts.
• Allow up to two correction cycles.
• Mark unresolved affected items for manual review.
• Preserve valid calendar-eligible items when another item needs review.

Business rules and edge cases

• Missing installation date allows undated results.
• Ambiguous dates require clarification.
• Duplicate webhook delivery must remain idempotent.
• Temporary provider failure preserves saved work.
• A 429 quota response pauses work without paid fallback.
• An expired private link does not grant access.
• New results invalidate approval for an older event set.

Nonfunctional requirements

1. Security and privacy

• Store documents privately.
• Enforce workspace scope on the server.
• Keep provider credentials out of the browser and model prompts.
• Sanitize logs and diagnostics.

2. Reliability

• Persist workflow state before external side effects.
• Use bounded retries and leases.
• Recover expired work safely.
• Use idempotency keys for jobs and delivery.

3. Performance and bounded execution

• Split long documents into bounded page work.
• Avoid chaining multiple slow AI stages in one execution window.
• Preserve checkpoints between stages.

4. Cost controls

• Use free-only AI configuration.
• Keep rate-limit handling separate from temporary provider errors.
• Avoid duplicate AI requests.

Dependencies

• Web application hosting
• Private database and object storage
• Gemini generation and embedding APIs
• Resend email sending and receiving
• Background scheduling
• Standards-compliant ICS calendar support

Failure and recovery requirements

• Temporary Gemini failure preserves the document and supports a later retry.
• Invalid credentials and malformed requests fail without repeated calls.
• Partial extraction remains usable when safe.
• Outbound failure retains the prepared message for controlled retry.
• Users receive a deterministic status email when document processing pauses.

Product limitations

• English documents only
• Five files per submission and 10,000,000 bytes per file
• No direct calendar synchronization
• No web editing of saved dates or results
• No guarantee that every manual provides enough timing evidence for dated events
• Free-tier provider limits may affect speed and availability

Product metrics

1. User funnel

Measure workspace visits, manual submissions, useful results, value actions, and repeat activity.

2. Trust and quality

Measure critical-action extraction accuracy, date accuracy, citation accuracy, RAG groundedness, and user-reported usefulness.

3. Reliability and cost

Measure processing failures, workflow completion, latency, and provider usage per successfully processed manual.

Risks