update

Plan.md

@@ -1,81 +1,284 @@
-## Plan: HumHub Animal Rescue Project — Discovery & Planning
+## Plan: HumHub Animal Rescue Project - Plugin-First Execution Plan
 
-**TL;DR:**  
-This plan outlines the steps to move from the current HumHub setup to a detailed, actionable implementation plan for the Animal Rescue platform. The focus is on clarifying requirements, identifying dependencies, and structuring the project for effective execution.
+## 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.
 
-**Steps**
+## 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)
 
-### Phase 1: Requirements Clarification & Context Gathering
-1. **Inventory Current State**
-	- **Installed HumHub Modules:**
-	  - Custom Pages (custom_pages, v1.10.15): Create custom pages and widgets.
-	  - Gallery (gallery, v1.5.5): Adds galleries to spaces and profiles.
-	  - Tasks (tasks, v1.8.8): Task and project management.
-	  - Additional modules present: auth-keycloak, cfiles, content-bookmarks, dark-mode, fcm-push, linklist, mail, menu-manager, newmembers, online-users, polls, popover-vcard, questions, reportcontent, sharebetween, sms, socialshare, text-editor, usermap, virus-scanner, weather, wiki.
-	- **Users:**
-	  - Kelin Reij (kelinshomelab@gmail.com): admin
-	  - April Abigail (aprilabigail@example.com): Groups: users, rescue, charity; Spaces: ct-horse-rescue
-	  - Body Bigs (bodybrigs@example.com): user
-	- **Spaces:**
-	  - ct-horse-rescue: owned by April Abigail
-2. **Clarify Feature Requirements**
-	- For each major feature (custom pages, profiles, resource/event/animal/volunteer/donor management, intelligent matching, donor perks), gather:
-	  - Detailed functional requirements
-	  - Data model needs
-	  - Workflow expectations
-	  - Access control/privacy requirements
-	- Clarify what "configurable" means for each interface.
-	- Define requirements for integrations (donations, social media, etc.).
-3. **Identify Technical Constraints**
-	- Determine which features can be built with existing HumHub modules vs. which require custom development.
-	- Identify any third-party dependencies or APIs needed.
+## 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.
 
-### Phase 2: Design & Planning
-4. **Draft Data Models**
-	- Propose data structures for animals, events, resources, volunteers, donors, and organizations.
-5. **Workflow Mapping**
-	- Create workflow diagrams for key processes (animal intake, event creation, volunteer scheduling, etc.).
-6. **UI/UX Planning**
-	- Outline interface requirements for each user type and feature.
-7. **Security & Privacy**
-	- Define access control, privacy, and data retention policies.
+## Scope and Sequencing
 
-### Phase 3: Implementation Roadmap
-8. **Prioritize Features**
-	- Sequence features for phased implementation (MVP, Phase 2, etc.).
-9. **Module Configuration & Customization**
-	- Plan configuration of existing modules and scope for custom modules/pages.
-10. **Integration Planning**
-	 - Identify and plan for payment, social media, and other integrations.
+### 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
 
-**Relevant files**
-- README.md — Project vision, goals, and high-level requirements
+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)
 
-**Verification**
-1. Review and confirm the inventory of modules, users, and spaces.
-2. Validate requirements and workflows with stakeholders (admins, rescue owners, volunteers, donors).
-3. Ensure all technical and integration requirements are documented.
-4. Confirm that data models and workflows align with organizational needs.
-5. Review security and privacy plans for compliance.
+### 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
 
-**Decisions**
-- The plan is strictly for discovery and requirements gathering; no implementation will begin until all ambiguities are resolved.
-- All features and workflows will be mapped before any code or configuration changes.
-- Scope includes only what is outlined in the README and clarified during requirements gathering.
+### 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.
 
-**Further Considerations**
-1. Should the MVP focus on a subset of features (e.g., animal intake, event management) or aim for broad coverage?
-2. What is the preferred method for gathering detailed requirements (workshops, interviews, surveys)?
-3. Are there existing HumHub modules or third-party tools that can be leveraged to reduce custom development?
+### 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.