Community setup

Appmint Community is a members' social space on the business's own website. A page (community_page) is one community: a club, a customer group, a brand, a venue or an event. Each page has members, a feed of posts with comments and reactions, stories, announcements, group chats and meetups. Connections, direct messages, follows, bookmarks and badges belong to the person, not to one page.

Members are customers signed in on the site. Everything is keyed by their email. Staff run it from Studio's Community app (/community). The API has two parts:

• client/community/…: what members do (community/community-client.controller.ts). With call_appengine these calls act as the signed-in staff person, by their email.
• community/…: connections, messages, meetings, blocks, plus the staff-only report review (community/community.controller.ts).

Studio's tabs save records with the ordinary repository create and update. The engine reacts to those saves: approvals, role changes, invitations, moderation notices and bans. So repo_create and repo_update do what Studio does. update-partial doesn't: it fires none of those reactions.

Related pages:

• EventOxygen's view of the same community (the event's page, the attendee app): Community management, The feed, Networking.
• Comments and reviews on blog posts and products are a different system: Moderate comments and reviews.
• The site's chat widget is a different system: Live chat on the website.

Ask first

• What is the community, and who is it for? Its name, a one-line description, a cover picture and logo, and its type: group, brand, topic, venue, organization, personal or other. Event pages make themselves (step 2).
• Who can see it? Anyone, including people who aren't signed in (public). Only members, while outsiders see a card and can ask to join (private). Or hidden from everyone who isn't a member (invite only).
• Who can join? Anyone, people approved by an admin, or people invited only.
• Who can post? Anyone signed in, members, or admins only. Are posts held for approval, or held only when someone reports them?
• Who runs it? The email of the owner, and of any admins and moderators. These must be the emails they sign in to the site with.
• Which parts are on: stories, group chat, announcements.
• The address: /community, or another page name on the site.
• Who to invite now, if anyone. Each invitation is an email.

Steps

1. Website: switch on the Community feature

The members' side is a built-in site page (base-app components/community/CommunityRoute.tsx). It sits inside the site's header and footer. It reads ?page=<slug or id> to open one community and ?tab= (feed, members, groups, meetups, messages). Without ?page= it opens the member's busiest community, else the busiest one on the site.

It answers only while the site's community feature is on. With the feature off, /community is a 404 (tested on the local site). To switch it on, add a row to site.data.features:

{ "feature": "community", "enabled": true, "page": "community" }

page is optional. It moves the address to /<page>. How to write the features list without losing the site's other settings, and how addresses are claimed: Site page routing. In Studio: Site Config › Features › Community.

Stop: switching it on publishes a page on the live site. Say the address and wait for yes.

Hands on: the community's address. Check: repo_find_one on the site shows the community row. Opening the address shows the community, or "No community pages yet." when there are none.

2. Community › Pages: the page

The way that also makes the owner: call_appengine POST /client/community/pages. The signed-in person becomes the page's owner (a member with role owner), and the slug is made from the title. Tested: a staff sign-in made james@… the owner, and could then post and announce.

{
  "title": "Saturday Runners",
  "type": "group",
  "shortDescription": "Easy 5k every Saturday at 8",
  "description": "<p>…</p>",
  "coverImage": "https://…/cover.jpg",
  "logo": "https://…/logo.png",
  "visibility": "private",
  "joinPolicy": "approval_required",
  "postingPolicy": "members",
  "moderationLevel": "flagged_only",
  "status": "active",
  "features": { "storiesEnabled": true, "chatEnabled": true, "announcementsEnabled": true }
}

In Studio (Community › Pages › Add Page): Studio's form starts with status: active, visibility: public, joinPolicy: open, postingPolicy: members, moderationLevel: none, and chat off. It makes no owner. Tested: a page saved this way had no members. Add the owner in step 3.

The rules:

The page's owner or an admin changes it later with PUT /client/community/pages/<id>. Only these fields are taken: title, slug, type, description, shortDescription, category, tags, status, coverImage, logo, images, visibility, joinPolicy, postingPolicy, moderationLevel, features, website. Anything else is refused: "No supported page fields supplied" (tested). A non-admin is refused with "Page administrator required" (tested). Staff can edit any page in Studio, or with repo_update on community_page.

Hands on: the page's sk and slug. Check: GET /client/community/pages?limit=50 lists it. Studio's Community › Pages shows it with its visibility and status. On the site, /<community page>?page=<slug> opens it.

3. Community › Pages › Members: owner, staff and members

The Members section is in the page's Edit Page drawer (it shows once the page is saved).

Roles are owner, admin, moderator, member, guest:

Membership status is active, pending (asked to join), invited, banned or left. Only active counts.

Add the owner or staff to a page made in Studio. repo_create on community_page_member:

{ "page": "<page sk>", "email": "[email protected]", "role": "owner", "status": "active",
  "source": "manual", "name": "<page sk>:[email protected]", "joinedAt": "<now>", "notificationPreference": "all" }

This sends nothing. The page's member count isn't recounted on a create (tested: it stayed one short). It catches up at the next join, leave or approval.

Make someone an admin or moderator. They must be an active member. On screen: their role picker in the page's Members. By API: repo_update on their member record with { "role": "moderator" }. They get the notice "You're now a moderator of …".

Approve or decline a join request. On screen: Members › Requests, then Approve or Decline. By API, approve with repo_update { "status": "active", "joinedAt": "<now>" }. Tested: they got "You're in! Your request to join … was approved", and the member count went up. Decline deletes the request record.

Invite. On screen: Members › Invite, then pick a customer. By API: POST /client/community/pages/<id>/invite { "email" }, as an owner or admin. Either way the member record is saved as invited, and the person gets the community-invitation email and an in-app notice. Tested: one email, subject "You're invited to join ", linking …/community?page=<slug>. They accept by pressing Join on the page, which also works when the page is invite_only (community-page.service.ts 268–292).

Stop before inviting. Each invitation emails a real person. Show the list and wait for yes.

Remove or ban. A member leaves with POST …/pages/<id>/leave. An owner or admin removes someone with the same route. On screen, Ban sets status: banned. A banned person can't rejoin ("Membership is banned"). Restore sets them back to active.

Hands on: who is owner, admin and moderator. Check: GET /client/community/pages/<id>/members (?role=) lists the active members with name and photo. Studio's Members tabs show Members, Requests, Invited and Banned.

4. Community › Announcements: news for the members

As a page owner or admin: POST /client/community/pages/<id>/announcements. This is published at once. In Studio: Community › Announcements › New Announcement, which starts as Draft.

Stop before publishing. Publishing (on create, or a draft saved as published) gives every active member it targets an in-app notice. On a public page, anyone can read it, even signed out. Tested: "Important: Route change — Saturday Runners" reached the member, the author got no notice, and an admins announcement was hidden from a plain member. Show the text and audience, and wait for yes. An announcement is announced once. Later edits don't notify again.

Check: GET /client/community/pages/<id>/announcements as a member lists it.

5. Community › Feed and Moderation: posts and reports

Members post from the site (POST /client/community/posts with page, content, media, contentType text/image/video/link/poll, poll). #tags in the text become hashtags. A post on a page is visibility: page. That means "on this page", not "members only": on a public page it is readable signed out. A page post can't be shared to the global feed ("This post cannot be shared publicly", tested).

Staff actions (Community › Feed, or repo_update on community_post):

Reports. A member reports another member with POST /client/community/reports { reportedId, reason, details, context: { postId?, page? } }. reason is spam, harassment, inappropriate, unwanted_contact or other. reportedId is the customer's sk or email. Or they block someone and report in one step: POST /client/community/blocks with report: true. If the report names a post on a flagged_only or pre_approve page, that post is held as flagged at once. Tested: it left other people's feeds, and its author still saw it.

Staff see pending reports in Community › Moderation, or call_appengine GET /community/reports (staff only). The decisions:

By API, do it as Studio does. repo_update the report (community_block) with its whole report object ({ ...report, status, action, reviewedAt }) and reportStatus. Then remove the post (repo_update on the post, status: removed) for a ban or content removal. repo_update replaces report whole, so read it first.

Stop before a warning, a ban or a removal. Each one tells the member, and a ban also ends their membership. Say who, what they did and which page or pages, and wait for yes.

Hashtags. Community › Hashtags bans a tag (community_hashtag status: banned). Posts with it are then refused: "#skilltest isn't allowed in this community" (tested, any case). It also drops out of trending.

Check: Community › Moderation shows the report as action taken or dismissed. GET /client/community/feed?page=<id> as another member shows the post gone or back.

6. Community › Badges: rewards that award themselves

repo_create on community_badge (or Community › Badges › New Badge):

{ "title": "First Post", "description": "Posted for the first time", "criteria": "Post once",
  "category": "engagement", "rarity": "common", "icon": "🏃",
  "criteriaType": "posts_count", "criteriaValue": 1, "autoAward": true, "status": "active" }

criteriaType that award: posts_count, comments_count, stories_posted, pages_joined, messages_sent, connections_count, meetings_attended, reactions_received (community-badge.service.ts 12–21). A member earns the badge the moment their next action of that kind reaches criteriaValue. They get the notice "You earned the First Post badge — Post once", and earnedBy goes up. Tested. Awards aren't back-dated: a member who already qualified gets it only at their next post, comment, and so on (tested). status: retired hides a badge.

Check: GET /client/community/badges/mine as the member. The site shows earned badges beside the feed.

7. Community › Groups and Meetings: chats and meetups

These are made as page staff, by the owner, an admin or a moderator, through the member routes:

• Group chat: POST /client/community/groups { page, title, members: [{ email }], maxMembers?, onlyAdminsCanPost?, allowMediaSharing? }. Every member must be an active page member ("… is not a member of this community"), and the page's chat must be on. Tested. Each message notifies the other group members in-app.
• Meetup: POST /client/community/meetings { page, title, participantIds: [customer sk or email], startTime, duration (minutes), timezone, location or meetingLink, locationType }. Participants must be page members. A page meetup is confirmed at once, and the end time is worked out from the duration. Tested: each invitee got " invited you to