Repository navigation
[PRD] CARES Program Tracking #276
Description
Current roadmap — 2026-10-15
Overall delivery plan: #558. This roadmap supersedes the original schema/phase assumptions below where they conflict with current code.
Registration with photos, Member profiles/seals, fry sharing and browser/coverage already have implementations. The registry remains admin-only (#477), and registrations now have an independent model (#478). Treat #279 and #285 as verification/reconciliation work, not proof that those features are absent.
Remaining launch sequence:
- [Feature] Annual renewal system #283 — Annual re-confirmation with defensible confirmation history and consistent lapse rules.
- [Feature] Article submission #281 — Member article entry via URL or PDF, reflected in history/seals.
- [Feature] BAP-CARES integration prompt #282 — Eligible BAP approval offers explicit opt-in registration; keep behind the registry gate.
- [Feature] CARES liaison report export #284 — Liaison preview/CSV/photo export consuming completed registration and activity rules (blocked by [Feature] Annual renewal system #283 and [Feature] Article submission #281).
- Verify the complete CARES journey and prepare the Member launch #564 — Reconcile existing feature tickets, verify the full journey on staging, record operational/release decisions and then open Member access.
#286 standings remain optional after launch. This roadmap does not change the BAP CARES bonus or introduce a separate points system. Preserve the March 31 grace-period decision already recorded on #283; resolve incomplete historical confirmations and export/PDF decisions in their tickets.
Original PRD (historical requirements; schema details may be obsolete)
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
- Member clubs (like BAS) participate through a designated CARES Liaison
- Hobbyists register species they're maintaining with photos for identification
- Activities are tracked: maintenance, articles published, fry shared
- 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
- Club liaison reports to CARES administration 3x/year with member registrations and activities
Current State in mulm
species_name_group.is_cares_speciesmarks ~400+ species as CARES conservation priorityspecies_collectiontracks which species members have in their collectionssubmissions.cares_speciesgives +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
- Enable participation: BAS members can easily register CARES species and report activities
- Track contributions: Maintain accurate records of who is keeping which species
- Recognize effort: Display earned seals and contributions on member profiles
- Simplify reporting: Generate formatted reports for CARES liaison submissions
- 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_speciesin 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: 8000
- 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_confirmeddate - 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 renewalNew 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
| Seal | Condition |
|---|---|
| Gold | species_collection.cares_registered_at IS NOT NULL AND cares_photo_id IS NOT NULL |
| Green | EXISTS record in cares_article for member + species |
| Blue | EXISTS record in cares_fry_share WHERE recipient_club IS NULL |
| Red | EXISTS record in cares_fry_share WHERE recipient_club IS NOT NULL |
| Longevity | cares_last_confirmed shows 2+ consecutive years of confirmation |
Annual Renewal Logic
- Registration is "active" if
cares_last_confirmedis 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
- Member views their collection or browses CARES species
- Clicks "Register for CARES" on eligible species
- Uploads photo (drag-drop or file picker)
- Confirms registration
- 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
uploadstable 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
- Approval workflow: Self-service - member uploads photo, immediately registered (no admin queue)
- Annual renewal: Required - members confirm annually they still maintain the species (earns longevity seals)
- BAP integration: Prompt to register - after BAP approval for CARES species, prompt member to register for CARES program
- 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:
| # | Type | Title | Phase |
|---|---|---|---|
| 1 | PRD | CARES Program Tracking | - |
| 2 | Schema | Add CARES tracking tables | 1 |
| 3 | Feature | CARES species registration flow | 1 |
| 4 | Feature | Member CARES profile section | 1 |
| 5 | Feature | Fry sharing form | 2 |
| 6 | Feature | Article submission | 2 |
| 7 | Feature | BAP-CARES integration prompt | 2 |
| 8 | Feature | Annual renewal system | 2 |
| 9 | Feature | CARES liaison report export | 3 |
| 10 | Feature | CARES species browser filter | 3 |
| 11 | Stretch | CARES standings/leaderboard | 4 |
Activity
jra3 commentedon Jan 21, 2026
UI/UX Design Addendum
The following cross-cutting design concerns need to be addressed across all CARES features:
Seal Badge Design Spec
The five seal types need consistent visual design:
Design requirements:
Navigation & Entry Points
Decision needed: Where does CARES appear in main navigation?
Options:
Confirmed: CARES landing page will exist (see new issue to be created)
CARES Landing Page (New Requirement)
A dedicated overview page at
/careswith:Mobile Considerations
All CARES features should be responsive:
Error & Edge Cases