diff --git a/Plan.md b/Plan.md index eed7e49..c17d50d 100644 --- a/Plan.md +++ b/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. diff --git a/next-steps.md b/next-steps.md index 5ea1650..01f77bb 100644 --- a/next-steps.md +++ b/next-steps.md @@ -1,7 +1,3 @@ -investigate how to have a social feed for each animal that users can follow, without creating a humhub account for each animal. - - - UI/UX Planning: No custom login portals, user/group permissions restrict content based on role (admin,group-manager,user,rescue,donor,charity) Use existing plugins from marketplace for auth, allow login with HumHum, Google, Apple, Facebook, Instagram, X(twitter) diff --git a/project-requirements/animal-management-plugin.md b/project-requirements/animal-management-plugin.md index 40bd8ae..849dd56 100644 --- a/project-requirements/animal-management-plugin.md +++ b/project-requirements/animal-management-plugin.md @@ -1,7 +1,7 @@ # Animal Management Plugin — Project Requirements ## Purpose -Manage animal profiles, intake, transfers, progress, and placement. Enable public and admin/staff workflows for animal care, transfer, and adoption. +Manage animal profiles, intake, transfers, progress, and adoption. Enable public and admin/rescue/staff workflows for animal intake, care, transfer, and adoption. ## Features - Animal profile pages (public details, gallery, donation/adoption options, comments) @@ -10,7 +10,8 @@ Manage animal profiles, intake, transfers, progress, and placement. Enable publi - Social media feed per animal (follow, post updates) - Search/filter animal profiles (various display modes) - Intake form (flexible fields, AI suggestions) -- Progress updates (routine care, medical, behavioral) +- Medical Visit Form (for documenting medical/vetrinary visits) +- Progress updates (routine care, behavioral, daily life) - Placement/adoption/transfer workflows ## Access Control @@ -19,13 +20,104 @@ Manage animal profiles, intake, transfers, progress, and placement. Enable publi - Social: Manage animal feeds ## Data Model -- Animal: id, name, breed, age, status, medical, gallery, owner, etc. +>These are the default fields, Admin/Rescue/Staff can manage additional fields & all field groups, and hide/show any field +>Default fields should only be managable by Admin to avoid breaking a feature that relys on specific fields + +- Animal: + - Basic fields: + - id + - name + - DOB + - breed + - age + - previous owner + >If the previous owner has an account on this humhub network the User ID field is used to link the account + >instead of copying the contact details which could cause data inconsistency. + - User ID (if on this humhub network) + >If not on this humhub network these fields are used and User ID is not + - Name + - Business Name + - Street Address + - City + - State + - Zip + - Cell phone + - Business phone + - Email + + - History fields: + - Lineage + - backstory + + - Gallery: + - Staff/Social users post to the animals feed with #gallery as a tag and the image gets added to the animals gallery. + - Staff/Social user can upload images directly to gallery + + - Medical fields: + - Weight + - Pulse + - Blood Pressure + - Oxygen + - Chronic Conditions + - Acute Conditions + - Special Needs + - Date of this Medical Visit + - Date of Most Recent Medical Visit + - Physician + - Name + - Business Name + - Street Address + - City + - State + - Zip + - Cell phone + - Business phone + - License Number + - Physician + - Name + - Business Name + - Street Address + - City + - State + - Zip + - Cell phone + - Business phone + - License Number + - Previous Physician(s) + - Name + - Business Name + - Street Address + - City + - State + - Zip + - Cell phone + - Business phone + - License Number + + - Location fields: + - Rescue + - Location Name + - city + - state + - zip + + - On animal intake form + - When animal is not their possession yet. + - If previous owner's city/state are known autopopulate the Location Name form field with the City and/or State properly capitalized + - The user can enter a string of their choosing + - When the animal is in their possession + - The Rescue field is populated by this rescue's id, Location Name field is populated by the Rescue's name + - The city,state,zip fields are cleared and unused. + - Transfer: from/to, status, agreements, notifications + - Progress: vitals, notes, updates, media + ## Workflows - Intake: add new animal, flexible/unknown fields, AI suggestions - Progress: regular updates, post to feeds +- Medical Visit: document a medical/vetrinary visit, information collected by a Rescue/Staff user, does not include gallery or Location fields - Placement: adoption or transfer, notifications, agreements ## Integration Points @@ -33,11 +125,15 @@ Manage animal profiles, intake, transfers, progress, and placement. Enable publi - Social feed, donation/adoption blocks ## Open Questions / Needs Clarification -- What fields are required for intake and profile? -- What AI integrations are required (meal plan, lineage, owner lookup)? - What are the privacy requirements for animal data? +>Research this and advice, focus on requirements in CT to start. - How are transfer agreements and notifications managed? +>All notifications use the humhub notification system +>Transfer workflow is defined in custom-plugins.md - What is the approval process for posts/updates? +>No approval needed for posts/updates by Admin/Rescue/Staff +>Optional setting to require approval for posts from Social user +>Research approval process options ## Notes - Add more detail on transfer workflow, AI requirements, and privacy as needed.