humhub-rescue/Plan.md

Plan: HumHub Animal Rescue Project - Plugin-First Execution Plan

TL;DR

This plan transitions from discovery to build execution with a strict plugin order:

1. Space Profiles Plugin
2. Animal Management Plugin

The goal is to ship configurable, marketplace-ready HumHub modules one at a time, while preserving clear role-based access control and reusable patterns for later modules.

Planning Inputs Consolidated

This plan is based on all files in this workspace, including:

• Project vision and goals
• Existing planning notes
• Access control and privacy notes
• Custom plugin definitions
• Updated requirements for Space Profiles and Animal Management
• Prototype UI/workflow references from the aistudio project (used as reference only, not target runtime)

Locked Decisions (Already Confirmed)

• Development order is fixed:
  1. Space Profiles Plugin
  2. Animal Management Plugin
• No custom login portals in production HumHub flow.
• Plugin suite must be configurable and distributable as standalone marketplace modules.
• Space Profiles scope (now): animal rescue template only.
• Space Profiles optional fields: header HTML, body HTML, footer HTML.
• Space Profiles customization limits: HTML/CSS allowed only for profile page regions, no JavaScript.
• Space profile updates do not require approval workflow.
• Animal data model supports default field groups plus configurable custom fields.
• Animal default fields are admin-managed to avoid breaking dependent features.
• Transfer notifications use HumHub notification system.
• Post/update approvals:
  • Admin/Rescue/Staff: no approval required.
  • Social: optional approval setting.

Scope and Sequencing

Phase A: Foundation Shared by Both Plugins

Purpose: establish consistent module conventions before building plugin 1.

Deliverables:

• Module architecture conventions:
  • Settings location under Rescue Settings page
  • Permission checks mapped to groups (admin, rescue, staff, social, volunteers, user)
  • Reusable validation and upload constraints
• Shared standards:
  • Field metadata strategy for configurable forms
  • Image upload limits and contact-field validation standards
  • Naming and unique ID standards
• Space menu alignment check:
  • Animals, Stream/Feed, Gallery, Rescue/Staff/Volunteer calendar and task visibility rules

Acceptance criteria:

• Permission model and settings conventions documented and approved.
• No plugin implementation starts without shared conventions finalized.

Plugin 1: Space Profiles Plugin (First Build)

Objectives

• Deliver a template-driven space landing page for rescue organizations.
• Provide structured profile fields plus optional HTML content regions.
• Integrate Search Animal Profiles block into space profile.

Functional Requirements

• Profile fields:
  • Rescue name
  • Address, city, state, zip
  • Email
  • Phone
  • Animals we accept
  • Description
  • Mission statement
  • Header (HTML, optional)
  • Body (HTML, optional)
  • Footer (HTML, optional)
  • Icon
  • Background image
• Field management:
  • Ability to modify/create profile fields
  • Standard validation for contact fields
  • Reasonable upload size limits for images
• Template behavior:
  • Rescue center template is default/current template
  • Architecture leaves room for future templates

Access Control

• User: read-only profile viewing
• Admin/Rescue: manage profile fields/content/settings

Security and Content Controls

• Allow HTML/CSS only in designated profile regions.
• Block JavaScript and script-like injections.
• Restrict custom styling scope so it cannot modify wider HumHub UI.

Technical Deliverables

• Plugin settings UI under Rescue Settings:
  • Field configuration
  • HTML content editors (header/body/footer)
  • Branding assets (icon/background)
• Public profile renderer with template + field output
• Search Animal Profiles block placement on profile page
• Validation layer for contact fields and uploads

Test and Validation Checklist

• Permission tests for read/manage boundaries
• HTML/CSS sanitization tests (including negative tests)
• Field required/optional validation tests
• Mobile and desktop rendering checks
• Regression check: no style leakage beyond profile regions

Exit Criteria for Plugin 1

• Plugin is feature-complete for current rescue template scope.
• Configurable settings and field management are working.
• Security controls for custom HTML/CSS are verified.
• Package is ready for standalone distribution workflow.

Plugin 2: Animal Management Plugin (Second Build)

Objectives

• Implement full animal lifecycle management: intake, profile, medical tracking, progress updates, placement/adoption/transfer, and feed integration.

Core Functional Areas

1. Animal Profile and Identity

• Every animal has a unique stable ID.
• Transfer operations always retain ID continuity.
• Existing animal feed posts become read-only after transfer ownership change.

2. Animal Profile Page

• Public details
• Image gallery
• Donation/adoption options
• Comments

3. Admin/Rescue/Staff Transfer Intelligence UI

• Transfer Options Block:
  • Sorted list of potential rescue matches
  • Uses Transfer Match Block template
  • AI-assisted matching against available rescue spaces and needs
• Transfer Match Block:
  • Name, address, email, contact person
  • Met/unmet requirement indicators

4. Animal Feed and Follow Model

• Users can follow animals similar to users/spaces.
• Admin/Rescue/Staff/Social can publish animal feed updates.
• Gallery ingestion:
  • Tagged post (#gallery) adds image to gallery
  • Direct gallery uploads supported

5. Search Animal Profiles

• Search/filter block with paginated results
• Display modes:
  • Grid Small
  • Grid Large
  • List full width
• Admin/Rescue/Staff sees management-oriented result blocks

6. Intake Form

• No globally required fields (unknown data expected)
• Supports creating/modifying fields
• Includes AI-assisted suggestions where applicable
• Location logic:
  • If animal not in possession: prefill location name from previous owner city/state when available
  • If in possession: rescue and location name derived from current rescue; city/state/zip unused

7. Medical Visit Form

• Dedicated form for veterinary/medical visits
• Managed by Rescue/Staff
• Excludes gallery and location fields

8. Progress Updates

• Scheduled routine care updates
• Fields:
  • Weight and vitals
  • Behavioral notes
  • Meal plan changes
  • Housing changes
  • Medical concerns/recommendations when applicable
• Posting actions:
  • Post to space feed
  • Post to animal feed
• Plugin settings:
  • Auto-post to space feed
  • Auto-post to animal feed
  • Feed templates for each destination

9. Placement Workflow

• Adoption path:
  • New owner details
  • Generate adoption packet (zip of available records)
  • Mark animal as adopted
• Transfer path (HumHub network rescue to rescue):
  • Transfer request with agreement details (transport, scheduling, fees, barter)
  • Notification responses: message, conditions, accept, decline
  • If accepted and completed by receiving rescue, animal ownership moves to receiving space

Data Model Baseline

• Default field groups include:
  • Basic identity
  • Previous owner (linked HumHub user preferred when available)
  • History (lineage, backstory)
  • Medical data and physician records
  • Location context
  • Transfer, progress, and placement records
• Configuration model:
  • Admin can manage default fields
  • Admin/Rescue/Staff can add/manage additional fields and field groups
  • Visibility controls for fields and field groups

Access Control

• User: read-only
• Admin/Rescue/Staff: manage animals and workflows
• Social: manage animal feeds
• Approval option: optional moderation for Social-authored posts

Integration Points

• HumHub notifications for transfer workflows
• Donation/adoption blocks in animal views
• AI components for:
  • Transfer match recommendations
  • Intake assistance (meal/vitals suggestions, owner lookup support)

CT Privacy and Compliance Workstream (Required During Plugin 2)

Research and finalize Connecticut-focused handling requirements for:

• Animal medical data retention and access policy
• Owner/previous owner personally identifiable information
• Auditability of transfers and placement actions
• Feed moderation and records policy

Output required:

• Privacy decision note with enforceable implementation rules.

Test and Validation Checklist

• Permission boundary tests by role
• Field configurability and visibility tests
• Intake/location branching tests
• Transfer workflow state-transition tests
• Notification event tests
• Feed/gallery linking tests (#gallery behavior)
• Adoption packet generation and completeness checks

Exit Criteria for Plugin 2

• End-to-end intake-to-placement workflows are functional.
• Transfer and adoption flows are operational with audit trail.
• Configurable schema controls are stable.
• Privacy and moderation controls are implemented and documented.

Reuse Strategy From Prototype (aistudio project)

The aistudio app is reference-only and not a deployment target. Reuse should be limited to:

• Information architecture ideas (intake dashboard, detail tabs, center match cards)
• UX patterns for forms and status states
• Terminology and field grouping inspiration

Do not reuse:

• Multi-portal login model
• Hardcoded role-routing app shell
• Prototype-only AI assumptions without HumHub integration design

Milestone Plan

1. Milestone 0: Foundation and conventions finalized
2. Milestone 1: Space Profiles plugin complete and internally validated
3. Milestone 2: Animal Management data model and core profile flow complete
4. Milestone 3: Intake, medical, progress, and feed integration complete
5. Milestone 4: Placement, transfer, adoption packet, and notifications complete
6. Milestone 5: Privacy and moderation hardening complete; distribution readiness review

Risks and Mitigations

• Risk: configurable fields break core logic
  • Mitigation: protect admin-managed default schema and dependency checks
• Risk: custom HTML/CSS introduces security or UI instability
  • Mitigation: strict sanitization + scoped styling enforcement
• Risk: transfer workflow complexity causes data inconsistency
  • Mitigation: explicit state machine and immutable audit events
• Risk: unclear CT privacy constraints delay completion
  • Mitigation: run privacy workstream in parallel early in Plugin 2

Immediate Next Actions

1. Freeze and approve shared foundation conventions (permissions, settings layout, validation standards).
2. Define Space Profiles sanitization and field validation implementation details.
3. Build Space Profiles plugin in full before starting Animal Management.
4. Start Animal Management with schema foundation and transfer state model first.