> ## Documentation Index
> Fetch the complete documentation index at: https://wegive.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Mapping

> Detailed mapping between WeGive funds and Virtuous project objects

# Project Mapping

This document details the mapping between WeGive fund objects and Virtuous project records, including fund categories, goal tracking, and designation management.

## Overview

Virtuous uses the **Project** object to represent funding categories, campaigns, and designations that donors can support. WeGive maps these to the **Fund** object to maintain consistent designation structures across both platforms.

## Core Project Mapping

### Primary Fields

| WeGive Field  | Virtuous Field | Type    | Required | Transformation                 |
| ------------- | -------------- | ------- | -------- | ------------------------------ |
| `id`          | Correlation ID | String  | No       | Stored in WeGive `virtuous_id` |
| `name`        | `Name`         | String  | Yes      | Direct mapping                 |
| `description` | `Description`  | String  | No       | Direct mapping                 |
| `is_active`   | `IsActive`     | Boolean | No       | Direct mapping                 |
| `goal_amount` | `Goal`         | Decimal | No       | Cents to dollars conversion    |

### Extended Fields

| WeGive Field | Virtuous Field | Transformation        | Notes                     |
| ------------ | -------------- | --------------------- | ------------------------- |
| `fund_type`  | `ProjectType`  | Fund category mapping | General, Restricted, etc. |
| `created_at` | `DateCreated`  | ISO 8601 format       | Read-only in Virtuous     |
| `updated_at` | `DateModified` | ISO 8601 format       | Updated on sync           |
| `sort_order` | `SortOrder`    | Numeric ordering      | Display order             |

## Project Structure Mapping

### Basic Project Object

**WeGive Fund to Virtuous Project:**

* **Fund Information**: Name, description, and current status
* **Financial Goals**: Target amounts and progress tracking
* **Category Classification**: Type of project (fund, campaign, etc.)
* **Management Settings**: Display order and administrative options

### Project Categories

| WeGive Fund Type | Virtuous Project Type | Description                          |
| ---------------- | --------------------- | ------------------------------------ |
| `general`        | `General`             | Unrestricted general operating funds |
| `restricted`     | `Restricted`          | Donor-restricted purpose funds       |
| `endowment`      | `Endowment`           | Permanent endowment funds            |
| `capital`        | `Capital`             | Capital campaign funds               |
| `program`        | `Program`             | Specific program funds               |
| `scholarship`    | `Scholarship`         | Scholarship and award funds          |
| `memorial`       | `Memorial`            | Memorial and tribute funds           |
| `emergency`      | `Emergency`           | Emergency response funds             |
| `event`          | `Event`               | Event-specific fundraising           |
| `other`          | `Other`               | Miscellaneous fund types             |

## Data Transformation

### Project Creation Processing

**WeGive to Virtuous Project:**

* Map fund name and description directly
* Convert goal amounts from cents to dollars
* Set project status based on fund active status
* Apply appropriate project category classification
* Establish display order and sorting

**Virtuous to WeGive Fund:**

* Import project name and description
* Convert goal amounts from dollars to cents
* Map project status to fund active status
* Determine fund type from project category
* Preserve project hierarchy and organization

### Category Mapping

**Project Type Translation:**

* Map WeGive fund types to Virtuous project categories
* Handle custom fund types with appropriate mapping
* Maintain category consistency across platforms
* Support organization-specific category needs

### Amount Conversion

**Goal Amount Processing:**

* Convert cents to dollars for Virtuous projects
* Convert dollars to cents for WeGive funds
* Maintain decimal precision for financial accuracy
* Handle null/empty goal amounts appropriately

## Sync Operations

### Push Operation (WeGive → Virtuous)

**Create New Project:**

* Validate fund name and required fields
* Map fund type to appropriate project category
* Convert goal amount to Virtuous format
* Set project status based on fund activity
* Create project with complete information
* Store correlation ID for future updates

**Update Existing Project:**

* Use correlation ID for project identification
* Update changed fields (name, description, goal)
* Maintain project type consistency
* Handle status changes appropriately
* Preserve Virtuous-specific project data

### Pull Operation (Virtuous → WeGive)

**Import Virtuous Project:**

* Map project fields to WeGive fund structure
* Convert amounts to WeGive cent format
* Determine appropriate fund type from project category
* Create or update WeGive fund record
* Store correlation ID for bidirectional sync

## Project Hierarchy and Organization

### Fund Grouping

**Department/Program Projects:**

* Support hierarchical fund structures
* Maintain parent-child relationships
* Coordinate sub-fund organization
* Support complex fund hierarchies

**Project Organization:**

* Display order management for project lists
* Category-based project grouping
* Search and filter capabilities
* Administrative organization tools

### Project Naming Conventions

**Hierarchical Project Names:**

* Support parent-child naming structures
* Maintain naming consistency across platforms
* Handle name conflicts and duplicates
* Support organization naming standards

## Project Analytics and Reporting

### Goal Tracking

**Progress Calculation:**

* Track total raised against project goals
* Calculate percentage completion
* Monitor fundraising velocity
* Support multi-year goal tracking

**Performance Metrics:**

* Gift count and average gift size
* Donor participation rates
* Time-based performance analysis
* Comparative project analysis

### Fund Performance Metrics

**Sync Fund Statistics:**

* Total donations received
* Number of unique donors
* Average gift amount
* Recent gift activity
* Fundraising trend analysis

## Validation and Error Handling

### Project Validation

**Required Field Validation:**

* Project name is required and unique
* Project category must be valid
* Goal amounts must be positive when specified
* Project status must be valid enumeration

**Business Rule Validation:**

* Project names follow organization standards
* Category selection appropriate for fund type
* Goal amounts reasonable for project scope
* Project hierarchy rules maintained

### Duplicate Project Detection

**Name-Based Matching:**

* Check for duplicate project names within organization
* Handle naming conflicts appropriately
* Support similar project name detection
* Maintain project uniqueness standards

### Error Recovery

**Handle Project Conflicts:**

* Resolve duplicate name conflicts
* Handle category mapping errors
* Manage goal amount validation failures
* Support manual project review and correction

## Default Project Management

### Default Project Configuration

**Ensure Default Project Exists:**

* Verify default project ID is valid and active
* Create default general fund if none exists
* Handle default project deactivation scenarios
* Maintain default project configuration

### Default Project Usage

**Gift Project Assignment:**

* Use default project for gifts without specific designation
* Handle project assignment failures gracefully
* Support organization-specific default rules
* Maintain gift-to-project relationships

## Project Lifecycle Management

### Project Activation and Deactivation

**Project Status Management:**

* Activate new projects for gift designation
* Deactivate completed or obsolete projects
* Handle historical gift references to inactive projects
* Maintain project history for reporting

**Project Archival:**

* Archive completed projects while preserving data
* Maintain historical gift relationships
* Support project reactivation when needed
* Handle project closure procedures

### Project Goal Management

**Goal Setting and Updates:**

* Support goal establishment and modification
* Track goal achievement and completion
* Handle goal extension and revision
* Support multi-phase project goals

## Performance Optimization

### Bulk Project Operations

**Batch Project Sync:**

* Process multiple projects efficiently
* Optimize API usage for large project lists
* Handle batch-level error reporting
* Support mass project updates

### Project Caching

**Cache Project Mappings:**

* Cache frequently accessed project data
* Optimize project lookup performance
* Support real-time project validation
* Minimize API calls for project information

## Integration with Gift Processing

### Project-Gift Relationships

**Gift Designation:**

* Ensure gifts properly designated to projects
* Validate project existence for gift creation
* Handle project changes affecting existing gifts
* Support gift reallocation between projects

**Project Financial Tracking:**

* Coordinate gift amounts with project totals
* Track project progress in real-time
* Support project-based financial reporting
* Maintain accurate project balances

## Special Project Types

### Campaign Projects

**Campaign Integration:**

* Link projects to fundraising campaigns
* Support campaign-specific project goals
* Coordinate campaign and project messaging
* Track campaign performance by project

### Event Projects

**Event Fundraising Projects:**

* Support event-specific fundraising projects
* Coordinate event registration with project designation
* Track event-based gift allocation
* Support multi-event project relationships

### Recurring Gift Projects

**Recurring Gift Project Assignment:**

* Default project assignment for recurring gifts
* Handle project changes for active recurring gifts
* Support project-specific recurring gift campaigns
* Maintain project consistency for recurring donations

## Custom Project Configuration

### Organization-Specific Projects

**Custom Project Rules:**

* Support organization-specific project categories
* Handle custom project field requirements
* Maintain organization project standards
* Support complex project approval workflows

### Project Integration Rules

**Advanced Project Mapping:**

* Support custom field mapping between systems
* Handle organization-specific project workflows
* Maintain project data quality standards
* Support advanced project reporting requirements

This comprehensive project mapping ensures accurate fund and designation synchronization between WeGive and Virtuous while maintaining project hierarchy, goal tracking, and proper gift designation management.