3TE/user_workflow.md

# User Workflow and User Journey

## 1. First Time User Journey

### 1.1 Initial Setup
1. **Application Launch**
   - User opens application in browser (localhost)
   - Application checks for existing data
   - If no data: Show welcome screen with option to start with seed data or empty

2. **Login**
   - User sees login page
   - Enter username and password (first time: create account)
   - Simple authentication (stored in localStorage)
   - Redirect to Dashboard

3. **Dashboard Overview**
   - User sees empty dashboard or welcome message
   - Quick access to key actions:
     - "Create your first project"
     - "Configure waste types"
     - "View documentation"

### 1.2 Recommended Initial Configuration Order
1. **Configure Waste Types** (`/configuration/waste`)
   - Create at least one waste type
   - Define BMP, water percentage, characteristics
   - This is needed for projects

2. **Configure Natural Regulators** (`/configuration/regulators`)
   - Create regulators if needed for waste treatment
   - Define characteristics and dosage

3. **Configure Services** (`/configuration/services`)
   - Set up service pricing for 10 years
   - Configure all 8 services
   - This is needed for business plan calculations

4. **Create Treatment Site** (`/projects/treatment-sites`)
   - Create at least one treatment site
   - Define location, temperatures, surface
   - Subscribe to services

5. **Create Waste Site** (`/projects/waste-sites`)
   - Create waste collection sites
   - Link to waste types
   - Define quantities and distance

6. **Create Project** (`/projects`)
   - Create first project
   - Link to treatment site and waste sites
   - Configure modules and dates

7. **View Yields** (`/yields`)
   - See calculated yields for the project
   - Review formulas and calculations

8. **Business Plan** (`/business-plan`)
   - Configure financial data
   - View projections over 10 years

## 2. Typical User Workflow

### 2.1 Creating a New Project

**Step 1: Project Basic Information**
- Navigate to `/projects`
- Click "Create New Project"
- Fill in:
  - Project name
  - Start date - End date
  - Number of modules

**Step 2: Link Sites**
- Select treatment site (required)
- Select one or more waste sites (required)
- Configure transport (Yes/No)

**Step 3: Configure Waste**
- Select primary waste type
- Optionally override waste characteristics
- Add regulatory wastes if needed
- Add natural regulators if needed

**Step 4: Administrative Procedures**
- Add required procedures (ICPE, spreading, etc.)
- Set status for each procedure

**Step 5: Investments**
- Add investors if applicable
- Set status and amount

**Step 6: View Results**
- Navigate to Yields page
- Review all calculated outputs
- Check formulas and parameters

**Step 7: Business Plan**
- Navigate to Business Plan page
- Configure revenues (auto-filled from services)
- Configure variable costs
- Configure fixed costs
- Configure investments
- Review financial projections

### 2.2 Modifying an Existing Project

1. Navigate to `/projects`
2. Click on project to edit
3. Modify any field
4. Changes are saved automatically (or on blur)
5. Recalculations happen automatically
6. User can see updated yields and business plan

### 2.3 Viewing Yields

1. Navigate to `/yields`
2. Select project from dropdown (if multiple projects)
3. View all calculated outputs:
   - Material outputs (water, fertilizer)
   - Gas outputs (methane, CO₂)
   - Energy outputs (heat, electricity)
   - Bitcoin production
4. Expand formula sections to see calculations
5. Export data if needed

### 2.4 Analyzing Business Plan

1. Navigate to `/business-plan`
2. Select project
3. Review project header (dates, sites, modules)
4. Review economic characteristics (year by year)
5. Review pricing characteristics (valorizations)
6. Analyze KPIs (CAC, LTV, break-even)
7. Export report

## 3. Configuration Workflow

### 3.1 Configuring Waste Types
1. Navigate to `/configuration/waste`
2. Click "Add Waste Type"
3. Fill in form:
   - Name
   - Origin type and subtype
   - BMP value
   - Water percentage
   - Origin units per 1000m³ methane
   - Regulatory needs
   - Maximum storage duration
4. Save
5. Waste type available for projects

### 3.2 Configuring Services
1. Navigate to `/configuration/services`
2. Select service to configure
3. Enter pricing for each year (1-10)
4. First year can have different pricing (prototype)
5. Save
6. Service pricing used in business plan calculations

### 3.3 Configuring Treatment Site
1. Navigate to `/projects/treatment-sites`
2. Click "Add Treatment Site"
3. Fill in:
   - Name
   - Status
   - Altitude
   - Available surface
   - Monthly temperatures (12 values)
   - Subscribe to services
4. Save
5. Site available for projects

## 4. Data Management Workflow

### 4.1 Exporting Data
1. Navigate to `/settings`
2. Click "Export Data"
3. JSON file downloads
4. Contains all application data

### 4.2 Importing Data
1. Navigate to `/settings`
2. Click "Import Data"
3. Select JSON file
4. System validates data:
   - Structure validity
   - Required fields
   - Value constraints
   - Reference integrity
5. If valid: Replace all data
6. If invalid: Show errors, keep existing data

### 4.3 Backup Strategy
- User exports data regularly
- Data stored in browser (localStorage/IndexedDB)
- Export before major changes
- Import to restore previous state

## 5. Error Handling Workflow

### 5.1 Form Validation Errors
1. User fills form
2. Real-time validation (on blur or change)
3. Errors shown below fields:
   - Red border on input
   - Error message in red
   - Help text if needed
4. User corrects errors
5. Errors clear when valid

### 5.2 Calculation Errors
1. System detects calculation error (division by zero, etc.)
2. Shows error message in yields section
3. Indicates which calculation failed
4. Suggests correction (e.g., "Please set number of modules > 0")

### 5.3 Data Integrity Errors
1. User tries to delete entity used in project
2. System shows warning:
   - "This waste type is used in X projects"
   - Option to cancel or force delete
3. If force delete: Remove from projects or set to null

### 5.4 Import Errors
1. User imports invalid JSON
2. System shows detailed error list:
   - Which entity has errors
   - Which fields are invalid
   - Which references are broken
3. User fixes JSON and retries

## 6. Navigation Patterns

### 6.1 Primary Navigation
- **Sidebar**: Always visible, main sections
- **Breadcrumbs**: Show current location
- **Header**: Project selector, user info, logout

### 6.2 Quick Actions
- **Dashboard**: Quick links to common actions
- **Project List**: Quick actions (Edit, View BP, Delete)
- **Contextual Actions**: Buttons in relevant sections

### 6.3 Deep Linking
- All pages have unique URLs
- Can bookmark specific projects
- Can share URLs (within localhost)

## 7. User Feedback and Confirmation

### 7.1 Success Messages
- "Project created successfully"
- "Data exported successfully"
- "Configuration saved"
- Toast notifications (top-right, auto-dismiss)

### 7.2 Confirmation Dialogs
- Delete operations: "Are you sure you want to delete this project?"
- Import data: "This will replace all existing data. Continue?"
- Logout: "Are you sure you want to logout?"

### 7.3 Loading States
- Form submission: Button shows spinner
- Calculations: "Calculating..." message
- Data load: Skeleton loaders

### 7.4 Empty States
- No projects: "Create your first project"
- No yields: "Configure a project to see yields"
- No data: "Import seed data or start configuring"

## 8. Recommended Order for New Users

### Day 1: Setup
1. Login
2. Configure 2-3 waste types
3. Configure 1-2 natural regulators
4. Configure all 8 services (with default pricing)
5. Create 1 treatment site
6. Create 1-2 waste sites

### Day 2: First Project
1. Create first project
2. Link sites
3. Configure waste
4. View yields
5. Configure business plan
6. Review results

### Day 3: Refinement
1. Adjust configurations
2. Create additional projects
3. Compare scenarios
4. Export data

## 9. Power User Workflow

### 9.1 Multiple Projects
- Create multiple projects with different configurations
- Compare yields between projects
- Compare business plans
- Use project selector in header

### 9.2 Advanced Configuration
- Override waste characteristics per project
- Customize service pricing per project
- Configure complex waste mixtures
- Multiple regulatory wastes and natural regulators

### 9.3 Data Analysis
- Export data for external analysis
- Import modified data
- Version control via exports
- Backup before major changes

## 10. Help and Documentation

### 10.1 Contextual Help
- Help icons next to complex fields
- Tooltips on hover
- Formula explanations inline

### 10.2 Documentation Access
- Help page (`/help`) with:
  - User guide
  - Formula reference
  - FAQ
  - Examples

### 10.3 Onboarding
- First-time user: Show tooltips for key features
- Optional: Skip onboarding
- Can restart onboarding from settings