Casper Docs

01

Overview

What Casper is

Casper is a Flutter application backed by Firebase. The codebase covers content delivery, commerce, community interactions, messaging, support, ticketing, and profile management.

Cross-platform Flutter client with dedicated mobile and web support.
Firebase Authentication for user identity and session bootstrap.
Firestore-backed social, commerce, CMS, and messaging features.
Firebase Storage for user-uploaded media and content assets.

Primary audience for this documentation

Engineers onboarding into the product.
Operators deploying the app or changing Firebase configuration.
Product owners reviewing what the platform currently supports.
Maintainers troubleshooting runtime, media, or release issues.

02

Product Surface

Content and CMS

Home feed, latest news, article detail, CMS content, media, courses, and videos.

Community

Communities, posts, comments, reactions, memberships, and community UI variants.

Messaging

Direct chat, group chat, unread indicators, shared media, and support chat surfaces.

Commerce

Shop, cart, product detail, checkout, order success, vouchers, and wallet-style flows.

Agenda and Ticketing

Agenda overview, event detail, ticket completion, and order-linked user flows.

Identity and Profile

Login, onboarding, edit profile, preferences, interests, and account-level settings.

03

Architecture

Flutter Client

UI, routing, local state, theming, animations, and feature modules.

->

Firebase Services

Authentication, Firestore, Storage, Messaging, Functions, Hosting.

->

Operational Tooling

Fastlane, Firebase CLI, platform config, and deployment scripts.

Client: Flutter app in lib/
Backend: Firebase project brolliance-cecd6
Infra config: firebase.json, .firebaserc, firestore.rules
iOS release: ios/fastlane/
Web entry: web/
Docs hosting: docs/

04

How the CMS works

Service layer

The CMS integration lives under lib/backend/cms/. The app talks to https://digitalradicalz.onrender.com through a singleton service that wraps HTTP requests, request normalization, caching, and error handling.

Endpoints include news, events, products, media, posts, courses, and categories.
Requests use a 30-second timeout and shared JSON headers.
Concurrent identical requests are deduplicated to avoid duplicate fetches.
Responses are cached for five minutes to reduce repeated traffic.

Provider layer

CmsProvider is the app-facing state container. It tracks loading flags, cache-backed collections, pagination state, and per-domain error messages.

Separate loading state for news, events, products, media, posts, and courses.
Refresh-aware pagination for list experiences.
Featured and filtered fetch paths for editorial surfaces.
Simple consumer pattern for screens like cms_content_widget.dart.

Content normalization

CMS models are defensive. The app maps inconsistent payload keys into stable Dart models like CmsNews, CmsEvent, CmsProduct, and CmsMedia. That means editorial payload differences are absorbed in one place instead of leaking into UI code.

UI screen -> CmsProvider.fetchNews()\nCmsProvider -> CmsService.getNews(page, filters)\nCmsService -> HTTP GET /api/news\nJSON payload -> CmsNews.fromJson(...)\nProvider cache/state update -> Consumer rebuild

05

How the mobile application works

Navigation model

Route exports in lib/index.dart expose the app surface. Navigation is driven by GoRouter and organized around core product areas like home, community, media, shop, and chat.

State model

App-wide state is handled with Provider and generated FlutterFlow models. Domain-specific workflows use helper services for Firestore transactions, notifications, and CMS loading.

Data model

Firestore collections are represented by generated record classes under lib/backend/schema/, while richer flows use service classes under lib/firestore/services/.

Content rendering

The home screen blends live Firestore content, CMS-fed content, and user-generated posts. The UI is optimized for cards, carousels, modals, and bottom-sheet detail surfaces.

Identity bootstrap

On startup the app initializes Firebase, hydrates persisted app state, and falls back to anonymous auth when no user session exists outside screenshot mode.

Cross-platform behavior

Mobile remains the primary operating mode, while web is supported for review, publishing, and content access. The shell currently constrains web to an iPhone 14 Pro Max viewport for visual consistency.

Operational flow inside the app

main.dart bootstraps Firebase + theme + app state\nGoRouter resolves feature routes\nFeature screens read Firestore, CMS, or both\nWidgets render cards, detail sheets, and action flows\nUser actions write back through Firestore helpers, auth utilities, or storage uploads

06

Repository Map

`lib/pages/`

Feature entry screens such as home, shop, community, media, news, and agenda.

`lib/components/`

Reusable UI pieces, detail sheets, cards, profile surfaces, and shared widgets.

`lib/backend/`

Firebase config, schema records, storage helpers, and CMS provider integration.

`lib/firestore/`

Repositories and transactional service helpers beyond generated schema access.

`ios/fastlane/`

Automated TestFlight and App Store release lanes.

`docs/`

This deployable documentation website for Firebase Hosting.

07

Local Setup

Prerequisites

Flutter stable SDK
Dart SDK bundled with Flutter
Firebase CLI for Hosting and rules deployment
Xcode and Ruby/Bundler for iOS release work

Bootstrap

flutter pub get
flutter run -d chrome
flutter run -d ios
firebase use brolliance-cecd6

08

Firebase Stack

Project

brolliance-cecd6 is configured as the default Firebase project in .firebaserc.

Firestore

Schema records are generated under lib/backend/schema/ and protected by firestore.rules.

Storage

User media and uploaded files use Firebase Storage with rules under firebase/storage.rules.

Functions

Cloud Functions code lives under firebase/functions/ with a dedicated Firebase config there.

09

Release Workflows

iOS Release

Fastlane lanes already exist in ios/fastlane/Fastfile.

cd ios
bundle install
cp fastlane/.env.example fastlane/.env
bundle exec fastlane deploy_testflight
bundle exec fastlane deploy_appstore

Web Docs Release

The documentation website is intentionally static so it can be published without a frontend build pipeline.

Source is stored directly in docs/.
Firebase Hosting points to the same directory.
Deployment is a single CLI command once authenticated.

10

Hosting Deploy

Deploy this documentation website

Firebase Hosting is configured to serve the docs/ directory at the root of the default project.

firebase login
firebase use brolliance-cecd6
firebase deploy --only hosting

If you need a preview before production, run firebase hosting:channel:deploy preview-docs.

11

Operations

Media safety

Prefer image widgets with placeholders or error fallbacks on web. Raw DecorationImage(NetworkImage) is fragile.

Profile data

Profile updates now support country persistence plus dependent city selection in the edit profile form.

Unread chat state

Unread count aggregation is wired centrally in lib/main.dart from direct and group chat streams.

Web viewport

The app shell currently constrains web rendering to an iPhone 14 Pro Max viewport for product review consistency.

12

Troubleshooting

Web image loads fail but mobile works

Check Firebase Storage rules, CORS setup, and whether the widget uses an error-capable image renderer on web.

Firebase deploy fails locally

Confirm Firebase CLI is installed, you are authenticated, and the active project is brolliance-cecd6.

iOS release lane cannot find Flutter

Set FLUTTER_BIN in ios/fastlane/.env if Flutter is not available on the default shell path.

Generated schema is missing a new field

Update the schema record in lib/backend/schema/ and make sure all create/update helpers include the field.