Deployment and Hosting

Toodle uses a distributed deployment architecture, with separate hosting services for the frontend, backend API, database, authentication, and documentation.

This separation allows the main components to be configured, maintained, and deployed independently while communicating through defined interfaces.

Deployment Architecture

flowchart LR
    U[User Browser]
    F[React Frontend - Vercel]
    A[Express API - Render]
    DB[(PostgreSQL - Supabase)]
    AUTH[Auth0]
    STORAGE[Supabase Storage]
    BREVO[Brevo Email API]
    DOCS[MkDocs - Cloudflare Pages]

    U --> F
    U --> DOCS
    F --> AUTH
    F --> A
    A --> AUTH
    A --> DB
    A --> STORAGE
    A --> BREVO

The browser loads the React frontend, which communicates with the Express REST API. Auth0 provides authentication, while the backend handles business logic, database access, and external service integrations.

Deployment Components

Component	Technology	Hosting Platform
Frontend	React and Vite	Vercel
Backend API	Node.js and Express	Render
Database	PostgreSQL	Supabase
Authentication	Auth0	Auth0
File Storage	Supabase Storage	Supabase
Transactional Email	Brevo API	Brevo
Documentation	MkDocs Material	Cloudflare Pages

Each component has its own configuration and deployment requirements.

Frontend Deployment

The React application is hosted on Vercel.

Vite generates the production build, while Vercel serves the frontend application over HTTPS.

The frontend repository uses Gitea Actions to perform automated checks, including:

• Dependency installation.
• ESLint and Prettier validation.
• Vitest automated tests.
• Production build verification.

Frontend deployment to Vercel is configured separately from these Gitea quality checks.

Backend Deployment

The Express REST API is configured for deployment on Render as a Node.js web service.

The backend deployment configuration includes:

• Environment-based application settings.
• Database connectivity through Prisma.
• A /health endpoint for service health checks.
• Prisma migration execution during the deployment build process.

The backend repository uses Gitea Actions for formatting, linting, automated tests, coverage, and allocation-integrity checks against a disposable PostgreSQL database.

Successful pushes to main can trigger Render deployment through a configured deployment hook.

Database Hosting

PostgreSQL is hosted through Supabase, providing managed relational database infrastructure.

The Express backend uses Prisma to access and manage application data. The database connection is configured through backend environment variables, including DATABASE_URL and DIRECT_URL.

Prisma migrations are maintained in the backend repository and can be deployed using:

npm run db:deploy

The frontend does not connect directly to the PostgreSQL database.

Detailed entity relationships and database constraints are documented under Database Design.

Authentication and External Services

Auth0 provides authentication, including Google Sign-In.

The frontend handles the user authentication flow, and the backend verifies access tokens before allowing protected operations.

Additional backend integrations include:

• Brevo: Transactional email and problem-report communication.
• Supabase Storage: User avatar storage and management.
• Wits academic calendar: Retrieval and parsing of academic term information.

External service credentials are configured on the backend and are not included in frontend builds.

See External API Integration for implementation details.

Documentation Deployment

The documentation website is generated using MkDocs Material and hosted publicly through Cloudflare Pages.

The documentation repository uses Gitea Actions to automate deployment.

The workflow:

1. Checks out the documentation source.
2. Installs the required Python dependencies.
3. Builds the documentation website.
4. Validates the build using strict mode.
5. Deploys the generated static site using Wrangler.

The strict validation command is:

python -m mkdocs build --strict

Documentation deployment is triggered by supported pushes to main or through manual workflow execution.

Environment Configuration

Each deployed component requires environment-specific settings.

These include:

• Database connection strings.
• Auth0 credentials and API audience configuration.
• Frontend and backend URLs.
• Brevo and Supabase service credentials.
• CI/CD deployment tokens and secrets.

Sensitive values are managed through environment variables and deployment-platform secrets rather than being committed to Git.

The backend also supports configurable reminder scheduling through REMINDERS_ENABLED and REMINDERS_INTERVAL_MINUTES.

See Environment Setup for configuration details.

Background Reminders

Toodle runs automated reminders using an in-process backend scheduler.

The scheduler operates while the API instance is running. When the hosting platform suspends an idle instance, reminder processing pauses until the service resumes.

Later runs can identify outstanding reminders, subject to the application's reminder rules and notification history.

Deployment Verification

Before releasing changes, the team checks that:

• Automated tests and production builds complete successfully.
• Code-quality checks pass.
• Required environment variables and secrets are configured.
• The frontend can communicate with the backend API.
• Auth0 authentication and protected operations work correctly.
• Prisma can connect to the database.
• Required database migrations have been applied.
• Relevant external integrations respond as expected.

The frontend, backend, and documentation repositories maintain separate automated workflows appropriate to their responsibilities.

Deployment Failure Handling

If a deployment fails, the team reviews build and application logs to identify the affected component.

Corrections are made through the usual development and review process before deployment is attempted again.

Where supported, the hosting platform can be used to restore an earlier stable deployment while an issue is investigated.