# berkmancenter/frankly architecture

> Architecture diagram of the GitHub repository berkmancenter/frankly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/berkmancenter/frankly
- Repository: https://github.com/berkmancenter/frankly

## Overview

##### Project type and purpose
- Frankly is a full-stack, web-based deliberations platform
- Client: Flutter web application (client/)
- Backend: Firebase services (Firestore, Auth, Hosting), Cloud Functions (Dart), plus a standalone “matching” microservice
- Shared models: data_models/ library used by both client and functions
- External integrations: Agora for video chat, Mux for livestream, Stripe for payments, Typeform, calendar feeds

##### File structure
- Top-level directories:
– client/: Flutter code (core/data/services, features/, presentation/views, utils, widgets)
– firebase/firestore/: Firestore rules & indexes
– firebase/functions/: Cloud Functions in Dart, organized by domain (community, events, live_meetings, templates, utils, infra)
– matching/: separate microservice (Dart/Node) for participant-to-breakout matching
– data_models/: shared Dart data classes (admin, events, chat, community, etc.)
– e2e/: Playwright test fixtures and page-object tests
– docs/: MkDocs site content
- Patterns spotted:
– Layered frontend (data providers → services → presenters → UI)
– Domain-based Cloud Functions, triggered by Firestore writes or HTTP/HTTPS calls
– Shared schemas in data_models/

##### Extract architecture hints from README
- Purpose: host video-enabled conversations, match participants into breakout rooms, structured event templates
- AGPL-licensed, external dependencies chosen accordingly
- Encourages reading the online docs for high-level overviews

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Flutter["Flutter Web Client"]:::client
        AgoraSDK["Agora SDK (WebRTC)"]:::client
        TypeformWidget["Typeform Widget"]:::client
    end

    %% Shared Models
    subgraph "Shared Models"
        DataModels["Shared Data Models"]:::shared
    end

    %% Firebase Managed Services
    subgraph "Firebase Managed Services"
        direction TB
        Hosting["Firebase Hosting"]:::firebase
        Auth["Firebase Auth"]:::firebase
        FirestoreDB["Firestore Database"]:::firebase

        subgraph "Firestore Configuration"
            FIConfig["Config"]:::firebase
            Rules["Rules"]:::firebase
            Indexes["Indexes"]:::firebase
        end

        subgraph "Cloud Functions"
            direction TB
            CF_Comm["Cloud Functions\n(Community Domain)"]:::functions
            CF_Events["Cloud Functions\n(Events Domain)"]:::functions
            CF_Disc["Cloud Functions\n(Discussion Threads)"]:::functions
            CF_Temp["Cloud Functions\n(Templates Domain)"]:::functions
            CF_Admin["Cloud Functions\n(Admin/Payments)"]:::functions
            CF_Infra["Cloud Functions\n(Utils & Infra)"]:::functions
            CF_Calendar["Cloud Functions\n(Calendar Feeds)"]:::functions
            CF_Mux["Cloud Functions\n(Mux Webhooks)"]:::functions
        end
    end

    %% Matching Microservice
    subgraph "Matching Service"
        direction TB
        MS_Func["Matching Microservice\n(Functions)"]:::micro
        MS_Lib["Matching Microservice\n(Library)"]:::micro
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AgoraAPI["Agora REST API"]:::third
        MuxAPI["Mux Livestream"]:::third
        StripeAPI["Stripe API"]:::third
        TypeformAPI["Typeform"]:::third
        CalFeeds["Calendar Feeds"]:::third
    end

    %% Other
    subgraph "Other"
        direction TB
        E2E["E2E Tests"]:::other
        Docs["Documentation (MkDocs)"]:::other
    end

    %% Connections
    Flutter -->|"OAuth / ID Tokens"| Auth
    Flutter -->|"Firestore SDK"| FirestoreDB
    Flutter -->|"HTTPS Callable"| CF_Events
    CF_Events -->|"calls Agora REST"| AgoraAPI
    CF_Events -->|"calls Mux Webhooks"| MuxAPI
    CF_Admin -->|"calls Stripe API"| StripeAPI
    CF_Calendar -->|"fetches feeds"| CalFeeds
    CF_Infra -->|"schedules email tasks"| E2E
    FirestoreDB -->|"onCommunityWrite"| CF_Comm
    FirestoreDB -->|"onEventWrite"| CF_Events
    FirestoreDB -->|"onDiscussionWrite"| CF_Disc
    CF_Events -->|"calls Matching Service"| MS_Func
    MS_Func --> MS_Lib
    DataModels --> Flutter
    DataModels --> CF_Comm
    DataModels --> CF_Events
    DataModels --> MS_Lib
    E2E -->|"tests client and functions"| Flutter
    Docs -->|"provides docs"| Flutter

    %% Click Events
    click Flutter "https://github.com/berkmancenter/frankly/tree/staging/client/"
    click DataModels "https://github.com/berkmancenter/frankly/tree/staging/data_models/"
    click Hosting "https://github.com/berkmancenter/frankly/blob/staging/firebase.json"
    click FIConfig "https://github.com/berkmancenter/frankly/tree/staging/firebase/firestore/"
    click Rules "https://github.com/berkmancenter/frankly/blob/staging/firebase/firestore/firestore.rules"
    click Indexes "https://github.com/berkmancenter/frankly/blob/staging/firebase/firestore/firestore.indexes.json"
    click CF_Comm "https://github.com/berkmancenter/frankly/tree/staging/firebase/functions/lib/community/"
    click CF_Events "https://github.com/berkmancenter/frankly/tree/staging/firebase/functions/lib/events/"
    click CF_Disc "https://github.com/berkmancenter/frankly/tree/staging/firebase/functions/lib/discussion_threads/"
    click CF_Temp "https://github.com/berkmancenter/frankly/tree/staging/firebase/functions/lib/templates/"
    click CF_Admin "https://github.com/berkmancenter/frankly/tree/staging/firebase/functions/lib/admin/payments/"
    click CF_Infra "https://github.com/berkmancenter/frankly/tree/staging/firebase/functions/lib/utils/infra/"
    click CF_Infra "https://github.com/berkmancenter/frankly/blob/staging/firebase/functions/lib/utils/send_email_client.dart"
    click CF_Calendar "https://github.com/berkmancenter/frankly/tree/staging/firebase/functions/lib/events/calendar/"
    click CF_Mux "https://github.com/berkmancenter/frankly/blob/staging/firebase/functions/lib/events/live_meetings/mux_webhooks.dart"
    click MS_Func "https://github.com/berkmancenter/frankly/tree/staging/matching/functions/"
    click MS_Lib "https://github.com/berkmancenter/frankly/tree/staging/matching/lib/"
    click AgoraSDK "https://github.com/berkmancenter/frankly/blob/staging/client/web/agora/iris-web-rtc.js"
    click TypeformWidget "https://github.com/berkmancenter/frankly/blob/staging/client/lib/features/events/features/live_meeting/presentation/widgets/typeform_widget.dart"
    click E2E "https://github.com/berkmancenter/frankly/tree/staging/e2e/"
    click E2E "https://github.com/berkmancenter/frankly/tree/staging/e2e/pages/"
    click E2E "https://github.com/berkmancenter/frankly/tree/staging/e2e/tests/"
    click Docs "https://github.com/berkmancenter/frankly/tree/staging/docs/"

    %% Styles
    classDef client fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px
    classDef shared fill:#CFD8DC,stroke:#455A64,stroke-width:2px
    classDef firebase fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px
    classDef functions fill:#A5D6A7,stroke:#2E7D32,stroke-width:2px
    classDef micro fill:#E0E0E0,stroke:#424242,stroke-width:2px
    classDef third fill:#FFE0B2,stroke:#E65100,stroke-width:2px
    classDef other fill:#D1C4E9,stroke:#4A148C,stroke-width:2px
```
