System Requirements Document for Cobalt-Bot

1. Introduction

The Cobalt-Bot project aims to develop a production-grade BTU Calculator for a commercial HVAC/plumbing calculation platform. This document outlines the system requirements, including functional and non-functional aspects, to ensure the calculator is accurate, user-friendly, and beneficial for both homeowners and contractors.

2. System Overview

Cobalt-Bot is designed to provide accurate BTU calculations and HVAC recommendations for various user types, including homeowners, HVAC contractors, builders, and property managers. The platform will feature multiple modes (Basic, Advanced, Contractor) to cater to different user needs and expertise levels. The system will also incorporate SEO and lead generation strategies to enhance visibility and user engagement.

3. Functional Requirements

• As a Homeowner, I should be able to use the Basic Mode to input simple data and receive BTU recommendations.
• As an HVAC Contractor, I should be able to access the Contractor Mode with advanced inputs for detailed calculations.
• As a Builder, I should be able to use the Advanced Mode to input detailed building specifications.
• As a Property Manager, I should be able to save and retrieve project histories for multiple properties.
• As a User, I should be able to view a built-in tutorial that highlights button functions and impacts.
• As a User, I should be able to receive warnings for oversizing and undersizing HVAC systems.
• As a User, I should be able to view efficiency recommendations based on input data.
• As a User, I should be able to convert units within the calculator.
• As a User, I should be able to access a FAQ section for common questions.
• As a User, I should be able to view SEO-optimized content and schema markup.
• As a User, I should be able to fill out contractor forms for lead generation.
• As a User, I should be able to access the platform on both desktop and mobile devices.

4. User Personas

• Homeowner: Seeks simple and quick BTU calculations for personal use.
• HVAC Contractor: Requires detailed calculations and professional recommendations.
• Builder: Needs comprehensive input options for new constructions.
• Property Manager: Manages multiple properties and requires project history tracking.

5. Core User Flows

• Homeowner accesses Basic Mode -> Inputs room dimensions -> Receives BTU recommendation and efficiency tips.
• HVAC Contractor accesses Contractor Mode -> Inputs detailed specifications -> Receives detailed BTU and system recommendations.
• Builder accesses Advanced Mode -> Inputs building specifications -> Receives comprehensive HVAC recommendations.
• Property Manager logs in -> Accesses project history -> Reviews past calculations and recommendations.

6. Visuals Colors and Theme

• primary: #1E3A8A (Deep Blue)
• primary_light: #3B82F6 (Light Blue)
• secondary: #F59E0B (Amber)
• accent: #EF4444 (Red)
• highlight: #FBBF24 (Gold)
• bg: #F3F4F6 (Light Gray)
• surface: rgba(255, 255, 255, 0.8)
• text: #111827 (Dark Gray)
• text_muted: #6B7280 (Muted Gray)
• border: rgba(209, 213, 219, 0.2)

7. Signature Design Concept

The homepage will feature an interactive 3D model of a house using @react-three/fiber and @react-three/drei. Users can click on different rooms to input data, and the model will dynamically update to show BTU recommendations in real-time. Hovering over elements will provide tooltips with additional information, and users can rotate the model to view different angles. This immersive experience will make the platform engaging and intuitive.

8. Interaction Model & Motion Direction

• Landing Page: Parallax interaction with layered depth via scroll. Decorative elements will translate at different speeds to create a visually rich first impression.
• Internal Pages: Static interaction model for clarity and ease of use, focusing on data input and results presentation.

9. Non-Functional Requirements

• The system must handle up to 1 million monthly users with scalable architecture.
• The platform should load within 3 seconds on both desktop and mobile devices.
• The system must ensure data security and privacy for all user inputs and stored data.

10. Tech Stack

• Frontend: React for Web
• Backend: Python, FastAPI
• Database: MySQL or MariaDB, using Alembic for migrations
• AI Models: Not applicable
• Local Orchestration: Docker, docker-compose
• Server-side Orchestration: Kubernetes

11. Assumptions and Constraints

• The platform will primarily serve users in the US, considering local HVAC standards and climate conditions.
• The system will not initially support international users or non-English languages.
• The platform will require internet connectivity to function.

12. Glossary

• BTU: British Thermal Unit, a measure of heat energy.
• HVAC: Heating, Ventilation, and Air Conditioning.
• SEO: Search Engine Optimization.
• CTA: Call to Action, a prompt for users to engage with the platform.

This document provides a comprehensive overview of the Cobalt-Bot project, ensuring all aspects are covered for successful development and deployment.