fplaces Frontend Integration Guide

Backend Engineer: Sunday Ajayi

This guide breaks down the division of responsibilities between the stateless REST API (used for fetching static data and initiating actions) and the WebSocket layer (used exclusively for receiving real-time live updates).

All REST endpoints require the Authorization: Bearer <access_token> header, and all WebSockets require the token to be passed as a query parameter ?token=<access_token>.

PART 1: Fan / User Application

This section covers the standard mobile or web application used by venue visitors.

1. Setup, Authentication, & Onboarding (REST)

The authentication flow uses SimpleJWT. The backend is stateless, so your client must store the access and refresh tokens securely.

• Register: POST /api/users/register/ (Provide email and password). User is created but is_email_verified is False.
• Verify Email: POST /api/users/verify-email/ (Provide email and the 6-digit otp sent to their email).
• List Interests: GET /api/forum/interests/ (Public, no auth required). Returns the curated catalog of interests (id, name, slug, order) to render as picker tags — no longer hardcoded on the frontend.
• Profile Setup: PATCH /api/users/me/ (Provide pseudo_name and optionally interests, an array of interest names picked from the catalog above). Setting pseudo_name is required before the user can post.
• Fetch Own Profile: GET /api/users/me/. Besides the standard profile fields and interests, the response includes:
  • stat: {"posts_count": 86, "upvotes_count": 3200, "venues_count": 14} — drives the stat cards at the top of the profile screen.
  • recent_posts: the user's 5 most recently created posts (full post objects, newest first) — drives the "Recent Posts" list on the profile screen.
• Standard Login: POST /api/users/login/ (Provide email and password). Returns an access/refresh JWT pair plus the user's profile embedded under user, so no separate GET /api/users/me/ call is needed right after login.
• Google Login: POST /api/users/login/google/ (Provide Google OAuth id_token). Automatically registers/logs in the user and returns the standard JWT tokens.
• Refresh Token: POST /api/users/token/refresh/ (Provide refresh). Returns a new access token once the old one expires (after 30 minutes).
• Logout: POST /api/users/logout/ (Provide refresh). Blacklists the refresh token; discard the access token locally too since it stays valid until it naturally expires.
• Forgot Password: POST /api/users/password-reset/ (Provide email). Emails a uid/token reset link. Always returns a generic 200 regardless of whether the email exists, to avoid leaking account existence.
• Reset Password: POST /api/users/password-reset-confirm/ (Provide uid, token, and new_password from the reset link).
• Change Password: POST /api/users/change-password/ (Provide old_password and new_password). For a logged-in user changing their password without the email round-trip.
• Guest Access: POST /api/users/guest/ (Provide ip_address and device_fingerprint). Returns a short-lived guest JWT, trial expiration info (including has_2d_trial_expired), and MappedIn keys. The guest session trial expires at the end of the day.
• Update Guest Preferences: PATCH /api/users/guest/update/ (Provide has_tried_ar_view or has_tried_2d_view). Updates guest tracking flags. Requires the guest JWT in the Authorization header.

2. Venue Selection & Initial Feed Load (REST)

When a user opens the app and selects a venue, fetch the historical state of that venue.

• List Venues: GET /api/forum/venues/ (Fetch available stadiums/arenas).
• List Sections: GET /api/forum/sections/?venue=<venue_id>
• List Categories: GET /api/forum/categories/ (Category objects include an icon_url field).
• Fetch Initial Feed: GET /api/forum/posts/?venue=<venue_id> (Paginated historical posts).
• Get Map Token: GET /api/maps/token/ (Authenticated). Returns a short-lived MappedIn token used to render the venue's interactive 2D/AR map. Guests get an equivalent token bundled directly into their POST /api/users/guest/ response instead of calling this separately.

3. The Live Feed & Heatmap (WebSocket)

Immediately after fetching the initial feed, establish a WebSocket connection to the venue's room:
ws://<domain>/ws/venues/<venue_id>/?token=<access_token>

You never send data up this socket. It is purely for receiving live JSON broadcasts:

1. new_post:
   • Payload: The full JSON object of the newly created post.
   • Action: Unshift/prepend it to your feed state.
2. upvote_update:
   • Payload: {"post_id": 123, "upvotes_count": 5, "upvoted": true}
   • Action: Find post 123 in your state and update its count.
3. post_hidden:
   • Payload: {"post_id": 123}
   • Action: Immediately remove post 123 from the UI.
4. section_heat_update:
   • Payload: {"heatmap": [{"section_id": 4, "post_count": 8, "priority": "high"}, ...]}
   • Action: Overwrite your entire UI venue map state with this array. Map the priority string ("high", "medium", "low") directly to your CSS glowing colors. Any missing section ID has 0 posts and is neutral.
5. presence_update:
   • Payload: {"online_count": 42}
   • Action: Dynamically update the "live users" counter shown on the venue map screen. This tracks unique users actively connected to the venue room.

4. Comments (WebSocket & REST)

Each post has its own flat (1-level) comment thread. Unlike section conversations, comments are broadcast over the same venue room used for the live feed (Part 1, Section 3) rather than a socket of their own.

• Fetch Comments: GET /api/forum/comments/?post=<post_id> (Paginated, oldest first).
• Post a Comment: POST /api/forum/comments/ (Provide post and content, max 500 chars). Triggers new_comment on the post's venue WebSocket room, and creates a comment notification for the post's author (delivered over the personal notifications socket in Section 6) unless they're commenting on their own post.
• WebSocket Event (new_comment): Received on the venue room, not a separate socket.
  • Payload: The full JSON object of the newly created comment.
  • Action: Append it to that post's comment thread if it's currently open.

5. User Interactions (REST)

When the user does something, fire a REST request. If successful, the backend automatically broadcasts the result over the WebSocket.

• Create Post: POST /api/forum/posts/ (Provide content max 140 chars, venue, category, and optional section). Triggers new_post and section_heat_update on the socket.
• Toggle Upvote: POST /api/forum/posts/<post_id>/upvote/. This is idempotent. Triggers upvote_update on the socket.
• Flag Post: POST /api/forum/posts/<post_id>/flag/ (Provide optional reason). If it hits 3 unique flags, it auto-hides and Triggers post_hidden and section_heat_update on the socket.

6. Personal Notifications (WebSocket & REST)

Users have a personal WebSocket for cross-venue, account-level alerts.

• Connect: ws://<domain>/ws/notifications/?token=<access_token>
• WebSocket Event (new_notification): Pushes a notification object in real-time so you can increment the unread badge count.
• REST Fetch: GET /api/notifications/ (List paginated notification history, newest first).
• REST Unread Count: GET /api/notifications/unread_count/ (Lightweight {"unread_count": 3} for badge rendering without paginating the full list).
• REST Mark Read: POST /api/notifications/<id>/mark_read/ or POST /api/notifications/mark_all_read/.

7. Location (Map Pin) Conversations (WebSocket & REST)

Map-area chat is keyed by (venue, location_id), where location_id is the Mappedin location/place id the fan tapped on the map — not an admin Section PK (see Part 1, Section 2 for those). The client never creates a conversation id and never needs an admin to pre-seed anything for a location: the first message for a never-seen location_id auto-creates its channel.

• Fetch History: GET /api/forum/conversations/?venue=<venue_id>&location_id=<location_id> (Both params required. Paginated, newest first. Returns an empty list with 200, never a 404, if nobody has posted at that location yet — a channel is only created by POST.)
• Post a Message: POST /api/forum/conversations/ (Provide venue, location_id, content (max 500 chars), and optionally location_name). Finds-or-creates the (venue, location_id) channel, then stores the message. location_name only sets the channel's display name on first create (or backfills it if still blank) — it's ignored otherwise. Triggers new_location_message on that location's socket.
• Connect: ws://<domain>/ws/venues/<venue_id>/locations/<location_id>/?token=<access_token> (URL-encode location_id). Subscribe only once the user actually opens that location's chat — don't pre-subscribe to every pin on the map.
• WebSocket Event: {"type": "new_location_message", "message": { ...same shape as the POST response... }}
  • Action: Append message to that location's conversation state.
• WebSocket Event (presence_update):
  • Payload: {"online_count": 5}
  • Action: Update the "live users" indicator showing how many unique users are actively viewing this location's conversation.

Admin Sections (North Stand / South Stand / VIP) are unaffected and still used for onboarding, the venue post feed's optional section, and the heatmap — they are a separate, much smaller catalog and are never auto-created from map pins.

PART 2: Admin / Moderator Dashboard

This section covers the web-based administrative panel used by staff. Accessing these endpoints requires an account with is_staff=True or user_type=admin.

1. Dashboard Authentication (REST)

Admins log in using the exact same login endpoints as users (POST /api/users/login/). Ensure your dashboard checks if the decoded JWT belongs to an admin before allowing entry.

2. Platform Statistics Overview (REST)

Used to render the charts and metric cards on the admin homepage.

• Fetch Dashboard Stats: GET /api/admin/stats/
  • Returns: Aggregated metrics including total registrations, verified users count, total posts/comments, and categorical breakdowns of activity.

3. Content Moderation (REST)

Admins have elevated visibility into all content, including posts hidden from the public.

• View Moderation Queue: GET /api/admin/posts/flagged/
  • Fetches posts sorted descending by flags_count. This is your primary moderation queue.
• Hide Post: POST /api/admin/posts/<post_id>/hide/
  • Removes the post from the public feed immediately. Triggers the post_hidden and section_heat_update WebSocket events for active fans.
• Show/Unhide Post: POST /api/admin/posts/<post_id>/show/
  • Reverses a manual or auto-hide.
• Clear Flags: POST /api/admin/posts/<post_id>/clear-flags/
  • Resets a post's flags_count to 0 and archives the flag tickets after a moderator has reviewed it and deemed it safe.

4. User Management (REST)

Complete control over user accounts.

• List Users: GET /api/admin/users/ (Fetch all users, paginated, including archived/unverified accounts).
• Archive User: DELETE /api/admin/users/<user_id>/ or POST /api/admin/users/<user_id>/archive/ (equivalent). Soft-deletes the user (is_archived=True), disabling their login without touching their posts/comments.
• Restore User: POST /api/admin/users/<user_id>/restore/
• Toggle Staff Status: POST /api/admin/users/<user_id>/toggle-staff/ (Flips is_staff to its opposite value; call again to toggle back).

5. Broadcast Notifications (REST)

Send a targeted push and/or email blast to users matched by venue, section, category, or explicit user ids (a union of whichever filters are provided — at least one is required).

• Send Broadcast: POST /api/admin/notifications/ (Provide subject, message, channels (["email", "push"]), and at least one of venue, section, category, or users).
  • Push channel creates a broadcast-verb Notification per matched user, delivered live over their ws/notifications/ socket.
  • Returns: {"users_targeted": 50, "email_sent": 48, "push_sent": 50}. Delivery is best-effort per user/channel — one failed send doesn't stop the rest of the broadcast.