Engineering
Technical Architecture
Architecture overview
Your Solar Guy is planned around two entry paths: a private web workspace and verified email. Both paths use the same document processing, date rules, quality checks, private data, and outputs.
The diagram shows the main responsibilities and trust boundaries. It leaves room for implementation choices while keeping the product rules clear.
Architecture principles
- Keep documents and workspace data private.
- Use AI for interpretation and deterministic logic for authorization, dates, approvals, and external actions.
- Save progress before slow or external work.
- Preserve evidence, uncertainty, and partial progress.
- Share document and result services across web and email.
Major components
| Component | Responsibility |
|---|---|
| Web workspace | Upload, results, calendar actions, private access, and Q&A |
| Verified email | Attachment intake, follow-up questions, results, and calendar approval |
| Document Extraction Agent | Turn manual pages into structured evidence |
| Email Evaluator Agent | Interpret verified email conversations |
| RAG Q&A Agent | Answer questions from retrieved manual evidence |
| QA/QC Agent | Review important extraction and delivery artifacts |
| Calendar Agent | Calculate eligible dates and create calendar files |
| Shared private foundation | Store documents, structured results, workflow state, citations, and approvals |
Document and results flow
- Authorize the private workspace or verified email case.
- Validate and store each file.
- Divide long documents into bounded page work.
- Extract structured actions and evidence.
- Review extraction quality.
- Apply the optional installation baseline.
- Calculate supported dates and recurrence.
- Review and save results.
- Present the timeline, notes, condition-based actions, calendar options, and Q&A.
The Calendar Agent selects valid future dates, groups recurrence for display, and creates standard all-day events. Download and email delivery use the same eligible event set. Email approval is tied to the current result version.
Email coordination
A verified inbound event creates durable work. The service retrieves the message and allowed attachments, resolves the private conversation, and handles clear commands before language interpretation.
LangGraph coordinates conversation states. A case-scoped MCP boundary exposes only the capabilities needed by the Email Evaluator. Outbound messages pass through the applicable quality checks and leave through a durable email queue.
Manual Q&A
The first question prepares a reusable index for retained documents. Page-aware sections receive embeddings and remain tied to their document and page. Retrieval searches one authorized workspace, and answers may cite only the evidence selected for that question.
Trust and data boundaries
Private links provide workspace access without an account screen. The server validates workspace scope for every operation. Email identity depends on verified provider messages and signed conversation context. Public invitation forms reveal no existing workspace state.
Every document, result, question, approval, artifact, and job belongs to one workspace or verified email case. Models cannot choose the workspace, recipient, or authority. Manuals and email text are untrusted input, and provider credentials remain outside model context.
Reliability, limits, and deployment
Slow work uses durable jobs, leases, bounded retries, and duplicate protection. Completed stages are saved before the next stage begins. A temporary provider failure pauses at the affected stage.
AI access remains free-only. Rate limits preserve work, and no paid fallback is selected automatically.
The planned deployment uses Vercel for the web application, Supabase for private data and storage, Gemini for AI tasks, and Resend for email. Scheduled calls support background work and retention cleanup.
Tradeoffs
- Private links reduce sign-in friction but must be protected like passwords.
- Free-tier AI lowers prototype cost but may increase waiting and provider failures.
- ICS files work across common calendar clients but do not provide live synchronization.
- Fifteen-day retention improves privacy but limits long-term access.
- Native document processing is simpler than a separate OCR pipeline but depends on provider document support.
Related planning documents
Agent Orchestration describes role boundaries. Data Contracts describes information ownership. Engineering Constraints records limits. Testing and Acceptance defines release checks.