Files
meet/docs/contributing/code-tour.md
T
unteem d06fddab56 📝(doc) create complete documentation website for Meet
Add a documentation site built with Zensical: getting started,
self-hosting with compose and Kubernetes, configuration, user guide,
contributing and reference pages, and every environment variable on
one page, grouped by feature.

Co-authored-by: davd-gzl <60177543+davd-gzl@users.noreply.github.com>
2026-11-16 10:59:49 +01:00

30 KiB

Code tour

Find each part of Meet's code in the repository before you change it. How Meet works explains how the parts work together, and Develop locally how to run them.

TL;DR

The Django backend is src/backend, the React frontend src/frontend, and LiveKit carries the media. The agents, the summary service and the Helm chart each have their own directory under src/.

The repository

meet/
├── src/
│   ├── backend/      Django application: API, rooms, recordings, LiveKit control
│   ├── frontend/     React application served to browsers
│   ├── agents/       LiveKit agents: live subtitles, metadata collector
│   ├── summary/      FastAPI service that transcribes and summarizes recordings
│   ├── sdk/          TypeScript SDK: a button that creates a Meet link in another app
│   ├── addons/       Outlook add-in
│   ├── mail/         MJML sources of the emails
│   └── helm/         Helm chart and the helmfile used for local Kubernetes
├── .github/          CI: pull request checks, image builds, Helm chart release
├── docker/           Dev Keycloak realm, LiveKit, nginx, Garage; DINUM frontend image
├── env.d/            Environment file templates, for development and production
├── bin/              Wrappers for docker compose, Tiltfile, release, Scalingo buildpack
├── deploy/           The nginx configuration template of the Scalingo deployment
├── crowdin/          The Crowdin configuration that syncs the translations
├── docs/             This site
├── gitlint/          The commit message rule CI applies
├── compose.yml       The development stack
├── Dockerfile        The backend image, development and production stages
├── Makefile          Every development command
├── CHANGELOG.md      One line per change, written in each pull request
└── UPGRADE.md        What an operator does when upgrading

Backend

A Django 5.2 project in three parts:

  • meet, the project, holds the settings and the root URLs.
  • core, an app, holds the code.
  • demo, a second app, holds the create_demo and createsuperuser commands that make demo and make superuser call.
Path under src/backend/ What it holds
meet/settings.py Every setting, read from environment variables through django-configurations; each variable is in Environment variables. DJANGO_CONFIGURATION picks the class: Development or Test locally, Production on a server
meet/celery_app.py The Celery application the celery-dev worker runs
core/models.py The data model, described under Models
core/api/ The REST API the frontend calls, under /api/v1.0/, built on Django REST Framework: viewsets, serializers, permissions, throttling
core/external_api/ The API other applications call to create and manage rooms, authenticated with application tokens
core/addons/ The endpoints of add-ins embedded in other applications, such as the Outlook add-in
core/authentication/ Sign-in, and the authentication of requests carrying a LiveKit pass
core/services/ The logic behind the API: the waiting room, presence, invitations, moderation, LiveKit webhooks, phone dial-in, subtitles
core/recording/ Starting and stopping recordings, and what happens once one ends
core/tasks/ Celery tasks: deleting connection-test rooms, deleting files, sending email. They run on the Celery worker when CELERY_ENABLED is on. Otherwise file deletion and email run inline in the request, and the connection-test room cleanup is not scheduled
core/management/commands/ Maintenance commands: purge_deleted_files, purge_inactive_rooms, clean_pending_files and merge_duplicate_users
core/audit/, core/auditing.py The audit log of room, token and recording operations, see The audit log
core/roomkit/ Meeting-room hardware joining over SIP
core/analytics/ Product analytics sent to PostHog, and the feature flags read from it
core/admin.py The Django admin pages
core/factories.py, core/tests/ Test data factories and the test suite
locale/ The backend's translations

Sign-in goes through the oidc_login module of django-lasuite, built on mozilla-django-oidc; core/urls.py mounts its URLs. Meet's own backend class is in core/authentication/backends.py.

Models

Model What it stores
User An account, created at the first OIDC sign-in. A staff account signs in to /admin/ with its admin_email and a password
Room A meeting room: its slug, the code in the URL; its access_level, public, trusted or restricted; its configuration, a JSON object every participant receives; and its telephony pin_code
ResourceAccess A user's role on a room: owner, administrator or member
Recording, RecordingAccess A recording or a transcription, its status from initiated to saved or a failure, and who may see it
Application, ApplicationDomain An application allowed to call the external API, and the email domains it may act for
File An uploaded file, such as a custom background image, and its upload state

API

core/urls.py mounts two APIs. The frontend's is described by the schema the backend generates, at /api/v1.0/swagger/ under the Development configuration; the other is the External API.

API Prefix Routes and their code
Browser API /api/v1.0/ users, rooms, resource-accesses, recordings, files and diagnostics from core/api/viewsets.py; roomkit from core/roomkit/; addons/sessions from core/addons/; the sign-in routes; config/, the instance's settings for the frontend
External API /external-api/v1.0/, mounted only when EXTERNAL_API_ENABLED is on application, rooms and users from core/external_api/viewsets.py

Most actions on a room are extra routes of RoomViewSet, such as request-entry, start-recording or mute-participant.

Frontend

A React 18 and TypeScript application built with Vite. Its libraries, whose versions are in package.json:

For Library
Components React Aria
Styles Panda CSS
Global state Valtio
Server data TanStack Query
Routes wouter
Translations i18next
Calls LiveKit's livekit-client and @livekit/components-react
Path under src/frontend/src/ What it holds
features/ One directory per feature: rooms, chat, recording, participants, settings and the others. Each keeps its own components, hooks and API calls
features/rooms/livekit/ Everything inside a call: the control bar, the participant tiles, the background effects, the LiveKit hooks
primitives/ The styled building blocks, Button, ToggleButton, Dialog, Menu and others, wrapping React Aria. A new component uses these rather than raw HTML or a direct React Aria import
components/ Components several features share
stores/ Valtio stores, one file per concern: layout.ts, chat.ts, recording.ts and the others. A component reads one with useSnapshot() and changes it by assigning to the store
api/ fetchApi, which calls the backend, the TanStack Query client, and useConfig, which reads the instance's settings from /api/v1.0/config/
hooks/ Hooks shared across features, such as useScreenReaderAnnounce
locales/, i18n/ One JSON file per namespace and language, and the i18next setup
routes.ts The pages and their URLs
utils/livekit.ts Browser detection the LiveKit workarounds rely on

Server data, such as a room or the list of recordings, goes through TanStack Query. A Valtio store holds what only the browser knows, such as the layout or an open panel.

Accessibility follows these patterns:

  • Every interactive element has an accessible name, from its visible text or an aria-label read through t(). HandToggle.tsx shows the usual shape: a ToggleButton from the primitives, its label and tooltip translated.
  • A state change the screen does not show, such as a recording starting, is announced with useScreenReaderAnnounce().
  • A room event goes through the toasts of ToastProvider.tsx.
  • A tooltip shown in picture-in-picture uses VisualOnlyTooltip instead of TooltipWrapper, so a screen reader does not read it twice. For the same reason, an element that only shows something carries no aria-live: announce the change once, with useScreenReaderAnnounce().
  • A React Aria Dialog traps focus and gives it back to the button that opened it. A side panel or a custom toolbar does neither: move focus into it yourself, with autoFocus, a ref.focus() or a FocusScope.

How Meet talks to LiveKit

The pass

The pass is the LiveKit access token the backend signs for each participant; the browser connects to LiveKit with it, as Joining a meeting describes.

generate_token() in core/utils.py builds it. The token's name is the participant's display name, and it carries three attributes: room_role, is_authenticated and color, the last derived from the participant's identity.

Owners and administrators get LiveKit's room_admin grant, which lets them moderate.

The pass reaches the browser two ways:

  • In the livekit field of the answer to POST /api/v1.0/rooms/<id>/join/, the join action of RoomViewSet in core/api/viewsets.py, when the visitor may enter at once. The display name travels in its body, as username; reading a room returns no pass.
  • In the answer to POST /api/v1.0/rooms/<id>/request-entry/, once someone admits the visitor from the waiting room, from core/services/lobby.py.

The pass also authenticates the API calls a participant makes during a call, signed in or not. They accept it through LiveKitTokenAuthentication in core/authentication/livekit.py.

sequenceDiagram
    participant Browser
    participant Backend
    participant LiveKit

    Browser->>Backend: POST /api/v1.0/rooms/{id}/join/ {username}
    Backend-->>Browser: room, with livekit {url, token, room}
    Browser->>LiveKit: WebSocket with the token
    Browser->>LiveKit: publish microphone and camera
    Backend->>LiveKit: room metadata, data messages, moderation, egress, agents
    LiveKit->>Backend: POST /api/v1.0/rooms/webhooks-livekit/

What the backend asks LiveKit

Every call goes through the client that create_livekit_client() returns.

What Backend side What the frontend does with it
Room metadata: the room's configuration and access level, and the recording state RoomManagement.update_metadata() in core/services/room_management.py RoomMetadataSynchronizer copies the configuration and access level into the cached room, and useRecordingStatuses reads the recording state
Data messages to every participant, such as someone waiting to enter notify_participants() in core/utils.py MainNotificationToast.tsx turns them into toasts and sounds
Muting, removing and updating a participant core/services/participants_management.py LiveKit applies it to the participant's connection
Recording, through LiveKit Egress core/recording/worker/services.py, behind mediator.py Shows the state carried by the room metadata
Sending an agent into a room core/services/subtitle.py for subtitles, core/recording/services/metadata_collector.py during a transcription Shows the subtitles the agent publishes
Phone dial-in rules, which route a caller's PIN to the room core/services/sip_management.py Nothing: the caller joins as an audio-only participant

What LiveKit tells the backend

LiveKit posts its events to /api/v1.0/rooms/webhooks-livekit/, the webhooks_livekit action of RoomViewSet. LiveKitEventsService in core/services/livekit_events.py checks the signature, then handles each event:

Event What the backend does
egress_updated Updates the recording's status
egress_ended Clears the recording state from the room metadata and stops the metadata collector. On success, core/recording/event/notification.py emails a screen recording's link to the people Email names, and sends a transcription to the summary service
room_started Closes the LiveKit room again if its Meet room was deleted; otherwise records the start time purge_inactive_rooms reads, and creates the room's phone dial-in rule when telephony or Roomkit is on
room_finished Deletes that rule and clears the room's presence and waiting-room state
participant_left Removes the participant from the presence cache, unless PRESENCE_CLEAR_ON_PARTICIPANT_LEFT is off

Any other event is acknowledged and ignored, and so is every event of a connection-test room or of a room whose name LIVEKIT_WEBHOOK_EVENTS_FILTER_REGEX does not match. In development, LiveKit finds the endpoint through the webhook section of docker/livekit/config/livekit-server.yaml.

The frontend side

Conference.tsx joins the room with POST /api/v1.0/rooms/<id>/join/, through joinRoom.ts, builds the LiveKit Room with Meet's options, and renders <LiveKitRoom> with the pass and the server URL. When the answer carries no pass, it shows the waiting room instead. It also holds the browser workarounds, such as an early WebSocket that lets Firefox connect behind some proxies, when enable_firefox_proxy_workaround is on.

The call's interface is VideoConference.tsx.

Agents

src/agents holds two LiveKit agents, workers that LiveKit sends into a room as silent participants when the backend asks.

File What it does
multi_user_transcriber.py Live subtitles: transcribes each speaker and publishes the text to the room
voxtral_vllm_stt.py The speech-to-text plugin for Voxtral served by vLLM, one of the subtitles providers
metadata_collector.py During a transcription, records who speaks when, connections and chat, and writes them to S3 for the summary service

Their settings are under Agents.

Summary service

src/summary is a FastAPI application with Celery workers:

The queues and the order of the steps are in How Meet works, and the settings under Summary service.

Other packages

Path What it holds
src/sdk The SDK in library/, published on npm as @gouvfr-lasuite/visio-sdk, which adds to another web application a button that creates a Meet link, and a sample application using it in consumer/. Its own guide is src/sdk/library/CONTRIBUTING.md
src/addons/outlook The Outlook add-in that adds a Meet link to an event, calling core/addons/
src/mail The MJML sources of the emails, compiled as Email templates describes

Deployment files

Path What it holds
src/helm/meet The Helm chart. Its values are documented in its README.md, which generate-readme.sh regenerates from values.yaml. Helm deployment covers deploying it
src/helm/helmfile.yaml.gotmpl, src/helm/env.d The helmfile and the values of the dev-keycloak and dev-dinum environments that Tilt deploys
env.d/development One .dist template per service of the development stack, which First run copies
env.d/production.dist The production templates. The directory carries the .dist suffix, not the files, so each keeps its name when the Deployment guide downloads it
Dockerfile, src/frontend/Dockerfile, docker/dinum-frontend The backend image, the frontend image, and the frontend image with the French government's styles
deploy/, Procfile The Scalingo deployment, described in Scalingo

The audit log

Audit logging describes what each event holds and how operators collect it.

Declaring an action

Every action is declared once, in core/auditing.py, as an audit.Action constant. An action may carry its ECS category and types, which then apply to every event it emits; a type its category does not expect fails at import time:

APPLICATION_TOKEN_ISSUE = audit.Action(
    "application.token.issue",
    category=EventCategory.AUTHENTICATION,
    types=(EventType.START,),
)
ROOM_CREATE = audit.Action("room.create")

core/auditing.py imports nothing but the audit facility and leaf helpers such as core.services.transit_code, so that any module can import it, authentication classes included. Models and authentication classes are registered separately, in core/audit_registry.py.

Auditing a DRF view

A DRF view only declares the actions it audits: everything else is derived from the response.

CRUD actions are mapped in audit_actions. An extra action names its own on its route, so that renaming its method cannot silently stop auditing it:

from core import audit, auditing


class RoomViewSet(audit.AuditViewMixin, viewsets.GenericViewSet):
    audit_actions = {"create": auditing.ROOM_CREATE, "retrieve": auditing.ROOM_RETRIEVE}

    def perform_create(self, serializer):
        self.audit_target = serializer.save()

    @action(detail=True, methods=["post"], audit_action=auditing.RECORDING_START)
    def start_room_recording(self, request, pk=None): ...

AuditViewMixin fills in the rest:

  • The ECS category and types come from the action, or default to api and the DRF action.
  • The outcome, reason and status code come from the response status: 401, 403 and 429 are denied, other errors are failure, filed as Classification describes.
  • The target is the object get_object() returned, unless the view assigns audit_target.
  • A view can also assign audit_user_target, audit_details and audit_actor, where None records no account, or override get_audit_fields().

Auditing from anywhere else

Outside of AuditViewMixin, from a view or deeper in a service, call audit.log. A category or types given here wins over the action's:

audit.log(auditing.USER_PROVISION, target=user)

Without request=, the event reads the context of the request being served, audit.request_context(), which AuditLogMiddleware captures when the request comes in. Outside a request, as in a Celery task, the context is empty and the actor is the system.

!!! note That context holds the Django request. DRF copies the user and auth onto the Django request, but not the authenticator, so a call made inside a DRF view without request= should pass auth_method=.

How fields are filled

  • Request fields are read from the request: the real client address, the path, the user agent and the request id.
  • The actor comes from request.user, request.auth and the DRF authenticator, as Actors describes. audit.register_auth_method maps the authenticator's class to an auth method, see Registering models. Without a request, the actor is the system. Override the actor with actor=, actor_type=, auth_method= and client_id=; an explicit actor_type= keeps the signed-in account. actor=None records no account: for a caller failing to authenticate, an application acting before it is given a delegated user, or the system.
  • The target is described by its model name, its primary key and the fields its model is registered with, see Targets. A model that is not registered is still identified. The account the action is about, user.target, is found from the target, unless given as user_target=. Name a service the backend calls with target_service=. Any other keyword argument is recorded under lasuite.details.

Emission never raises

A broken configuration or value is reported on the application logger and to Sentry, and the business operation goes on. A registered field that cannot be read is left out of the target, and the event is still emitted.

Admin pages need nothing

Every admin class, Django's own included, is audited as it is registered, by AuditedAdminSite in core/audit/admin.py. Registering a new admin's model only adds its category and allowed values.

Registering models and authentication methods

The project describes itself to the audit facility in code, in core/audit_registry.py. Once the audit app is ready, it imports the audit_registry module of every installed app.

audit.register(Model, ...) tells the audit log how to handle a model:

  • fields: the fields describing it as a target;
  • admin_values: the fields whose before and after values may be recorded for admin writes;
  • category: the ECS category of its admin writes;
  • entity_type: its ECS entity type, when one of the allowed values fits, such as application or user;
  • user_target: the attribute holding the account an event on it is about, such as user for an access.

A proxy model falls back to its concrete model. Registering a model twice raises AlreadyRegistered, and an entity type ECS does not allow raises ValueError.

audit.register_auth_method(klass, name) sets the lasuite.auth.method of a DRF authentication class or of a login backend. A DRF class inherits the name of its closest registered base, and DRF's own classes are built in. A login backend must be registered itself, because custom backends often subclass ModelBackend just for its permission checks. ModelBackend is built in as password.