Tidal PTC

Tidal PTC (parent-teacher conferences) is Archboard's first open source project. It is a web application that allows parents and guardians to schedule parent-teacher conferences with their children's teachers. It has direct integration with PowerSchool, which makes it easy for IT admins to set up and get running.

Installation

Requirements: PHP 8.5, PostgreSQL, Node 20+, a PowerSchool plugin (client ID/secret) for SSO and data sync.

composer install
npm install && npm run build
cp .env.example .env
php artisan key:generate
php artisan migrate

Point a web server at public/, then visit /install to configure the tenant and create the first administrator. For a step-by-step fresh-server walkthrough without Docker (Nginx, PHP-FPM, PostgreSQL, Redis and systemd services), see INSTALLATION-VM.md.

Scheduled tasks and email

Add the scheduler to cron so reminders go out and the activity log is pruned:

* * * * * cd /path/to/tidal-ptc && php artisan schedule:run >> /dev/null 2>&1

Email is sent through the SMTP settings configured on the tenant settings page. QUEUE_CONNECTION=sync (the default) sends mail inline; set a real queue driver and run php artisan queue:work --queue=default,sis_sync to send in the background. PowerSchool syncs run on the sis_sync queue, which the worker only picks up once default is empty.

Docker

For a step-by-step fresh-server walkthrough, including the reverse proxy, see INSTALLATION.md.

The repository ships a production Compose stack: the app on Laravel Octane (FrankenPHP), Reverb for websockets, a queue worker, the scheduler, PostgreSQL and Redis.

Images are published to ghcr.io/archboard/tidal-ptc (latest and one tag per release), so a server only needs docker-compose.yml and an .env:

cp .env.example .env
# Set APP_URL, APP_ENV=production, APP_DEBUG=false, DB_PASSWORD, the REVERB_* values
# and the PowerSchool credentials, plus a key:
sed -i "s|^APP_KEY=.*|APP_KEY=base64:$(openssl rand -base64 32)|" .env
docker compose pull && docker compose up -d   # or `up -d --build` to build from source

Migrations run automatically when the app service starts. Put a TLS-terminating reverse proxy in front and route / to port 8000 and /app, /apps (websockets) to port 8080; REVERB_HOST/REVERB_PORT/REVERB_SCHEME must describe the proxy's public websocket address. Run Artisan with docker compose exec app php artisan …. To update, docker compose pull && docker compose up -d restarts every service on the new image (pin a version with TIDAL_PTC_VERSION=1.2.3 in .env).

To hear about new versions, watch the repository's releases on GitHub (Watch → Custom → Releases). To update automatically instead, run Watchtower against the stack, and leave TIDAL_PTC_VERSION unset so it follows latest.

DigitalOcean App Platform

The button deploys .do/deploy.template.yaml: a single container built from the app-platform stage of the Dockerfile (Octane, Reverb, the queue worker and the scheduler in one process tree) plus a dev PostgreSQL database. Before deploying, fill in APP_KEY (echo "base64:$(openssl rand -base64 32)") and the PowerSchool credentials; everything else has a working default. Websockets are served through the app's own domain, so no extra routing is needed.

Rotating the app key

APP_KEY encrypts every tenant's PowerSchool and SMTP credentials, and it signs sessions and cloud setup links. Keep it only in your host's secret store. If it leaks, or on a schedule, rotate it:

1. Generate a new key with php artisan key:generate --show. Set it as APP_KEY, move the old key to APP_PREVIOUS_KEYS (comma-separated), and deploy. Existing secrets, sessions and links keep working.
2. Run php artisan key:reencrypt to rewrite the tenant secrets with the new key.
3. Remove APP_PREVIOUS_KEYS and deploy. Everyone is signed out, and unused cloud setup links stop working (reissue them with php artisan tenant:setup-link).

Local development

php artisan migrate --seed creates a tenant on APP_URL with an admin (admin@example.com), a teacher, a guardian and sample time slots — all with the password password. Run npm run enums after changing a #[PublishEnum] enum to regenerate the JavaScript copies.

License

Tidal PTC is licensed under the GNU GPLv3 license. You can read more about it on GNU's website.