CARES Program Tracking - Product Requirements Document

Executive Summary

Add comprehensive CARES Fish Preservation Program tracking to mulm, enabling Brooklyn Aquarium Society members to participate in the international conservation effort. This feature will track species maintenance, articles, fry distribution, and generate reports for the CARES liaison to submit to the program administration.

Background

What is CARES?

The CARES Fish Preservation Program (Conservation, Awareness, Recognition, Encouragement, Support) is an international initiative founded in 2004 that encourages aquarium hobbyists to maintain endangered and at-risk freshwater fish species. The program creates a distributed "living gene bank" across hobbyists worldwide.

How CARES Works

1. Member clubs (like BAS) participate through a designated CARES Liaison
2. Hobbyists register species they're maintaining with photos for identification
3. Activities are tracked: maintenance, articles published, fry shared
4. Recognition seals are awarded for contributions:
   • Gold - Species registration
   • Green - Publishing articles about the species
   • Blue - Sharing fry with fellow club members
   • Red - Sharing fry with hobbyists from other clubs
   • Longevity - Continued maintenance year over year
5. Club liaison reports to CARES administration 3x/year with member registrations and activities

Current State in mulm

• species_name_group.is_cares_species marks ~400+ species as CARES conservation priority
• species_collection tracks which species members have in their collections
• submissions.cares_species gives +5 bonus points in BAP for breeding CARES species
• CARES badge displays on species pages with IUCN status

Gap

BAS is a CARES member club, but no one is actively maintaining the program. mulm can fill this gap by:

• Accepting registrations, article reports, and fry sharing records
• Tracking recognition seals
• Generating liaison reports for CARES submissions

Goals

1. Enable participation: BAS members can easily register CARES species and report activities
2. Track contributions: Maintain accurate records of who is keeping which species
3. Recognize effort: Display earned seals and contributions on member profiles
4. Simplify reporting: Generate formatted reports for CARES liaison submissions
5. Encourage conservation: Make CARES participation visible and rewarding

Non-Goals

• Real-time sync with caresforfish.org (manual liaison submission is fine)
• Certificate generation (future consideration)
• Integration with other conservation programs (IUCN Red List data already present)

User Stories

As a BAS member:

• I want to register a CARES species I'm maintaining so my contribution is tracked
• I want to upload a photo of my fish for species verification
• I want to record when I share fry with other hobbyists
• I want to record articles I've written about my CARES species
• I want to see my CARES seals and contributions on my profile
• I want to see which CARES species other members are maintaining

As the CARES liaison:

• I want to see all registered CARES species and who maintains them
• I want to export a report of registrations and activities for CARES submission
• I want to know when members share fry externally (Red seal events)

As an admin:

• I want to review and approve CARES registrations
• I want to manage CARES species list updates
• I want to view CARES program statistics

Functional Requirements

FR1: CARES Species Registration

Description: Members can register a species from their collection as a CARES-maintained species.

Requirements:

• FR1.1: Only species marked is_cares_species in species_name_group can be registered
• FR1.2: Registration requires uploading a photo of the member's actual fish
• FR1.3: Photo must be a side-view showing identifying characteristics
• FR1.4: Registration records the date and creates a Gold seal
• FR1.5: Members can have multiple CARES registrations (different species)
• FR1.6: Registration can be linked to an existing species_collection entry or create one

Acceptance Criteria:

• Member can browse their collection and register CARES-eligible species
• Photo upload is required to complete registration
• Registration appears in member's CARES profile
• Gold seal is awarded upon registration

FR2: Article Submission

Description: Members can record articles they've published about CARES species.

Requirements:

• FR2.1: Article must be associated with a registered CARES species
• FR2.2: Accept URL to online article OR file upload (PDF) for print articles
• FR2.3: Record article title and publication date
• FR2.4: Creates a Green seal for the species

Acceptance Criteria:

• Member can submit article with URL
• Member can submit article with PDF upload
• Green seal appears on member's CARES profile

FR3: Fry Sharing Records

Description: Members can record when they distribute fry of CARES species.

Requirements:

• FR3.1: Fry sharing must be associated with a registered CARES species
• FR3.2: Record recipient name with typeahead for known members
• FR3.3: For internal sharing (BAS member): creates Blue seal
• FR3.4: For external sharing: record recipient's club name, creates Red seal
• FR3.5: Record date of sharing
• FR3.6: Optional notes field

Acceptance Criteria:

• Member can record fry sharing with typeahead recipient selection
• Internal shares (no club specified) create Blue seal
• External shares (club specified) create Red seal
• Sharing history visible on member profile

FR4: Member CARES Profile

Description: Display member's CARES participation and earned seals.

Requirements:

• FR4.1: Show list of registered CARES species with photos
• FR4.2: Show seals earned per species (Gold, Green, Blue, Red)
• FR4.3: Show longevity indicator for multi-year registrations
• FR4.4: Show article and fry sharing history
• FR4.5: Accessible from member's main profile page

Acceptance Criteria:

• CARES section visible on member profile
• All seals display correctly per species
• Activity history is chronological

FR5: CARES Liaison Reporting

Description: Generate reports for CARES program submissions.

Requirements:

• FR5.1: Export all active registrations with member info, species, and dates
• FR5.2: Export fry sharing events (especially external/Red seal events)
• FR5.3: Export article submissions
• FR5.4: Include photos for species verification
• FR5.5: Filterable by date range (for quarterly submissions)
• FR5.6: Export formats: CSV for data, ZIP for photos

Acceptance Criteria:

• Admin can generate registration report for date range
• Report includes all required CARES fields
• Photos can be exported in batch

FR6: CARES Species Browser

Description: Browse and filter species by CARES status and maintainers.

Requirements:

• FR6.1: Filter species list to show only CARES species
• FR6.2: Show which members are maintaining each CARES species (public)
• FR6.3: Show total BAS coverage of CARES priority list

Acceptance Criteria:

• Species browser has CARES filter
• CARES species show maintainer count/list

FR7: BAP-CARES Integration

Description: Prompt members to register for CARES when they breed a CARES species.

Requirements:

• FR7.1: After BAP submission is approved for a CARES species, prompt member to register
• FR7.2: Prompt appears on confirmation page and/or notification
• FR7.3: Link directly to CARES registration flow for that species
• FR7.4: Do not auto-register - member must explicitly opt in

Acceptance Criteria:

• BAP approval for CARES species triggers registration prompt
• Prompt links to registration flow with species pre-selected

FR8: Annual Renewal

Description: Members confirm their CARES registrations annually.

Requirements:

• FR8.1: Track last confirmation date per registration
• FR8.2: Prompt members to confirm at start of calendar year
• FR8.3: Unconfirmed registrations marked as "lapsed" (not deleted)
• FR8.4: Consecutive confirmations earn longevity recognition

Acceptance Criteria:

• Annual confirmation prompt appears for registered species
• Confirmation updates cares_last_confirmed date
• Lapsed registrations are visually distinguished

Data Model

Extend species_collection

ALTER TABLE species_collection ADD COLUMN cares_registered_at DATETIME;
ALTER TABLE species_collection ADD COLUMN cares_photo_id INTEGER REFERENCES uploads(id);
ALTER TABLE species_collection ADD COLUMN cares_last_confirmed DATE;  -- Annual renewal

New Table: cares_article

CREATE TABLE cares_article (
  id INTEGER PRIMARY KEY,
  member_id INTEGER NOT NULL REFERENCES members(id),
  species_group_id INTEGER NOT NULL REFERENCES species_name_group(group_id),
  title TEXT NOT NULL,
  url TEXT,
  file_id INTEGER REFERENCES uploads(id),
  published_date DATE,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  CHECK (url IS NOT NULL OR file_id IS NOT NULL)
);

New Table: cares_fry_share

CREATE TABLE cares_fry_share (
  id INTEGER PRIMARY KEY,
  member_id INTEGER NOT NULL REFERENCES members(id),
  species_group_id INTEGER NOT NULL REFERENCES species_name_group(group_id),
  recipient_name TEXT NOT NULL,
  recipient_member_id INTEGER REFERENCES members(id),
  recipient_club TEXT,  -- NULL = internal (Blue), non-NULL = external (Red)
  share_date DATE NOT NULL,
  notes TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Seal Derivation Logic

Annual Renewal Logic

• Registration is "active" if cares_last_confirmed is within current calendar year
• System prompts members to confirm registrations annually (email/notification)
• Unconfirmed registrations become "lapsed" but data is retained
• Longevity seals count consecutive confirmed years

UI/UX Considerations

Registration Flow

1. Member views their collection or browses CARES species
2. Clicks "Register for CARES" on eligible species
3. Uploads photo (drag-drop or file picker)
4. Confirms registration
5. Gold seal immediately visible

Fry Sharing Form

• Recipient field: text input with typeahead showing BAS members
• If recipient not in typeahead, free-text allowed
• "External club" checkbox reveals club name field
• Date picker defaults to today

Member Profile CARES Section

• Collapsible/expandable section
• Species cards showing: photo, species name, seals earned
• Click to expand: article list, fry sharing history

Liaison Report Page (Admin)

• Date range picker
• Preview table of data
• Export buttons: CSV, ZIP (with photos)

Technical Considerations

Photo Storage

• Use existing uploads table and file storage
• Validate image format (JPEG, PNG)
• Consider max file size (existing limits apply)

Performance

• CARES species list is ~400 species, not a performance concern
• Index on species_collection(cares_registered_at) for queries
• Index on cares_fry_share(member_id, share_date) for history queries

Migration

• Schema changes via standard migration system
• No data migration needed (new feature)

Success Metrics

• Number of CARES species registrations
• Number of unique members participating
• Fry sharing events (especially Red seal/external)
• Articles submitted
• Coverage: % of CARES priority list maintained by BAS members

Design Decisions

1. Approval workflow: Self-service - member uploads photo, immediately registered (no admin queue)
2. Annual renewal: Required - members confirm annually they still maintain the species (earns longevity seals)
3. BAP integration: Prompt to register - after BAP approval for CARES species, prompt member to register for CARES program
4. Visibility: Public by default - species pages show who maintains them

Implementation Phases

Phase 1: Foundation

• Database schema
• CARES registration with photo upload
• Basic member profile display

Phase 2: Activities

• Fry sharing form and tracking
• Article submission

Phase 3: Reporting

• Liaison export functionality
• CARES species browser filter

Phase 4: Polish

• Standings/leaderboard
• Statistics dashboard
• Certificate generation (stretch)

GitHub Project Structure

Create GitHub Project: CARES Program Tracking

Issues to Create: