# PoliticTalk Jitsi Developer Handoff

This folder is the source of truth for the white-labeled PoliticTalk Jitsi setup served from:

```text
https://politictalk.parallelglobe.io
```

The PoliticTalk VPS still runs the real Jitsi services. Local changes are made in this repo, committed, pushed, pulled on the VPS, then copied into the live Jitsi install with the deploy script.

## Main Files

```text
config/politictalk.parallelglobe.io-config.js
  Jitsi meeting policy: toolbar, audio-only behavior, prejoin, E2EE, branding URLs.

web/plugin.head.html
  Injected CSS and JavaScript for most visible UI customizations.
  This controls branding, mobile toolbar fixes, direct-access messaging,
  participant tile styling, role colors, hidden Jitsi controls, and layout patches.

web/title.html
  Browser title, favicon, and page metadata template.

web/manifest.json
  Web manifest used by the deployed Jitsi web app.

assets/public/politictalk/
  Public images and branding JSON, including logos, favicon, and background assets.

interface_config/politictalk-overrides.js
  Overrides appended to Jitsi's interface_config.js.

prosody-plugins/mod_politictalk_roles.lua
  Server-side room policy: JWT role mapping, moderator/member handling,
  host lifecycle, AV moderation, room inactive callback, and occupancy callback.

nginx/politictalk.parallelglobe.io.conf
  Nginx vhost and public asset routes for the PoliticTalk domain.

scripts/deploy-vps.sh
  Copies tracked files into the live Jitsi system paths and creates backups.
```

## Normal Change Flow

Work locally from the Jitsi folder:

```bash
cd /Users/amardeep/work/pg/jitsi
git status --short
```

Edit the relevant files. Most UI changes go in:

```text
web/plugin.head.html
```

Before committing, run quick checks:

```bash
git diff --check
awk '/^<script>$/{inside=1; next} /^<\/script>$/{inside=0} inside{print}' web/plugin.head.html | node --check -
```

Then commit and push:

```bash
git add .
git commit -m "Update PoliticTalk Jitsi UI"
git push
```

Use a specific commit message for non-UI work, for example auth, Prosody, nginx, or config changes.

## Deploy On VPS

The current VPS checkout is expected at:

```text
/opt/politictalk-jitsi-config
```

SSH into the VPS, pull the latest code, and run the deploy script:

```bash
ssh ubuntu@politictalk
cd /opt/politictalk-jitsi-config
git status --short
git pull --ff-only
sudo ./scripts/deploy-vps.sh
```

If the nginx vhost changed, deploy nginx too:

```bash
sudo DEPLOY_NGINX=1 ./scripts/deploy-vps.sh
```

The deploy script creates a backup under:

```text
/root/jitsi-backups/YYYYMMDD-HHMMSS
```

It also reloads nginx automatically.

## Restart Rules

For most UI and asset changes, this is enough:

```bash
sudo ./scripts/deploy-vps.sh
```

Then hard-refresh the browser or open a new incognito window.

For nginx changes:

```bash
sudo DEPLOY_NGINX=1 ./scripts/deploy-vps.sh
```

For Prosody plugin, JWT auth, moderator/participant policy, host lifecycle, or room callback changes, restart the Jitsi services after deploy:

```bash
sudo systemctl restart prosody
sudo systemctl restart jicofo
sudo systemctl restart jitsi-videobridge2
```

## Quick Verification

Check that public assets are served:

```bash
curl -I https://politictalk.parallelglobe.io/images/politictalk/pgLogo.svg
curl -I https://politictalk.parallelglobe.io/images/politictalk/politictalk_logo_text.svg
```

Check that the deployed config includes the expected PoliticTalk settings:

```bash
curl -s https://politictalk.parallelglobe.io/config.js \
  | grep -E "startAudioOnly|toolbarButtons|dynamicBrandingUrl|defaultLogoUrl|prejoinConfig"
```

Manual smoke test from PgPlatform:

```text
1. Create or open a PoliticTalk room from the platform.
2. Join as host and confirm the host is moderator.
3. Join as participant and confirm the participant is not moderator.
4. Confirm participant starts muted and cannot unmute without host action.
5. Confirm chat, raise hand, polls, fullscreen, and noise suppression work.
6. Confirm direct room access without platform/JWT shows the Parallel Globe account message.
7. Confirm mobile toolbar, participant tiles, and branding render correctly.
```

## Rollback

Every deploy prints the backup path. To roll back, copy the backed-up files from that folder back to their original system paths, then reload/restart the relevant services.

Common live paths:

```text
/etc/jitsi/meet/politictalk.parallelglobe.io-config.js
/etc/jitsi/meet/public/politictalk/
/usr/share/jitsi-meet/images/politictalk/
/usr/share/jitsi-meet/plugin.head.html
/usr/share/jitsi-meet/title.html
/usr/share/jitsi-meet/manifest.json
/usr/share/jitsi-meet/interface_config.js
/usr/share/jitsi-meet/prosody-plugins/mod_politictalk_roles.lua
/etc/nginx/sites-available/politictalk.parallelglobe.io.conf
```

After rollback:

```bash
sudo systemctl reload nginx
```

If Prosody/JWT logic was rolled back:

```bash
sudo systemctl restart prosody
sudo systemctl restart jicofo
sudo systemctl restart jitsi-videobridge2
```

## Important Notes

- Do not edit the live Jitsi files manually on the VPS except for an emergency. Those changes will be overwritten by the next deploy.
- Do not commit secrets, JWT secrets, Prosody passwords, or generated Docker `.env` files.
- Public visual assets should go in `assets/public/politictalk/`.
- Keep `plugin.head.html` changes scoped and well-commented. Jitsi is a React app with generated class names, so prefer stable selectors such as IDs, aria labels, known wrapper classes, and classes that our script adds.
- The platform and PgApi are responsible for room creation, user validation, invite links, and Jitsi JWT generation. The Jitsi VPS validates the token and enforces in-room behavior.