docs: expand host, community, and content guides (#902)

Author: rsmithlal

docs/community_management.md

@@ -0,0 +1,43 @@
+# Community Management
+
+This section describes how to manage communities, partners, invitations, memberships, and conversations.
+
+## People
+
+- **Create & Edit**: Add or modify person profiles, including name, email, profile image, and bio.
+- **Search & Filter**: Locate individuals by name, email, community membership, or role.
+- **Bulk Actions**: Import, export, or deactivate multiple person records via CSV operations.
+
+## Communities
+
+- **Host Community**: Register, customize, and activate new communities with unique branding, privacy, and membership settings.
+
+- **Future Expansions**:
+  - **Personal Communities**: Allow individuals to create their own private community spaces.
+  - **Geospatial Communities**: Auto-generate communities based on geographic boundaries (regions, cities).
+  - **Language Communities**: Segment communities by preferred language/localization.
+  - **Nested Sub-Communities**: Enable hierarchical community structures (chapters, subgroups) under a parent community.
+
+## Partners
+
+- **Name & Description**: Set partner name, subtitle, and summary description for public listings.
+- **Images**: Upload and manage partner logo, cover image, and photo galleries.
+- **Contact Details**: Store multiple addresses, phone numbers, email addresses, and social links via the contact detail editor.
+- **Mapping & Locations**: Geolocate partners on maps, define service areas, and display interactive location markers.
+
+## Invitations
+
+- **Platform Invitations**: Send email invites to new users, assign default roles, and monitor acceptance rates.
+- **Guest Access**: Create time-limited guest tokens for one-click entry without account creation.
+- **Invitation Lifecycle**: Track invitation statuses (pending, accepted, expired), resend or revoke invites, and view audit logs.
+
+## Memberships
+
+- **Role Assignment**: Grant or revoke platform/community roles for individuals, controlling their access and capabilities.
+- **Join & Leave**: Manage community membership directly or require approval; bulk-add or remove members as needed.
+
+## Conversations & Messaging
+
+- **Conversations**: Create new conversation threads (group or one-on-one), name channels, and add participants.
+- **Messages**: Compose and edit rich-text messages (attachments supported) that update in real time via WebSockets.
+- **Notifications**: Configure in-app toast and persistent alerts, as well as email digests for unread messages and mentions.

docs/content_management.md

@@ -0,0 +1,59 @@
+# Content Management
+
+This guide covers categories, navigation, page and block editing, resources, events, and maps.
+
+## Categories
+
+- **Topics**, **Journey Stages**, **Events**: Define and organize content categories, sequence journey stages, and tag events for user discovery.
+- **Media Defaults**: Configure default card and cover images for event listings and topic thumbnails.
+
+## Navigation
+
+### Areas
+- **Named Areas**: Create header, footer, admin, or custom sidebars with support for multiple nesting levels.
+- **Visibility & Privacy**: Control which user roles and communities can view each navigation area and schedule publication dates.
+- **Performance**: Enable fragment or page caching to speed up menu rendering and reduce backend requests.
+
+### Items
+- **Link Items**: Add external URLs, link to internal CMS pages, or reference app resources via dropdown selectors.
+- **Dropdowns**: Build hierarchical dropdown menus to organize related links under parent items.
+- **Item Settings**: Set publication schedules, role-based visibility, and caching preferences on individual navigation items.
+
+## Content Blocks
+
+- **Block Types**:
+  - Rich Text: WYSIWYG editor blocks for formatted text content.
+  - Image & Hero: Full-width and inline image banners with captions and alt text.
+  - HTML & CSS: Custom markup and style overrides for advanced layouts.
+  - Template: Predefined layouts with nested block placeholders.
+  - **Future**: Multi-column layouts, embedded content (iFrame), video/audio players, maps, forms, and dynamic lists (people, communities, pages, events).
+- **Special Blocks**: Platform-wide CSS overrides, funder acknowledgments, and legal disclaimers.
+- **Editor Interface**: Assign unique identifiers, apply style presets, and configure block-specific fields (e.g. image upload, rich-text area).
+
+## Pages
+
+- **Page Management**: Browse, create, duplicate, or delete CMS pages with metadata (title, slug, template).
+- **Block Editor**: Drag-and-drop content blocks, reorder sections, and configure hero banners inline.
+- **Publishing Controls**: Schedule publication dates, toggle draft mode, and restrict page visibility by role or community.
+- **Navigation Assignment**: Attach header or sidebar navigation areas per page for context-sensitive menus.
+
+## Resources
+
+- **Resource Library**: Upload, tag, and categorize downloadable files; version control via uploads history.
+- **Access Control**: Set download permissions by role and community membership.
+
+## Events
+
+- **Event Setup**: Define event title, rich-text description, schedule (start/end times), and registration URL.
+- **Location & Mapping**: Attach physical or virtual locations, geocode addresses, and embed map widgets.
+- **Media & Gallery**: Upload event images or cover photos and set default display sizes.
+- **Visibility Settings**: Publish events immediately or schedule publishing; restrict view by community or role.
+
+## Maps
+
+- **Map Integration**: Embed interactive maps showing community boundaries, partner locations, or custom geospatial layers.
+- **Customization**: Choose map styles, clusters, and pop-up templates for location markers.
+
+---
+
+For more detailed API reference and code examples, see the [Models & Concerns Overview](models_and_concerns.md) and the [Mermaid diagram](models_and_concerns_diagram.mmd).

docs/guide.md

@@ -0,0 +1,9 @@
+# Better Together Community Engine Documentation Guide
+
+This set of guides walks you through the core features of the Better Together Community Engine, organized under three main areas:
+
+- [Host Management](host_management.md)
+- [Community Management](community_management.md)
+- [Content Management](content_management.md)
+
+Use the links above to navigate to detailed instructions and reference materials for each feature.

docs/host_management.md

@@ -0,0 +1,87 @@
+# Host Management
+
+This section covers all administrative features available to platform hosts.
+
+## Host Navigation
+
+The host navigation bar provides quick access to key administrative areas:
+
+- **Dashboard**: View high-level metrics, recent activity logs, and shortcuts to common tasks.
+- **Communities**: Create and manage community instances, configure privacy and membership settings.
+- **Navigation Areas**: Define and publish header, footer, and sidebar menus with nesting and visibility controls.
+- **Pages**: Build and maintain CMS pages using the block editor, schedule publishing, and assign navigation.
+- **People**: Search and edit person records, manage profiles, community memberships, and special access flags.
+- **Platforms**: Configure platform-wide metadata (name, description, logo) and global privacy/invitation rules.
+- **Roles**: Establish user roles at platform and community levels, specifying purpose and default privileges.
+- **Resource Permissions**: Assign fine-grained CRUD permissions on resources to defined roles for access control.
+- **Resources**: Upload, categorize, and version downloadable assets (PDFs, images, reports) for reuse.
+- **Content Blocks**: Review and configure reusable block types (rich text, images, templates, etc.) for the page editor.
+- **Metrics Reports**: Generate CSV exports and view charts for page views, link clicks, downloads, and shares.
+
+## Dashboard Overview
+
+### Newcomer Navigator NL
+
+- **Partners**: Onboard partners by creating profiles with names, descriptions, logos, and geo-coordinates.
+- **Resources**: Curate newcomer assets (guides, checklists, videos) and control download permissions.
+- **Journey Stages**: Outline sequential phases of the newcomer experience, assign stage labels and ordering.
+- **Topics**: Tag resources and pages with topic labels for easier filtering and discovery.
+- **Journey Maps**: Build visual flowcharts mapping stages, topics, and resource links to guide newcomers.
+
+### Better Together Core
+
+- **Communities**: Spin up new community sites, configure membership rules, customize branding and privacy.
+- **Navigation Areas**: Manage site-wide menu structures, assign them to layouts or specific pages.
+- **Pages**: Author content pages with drag-and-drop block editing, manage drafts and publish schedules.
+- **Platforms**: Update platform metadata (name, logo, description), set language/localization defaults.
+- **People**: Administer person records, view activity logs, reset access, and manage guest access tokens.
+- **Roles & Permissions**: Define role-based access rules, map permissions to resources, and cache policy for performance.
+- **Users, Conversations & Messages**: Monitor registered users, initiate or audit conversation threads, and review message history.
+- **Categories**: Create and manage taxonomy for content and events to improve discoverability.
+
+## Platform Details
+
+Under **Platforms**, edit these platform settings:
+
+- **Name & Description**: Set the display name, subtitle, and descriptive text for the platform header and meta tags.
+- **Privacy Settings**: Choose whether the platform is public, private (invite-only), or hidden from unregistered users.
+- **Invitation Requirements**: Toggle whether users need an invitation code to register or if self-registration is open.
+
+## Roles & Permissions
+
+Roles and permissions are managed independently at the platform and community levels to provide scoped access control.
+
+### Platform Roles & Permissions
+- Define global roles that apply across the entire platform, then grant or revoke specific resource permissions per role to control CRUD access.
+
+### Community Roles & Permissions
+- Create roles scoped to individual communities and assign permissions to control access to community-specific features and content.
+
+> **Note:** Permission checks are cached per role to optimize database performance and reduce authorization overhead.
+
+## User Accounts
+
+- **List**: View all registered users, filter by status, role, or last sign-in date.
+- **Registration & Sign In**: Configure email workflows for user onboarding, password resets, and account confirmations.
+- **Profiles**: Enable users to update personal information (avatar, contact info, preferences) and manage privacy settings.
+
+## Metrics & Reporting
+
+- The engine collects and visualizes these core metrics:
+
+- **PageView**: Measures views on pages, people, communities, and partners. Available charts include views by page (bar) and daily totals (line).
+- **LinkClick**: Logs each tracked link interaction with charts for clicks by URL and daily trends.
+- **Download**: Records downloads of resources and exported reports with charts of downloads by file name.
+- **Share**: Tracks share button clicks per social platform, offering charts for shares by platform and per-URL breakdowns.
+
+All metrics support date-range filtering and locale-specific breakdowns, with CSV export for offline analysis.
+
+**Future reports** will include user engagement dashboards, invitation conversion analytics, partner link-click reports, and additional metric types such as search queries and journey map interactions.
+
+## Search & Notifications & Caching
+
+- **Search**: Full-text search powered by Elasticsearch, indexing pages, posts, people, and events with faceted filtering support.
+- **Notifications**:
+  - **Email**: Configurable notification templates for actions such as invitations, mentions, and password resets.
+  - **In-app**: Real-time alerts delivered via ActionCable with both ephemeral toast messages and persistent notification feeds.
+- **Caching**: Implements fragment and page caching for navigation and content blocks, with Redis-backed cache stores and optional CDN integration to speed up delivery.