platform_functionality_guide.md

# Buildsnapper Assessor Platform - Complete Functionality Guide
**Training Resource for Chatbot Fine-Tuning**

---

## Overview

The Buildsnapper Assessor Platform is a web-based application designed for SAP (Standard Assessment Procedure) assessors to manage building compliance projects, generate reports, and collaborate with clients on UK Building Regulations Part L compliance.

---

## 1. Account Management

### 1.1 Creating an Account

**How to create an assessor account:**
1. Navigate to the account creation page
2. Provide the following information:
   - Email address
   - Username (display name)
   - Password (must meet security requirements)
   - Confirm password

**Password Requirements:**
- Minimum 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number
- At least one special character (!@#$%^?)

**After Registration:**
- You'll receive a verification email
- Click the verification link to activate your account
- You can then log in to the platform

###1.2 Logging In

**To log in to your assessor account:**
1. Go to the login page (`/assessor/login`)
2. Enter your email address
3. Enter your password
4. Click "Login"

**First-Time Login:**
- On first login, you may see an introductory guide
- You'll be asked to accept the Terms & Conditions and Privacy Policy
- After acceptance, you'll be directed to the Reports page

### 1.3 Password Reset

**If you've forgotten your password:**
1. Click "Forgotten Password" on the login page
2. Enter your email address
3. Check your email for a password reset link
4. Click the link and set a new password

**Security Note:** For privacy, the system will always show a success message, even if the email isn't registered.

### 1.4 Logging Out

To log out of your account, click the "Logout" button in the navigation menu. This will end your session and return you to the login page.

---

## 2. Client Projects Management

### 2.1 What are Client Projects?

Projects are the core organizational unit in Buildsnapper. Each project represents a development site with:
- A unique name
- Builder/client information
- Site address
- One or more plots (individual buildings)

### 2.2 Viewing Your Projects

**To view all your projects:**
1. Navigate to "Client Projects" from the main menu
2. You'll see a list of all projects assigned to you
3. Each project shows:
   - Project name
   - Builder name
   - Number of plots
   - Plot names

### 2.3 Creating a New Project

**To create a new project:**
1. Go to "Client Projects"
2. Click "Create New Project"
3. Fill in the required information:
   - **Client Email**: Email of the builder/client (must have an existing Buildsnapper account)
   - **Client Name**: Builder or developer name
   - **Project Name**: Unique name for this project
   - **Project Description**: Brief description of the development
   - **Project Address**: Site address
   - **Plots**: Add one or more plots (each plot represents a building)

**Important Notes:**
- The client must already have a Buildsnapper account (you can create one for them in the Credits page)
- Project names must be unique for each client
- Each plot needs a unique name within the project

**What happens when you create a project:**
- The project is linked to your assessor account
- The client can see this project in their Buildsnapper app
- The system automatically creates an assessor record linking you to the client
- Clients can then provide plot data and photos through their mobile app

### 2.4 Editing an Existing Project

**To update a project:**
1. Go to "Client Projects"
2. Click on the project you want to edit
3. Modify any of the following:
   - Project name
   - Builder name
   - Description
   - Address
   - Plots (add, remove, or rename)
4. Click "Save Changes"

**Note:** You can only edit projects that are assigned to you.

### 2.5 Deleting a Project

**To delete a project:**
1. Go to "Client Projects"
2. Find the project you want to delete
3. Click the "Delete" button
4. Confirm the deletion

**Warning:** Deleting a project will remove all associated data. This action cannot be undone.

### 2.6 Managing Plots

**What is a plot?**
A plot is an individual building within a project. For example, a housing development might have 20 plots (20 houses).

**Adding plots to a project:**
- When creating or editing a project, use the "Add Plot" button
- Give each plot a unique name (e.g., "Plot 1", "House A", "Unit 12")
- Each plot can have its own compliance assessment and report

**Plot Information:**
- Plot name
- Plot ID (automatically generated)
- Completion status (how many sections are completed)
- Photo archive (uploaded by client via mobile app)
- Associated report

---

## 3. Reports Management

### 3.1 Understanding Reports

Reports are compliance assessment documents generated for each plot. They contain:
- Building specifications
- Energy performance calculations
- Part L compliance information
- SAP ratings
- Recommendations

### 3.2 Viewing Reports

**To access your reports:**
1. Navigate to "Reports" from the main menu
2. Reports are organized by:
   - **Client** (builder name)
   - **Project** (development name)
   - **Plot** (individual building)

**Report Information Displayed:**
- Client name
- Project name
- Plot name
- Completion status (e.g., "3 out of 5 sections completed")
- Last modification date
- Unviewed revision indicator (if the report was updated since you last viewed it)

### 3.3 Downloading Reports

**To download a report:**
1. Go to "Reports"
2. Expand the client and project to find the specific plot
3. Click the "Download Report" button
4. The report will download as a PDF file

**Report File Names:**
Reports are automatically named with the project and plot information for easy organization.

### 3.4 Viewing Plot Photos

**To access photos uploaded by the client:**
1. Go to "Reports"
2. Find the relevant plot
3. Click the "Download Photos" button (if available)
4. Photos are provided as a ZIP archive

**Note:** Photos are uploaded by clients via the Buildsnapper mobile app during site visits.

### 3.5 Report Modification Tracking

**Understanding report modifications:**
- When a client updates plot information, the report is automatically regenerated
- The "Last Modified" date shows when the report was last updated
- An "Unviewed Revision" indicator appears if you haven't viewed the latest version

**To mark a report as viewed:**
- Simply open/download the report
- The system automatically updates your view date
- The "Unviewed Revision" indicator will disappear

### 3.6 Plot Completion Status

**Understanding completion status:**
Each plot has multiple sections that need to be completed:
1. Building fabric details
2. Heating system information
3. Ventilation details
4. Hot water system
5. Renewable technologies

**Status Indicators:**
- ✓ Green checkmark = All sections completed
- ✗ Red X = Some sections incomplete
- "3 out of 5" = Number of completed sections

---

## 4. Credits System

### 4.1 What are Credits?

Credits are licenses that you purchase to assign subscriptions to your clients. There are three types:

1. **Buildsnapper Annual Credits**: 12-month subscriptions to the Buildsnapper app
2. **Buildsnapper Monthly Credits**: 1-month subscriptions to the Buildsnapper app
3. **Manager Annual Credits**: 12-month licenses for the Buildsnpper Manager app

### 4.2 Viewing Your Credits

**To check your credit balance:**
1. Navigate to "Credits" from the main menu
2. You'll see:
   - Available Annual Credits
   - Available Monthly Credits
   - Available Manager Credits
   - Total Credits Spent
   - List of clients you've assigned credits to

### 4.3 Purchasing Credits

**To buy credits:**
1. Go to "Credits"
2. Click "Purchase Credits"
3. Select the credit type:
   - **Buildsnapper Annual**
   - **Buildsnapper Monthly**
   - **Manager Annual**
4. Enter the number of credits you want to purchase
5. Review the total cost

**Pricing (as of 2024):**
Pricing varies based on quantity:

**Buildsnapper Annual:**
- 1-4 licenses: £79.99 each
- 5-9 licenses: £74.99 each
- 10+ licenses: £69.99 each

**Buildsnapper Monthly:**
- 1-9 licenses: £7.99 each
- 10-19 licenses: £7.49 each
- 20+ licenses: £6.99 each

**Manager Annual:**
- 1-4 licenses: £39.99 each
- 5-9 licenses: £37.49 each
- 10+ licenses: £34.99 each

**Payment Process:**
1. Click "Proceed to Payment"
2. You'll be redirected to Stripe's secure checkout
3. Enter your payment details
4. Complete the purchase
5. You'll be redirected back to the Credits page
6. Your new credits will be available immediately

**Receipt and Invoice:**
- You'll receive a payment confirmation email
- An invoice will be available in your transaction history
- All transactions are securely processed through Stripe

### 4.4 Transaction History

**To view your purchase history:**
1. Go to "Credits"
2. Scroll to the "Transaction History" section
3. You'll see:
   - Purchase date
   - Product type (Annual/Monthly/Manager)
   - Number of credits purchased
   - Total cost
   - Invoice link (for download)

### 4.5 Assigning Credits to Clients

**To assign a subscription to a client:**
1. Go to "Credits"
2. Click "Assign Credit"
3. Enter the client's email address
4. Select the subscription type:
   - Monthly (uses 1 monthly credit)
   - Annual (uses 1 annual credit)
   - Manager Annual (uses 1 manager credit)
   - Trial (7-day free trial, doesn't use credits)

**If the client doesn't have an account:**
- Enter their name
- The system will create an account for them
- They'll receive a welcome email with instructions

**If the client already has an account:**
- Their existing subscription will be extended
- If they have an active subscription, the new period will be added to the end

**Important Notes:**
- You must have sufficient credits of the correct type
- Trial subscriptions can only be assigned once per client
- Credits are immediately deducted from your balance

### 4.6 Managing Client Subscriptions

**Viewing assigned clients:**
In the Credits page, you can see:
- All clients you've assigned subscriptions to
- Their current subscription status
- Expiry dates
- Assignment history

**Client List Shows:**
- Client name
- Email address
- Product type (Annual/Monthly/Manager/Trial)
- Assignment date
- Expiry date
- All previous assignments

### 4.7 Revoking Credits

**You can revoke a credit assignment within 7 days:**

1. Go to "Credits"
2. Find the client in your assigned clients list
3. Click "Revoke"
4. Confirm the revocation

**What happens when you revoke:**
- The client's subscription is immediately cancelled
- The credit is returned to your balance
- This can only be done within 7 days of assignment
- If the client had a previous subscription through you, it will be restored

**Limitations:**
- You can only revoke within 7 days of assignment
- You can only revoke subscriptions you assigned
- Trial subscriptions cannot be revoked (they're free)

### 4.8 Trial Subscriptions

**Free 7-day trials:**
- You can assign a 7-day trial to any new client
- This doesn't use any of your credits
- Each client can only receive one trial
- After the trial expires, you'll need to assign a paid subscription

**To assign a trial:**
1. Follow the normal credit assignment process
2. Select "Trial" as the subscription type
3. No credits will be deducted

---

## 5. Profile Management

### 5.1 Viewing Your Profile

**To access your profile:**
1. Click on your name in the top navigation
2. Select "Profile"

### 5.2 Editing Your Profile

**You can update:**
- **Name**: Your display name (shown to clients)
- **Company**: Your company name
- **Telephone**: Contact number
- **Logo**: Company logo (displayed in reports and client communications)
- **Search Visibility**: Whether you appear in the assessor search directory

**To update your profile:**
1. Go to "Profile"
2. Modify the fields you want to change
3. Click "Save Changes"

**Profile Information is Used In:**
- Project communications
- Reports sent to clients
- Assessor directory (if search visibility is enabled)
- All client-facing materials

### 5.3 Uploading a Company Logo

**To add or change your logo:**
1. Go to "Profile"
2. Click "Choose File" under Logo
3. Select an image file (PNG, JPEG, or GIF)
4. Click "Save Changes"

**Logo Requirements:**
- Supported formats: PNG, JPEG, GIF
- Recommended size: 512x512 pixels
- Maximum file size: 5MB

**Where your logo appears:**
- On reports
- In client communications
- In the assessor directory

### 5.4 Search Visibility

**What is Search Visibility?**
Enabling search visibility allows potential clients to find you in the Buildsnapper assessor directory.

**To toggle search visibility:**
1. Go to "Profile"
2. Check or uncheck "Visible in Assessor Search"
3. Click "Save Changes"

**When Enabled:**
- Your profile appears in client searches for assessors
- Clients can see your name, company, and contact information
- You may receive new project inquiries

---

## 6. Support & Feedback

### 6.1 Getting Help

**To submit a support request or feedback:**
1. Click the "Support" button (usually in the bottom corner)
2. Type your message or question
3. Click "Send"

**Your message will be sent to:**
- support@bricksandbot.com
- Stored in the support system for tracking

**Support requests include:**
- Your name
- Your email
- Your user ID (for context)
- Your message

### 6.2 What Support Can Help With

- Technical issues with the platform
- Questions about using features
- Billing and credit questions
- Account problems
- Feature requests
- Bug reports

---

## 7. Common Workflows

### 7.1 Complete Workflow: New Client to Report

1. **Purchase Credits** (if needed)
   - Go to Credits page
   - Purchase annual or monthly credits

2. **Create Client Account** (if they don't have one)
   - In Credits page, assign a credit
   - Enter new client's email and name
   - System creates their account

3. **Create Project**
   - Go to Client Projects
   - Click "Create New Project"
   - Fill in project details and plots
   - Save

4. **Assign Subscription to Client**
   - Go to Credits
   - Assign annual or monthly subscription
   - Client receives access to their mobile app

5. **Client Completes Plot Data**
   - Client downloads Buildsnapper mobile app
   - They see the project you created
   - They complete building details for each plot
   - They upload photos

6. **View and Download Reports**
   - Go to Reports
   - Find the project and plot
   - Download the generated compliance report
   - Download plot photos if needed

### 7.2 Renewing a Client Subscription

1. Go to "Credits"
2. Find the client in your assigned clients list
3. Click "Renew" or "Assign Credit"
4. Select subscription type (annual/monthly)
5. Confirm assignment
6. Their subscription is extended from the current expiry date

### 7.3 Managing Multiple Plots in a Project

1. Create or edit the project
2. Add all plots at once:
   - Plot 1, Plot 2, Plot 3, etc.
3. Save the project
4. Client sees all plots in their app
5. They complete each plot separately
6. You get separate reports for each plot
7. Each plot can have different completion statuses

---

## 8. Best Practices

### 8.1 Project Organization

- **Use clear project names**: "Riverside Development Phase 1" instead of "Project A"
- **Standardize plot naming**: "Unit 1", "Unit 2" OR "House A", "House B"
- **Keep descriptions concise but informative**: Include key details like number of units, building types
- **Update project address**: Full postal address helps with client communication

### 8.2 Credit Management

- **Buy credits in bulk**: Larger purchases get better discounts
- **Monitor your credit balance**: Don't run out before assigning new clients
- **Use trials wisely**: Give trials to potential new clients, then convert them to paid
- **Track expiry dates**: Remind clients when their subscription is expiring

### 8.3 Client Communication

- **Keep your profile updated**: Professional logo and contact info build trust
- **Respond to client data promptly**: Check Reports regularly for new submissions
- **Download reports quickly**: If there's an "Unviewed Revision" indicator, check it

### 8.4 Report Management

- **Regular checks**: Visit the Reports page daily or weekly
- **Download systematically**: Keep local copies of all reports
- **Organize by project**: Create folders on your computer matching your project structure
- **Review completion status**: Follow up with clients on incomplete plots

---

## 9. Troubleshooting

### 9.1 Login Issues

**Problem: Can't log in**
- **Solution 1**: Verify you're using an assessor account (not a standard user account)
- **Solution 2**: Use the "Forgotten Password" link to reset
- **Solution 3**: Check your email for the verification link if this is a new account

**Problem: "Account not found" error**
- **Solution**: You may not have an assessor account. Contact support to convert your account.

### 9.2 Project Issues

**Problem: Can't create project - "Client email doesn't exist"**
- **Solution**: The client must have a Buildsnapper account first. Create one for them via the Credits page.

**Problem: "Project name already exists"**
- **Solution**: Each client must have unique project names. Add a suffix like "Phase 2" or use a date.

### 9.3 Credit Issues

**Problem: Payment succeeded but credits not showing**
- **Solution 1**: Refresh the page
- **Solution 2**: Wait 1-2 minutes for processing
- **Solution 3**: Contact support with your transaction ID

**Problem: Can't assign credit - "Insufficient credits"**
- **Solution**: Purchase more credits of the correct type (annual vs monthly vs manager)

**Problem: Can't revoke credit**
- **Solution 1**: Check if 7 days have passed (revocation only works within 7 days)
- **Solution 2**: Verify you originally assigned this credit

### 9.4 Report Issues

**Problem: Report not showing**
- **Solution 1**: Check if the client has completed the plot data
- **Solution 2**: Verify the project is assigned to you
- **Solution 3**: Refresh the Reports page

**Problem: Download button not working**
- **Solution 1**: Check your browser's pop-up blocker
- **Solution 2**: Try a different browser
- **Solution 3**: The report link may have expired - refresh the page

### 9.5 Profile Issues

**Problem: Logo not uploading**
- **Solution 1**: Check file format (must be PNG, JPEG, or GIF)
- **Solution 2**: Reduce file size (max 5MB)
- **Solution 3**: Try a different browser

---

## 10. Glossary

- **Assessor**: A professional who evaluates building energy performance and compliance
- **SAP**: Standard Assessment Procedure for energy rating
- **Plot**: An individual building within a development project
- **Client**: A builder or developer who uses Buildsnapper to manage their projects
- **Credit**: A license that allows you to assign subscriptions to clients
- **Entitlement**: A subscription assigned to a client via RevenueCat
- **RevenueCat**: The third-party service that manages subscription lifecycles
- **Part L**: UK Building Regulations covering conservation of fuel and power
- **Buildsnapper**: The mobile app used by builders to collect building data
- **Buildsnpper Manager**: The mobile app for project managers to oversee multiple projects
- **Report**: A PDF document containing compliance assessment for a plot
- **TER**: Target Emission Rate (Part L requirement)
- **BER**: Building Emission Rate (calculated value that must not exceed TER)

---

## 11. Feature Reference Quick List

| Feature | Location | Key Actions |
|---------|----------|-------------|
| Create Account | /assessor/create-account | Register, verify email |
| Login | /assessor/login | Email + password |
| Password Reset | /assessor/forgotten-password | Request reset link |
| View Projects | Client Projects menu | See all assigned projects |
| Create Project | Client Projects → New | Define client, plots, details |
| Edit Project | Client Projects → Edit | Modify name, plots, address |
| Delete Project | Client Projects → Delete | Remove project (irreversible) |
| View Reports | Reports menu | Browse by client/project/plot |
| Download Report | Reports → Download | Get PDF report |
| Download Photos | Reports → Photos | Get ZIP archive |
| View Credits | Credits menu | Check balance, history |
| Purchase Credits | Credits → Purchase | Buy via Stripe checkout |
| Assign Credit | Credits → Assign | Give subscription to client |
| Revoke Credit | Credits → Revoke | Cancel within 7 days |
| Edit Profile | Profile menu | Update name, company, logo |
| Send Feedback | Support widget | Contact support team |

---

## 12. API Endpoints (for Reference)

**Public Endpoints:**
- `/assessor/login` - Login page
- `/assessor/create-account` - Registration
- `/assessor/forgotten-password` - Password reset

**Authenticated Endpoints:**
- `/assessor/reports` - View reports
- `/assessor/client-projects` - Manage projects
- `/assessor/credits` - Credit management
- `/assessor/profile` - Profile settings
- `/assessor/support/feedback` - Submit support requests
- `/assessor/logout` - End session

**API Endpoints (JSON):**
- `POST /assessor/client-projects` - Create/update project
- `DELETE /assessor/client-projects/<id>` - Delete project
- `POST /assessor/client/assign` - Assign Buildsnapper subscription
- `POST /assessor/client/assign/manager` - Assign Manager subscription
- `POST /assessor/client/search` - Search for client
- `POST /assessor/client/revoke` - Revoke subscription
- `POST /webhooks/stripe` - Stripe payment webhook

---

This comprehensive guide covers all functionality available in the Buildsnapper Assessor Platform. Use it as a reference for answering user questions about platform features, workflows, and troubleshooting.