System Overview¶

Toodle is a multi-repository tutor management system consisting of a frontend application, backend API, and documentation website. Each component is developed, tested, and deployed independently while contributing to one integrated platform.

The React frontend communicates with the Express backend through a hand-written REST API. The backend manages application logic, authentication, authorisation, validation, and database operations. Project documentation is maintained separately using MkDocs.

High-Level Architecture¶

Toodle follows a layered application architecture. The frontend communicates with the backend through HTTP requests, while the backend processes requests, applies business rules, and interacts with PostgreSQL through Prisma.

flowchart LR
    subgraph Frontend["Frontend - React + Vite"]
        A[Admin Interface]
        L[Lecturer Interface]
        T[Tutor Dashboard]
        S[Student View]
    end

    subgraph Backend["Backend - Express REST API"]
        M[Global Middleware]
        R[Routes]
        V[Authentication, RBAC & Validation]
        C[Controllers]
        SV[Services & Business Logic]
        P[Prisma ORM]

        M --> R
        R --> V
        V --> C
        C --> SV
        SV --> P
    end

    DB[(PostgreSQL)]
    AUTH[Auth0]
    EXT[External Services]

    A --> M
    L --> M
    T --> M
    S --> M

    Frontend -. Authentication .-> AUTH
    AUTH -. Token Verification .-> V

    P --> DB
    SV --> EXT

The diagram illustrates the main architectural responsibilities. Authentication and validation are applied where required, rather than uniformly to every endpoint. Certain controllers and middleware components also access Prisma directly.

Frontend¶

The frontend is built using React and Vite. It provides role-specific interfaces for administrators, lecturers, tutors, and students.

Frontend requests are handled through an Axios API client, which supports authenticated communication with the backend using bearer tokens. During local development, Vite provides an API proxy.

The frontend does not access the database directly.

Backend API¶

The backend is built using Express.js and exposes the hand-written REST API.

Its responsibilities include:

Routing and processing HTTP requests.
Authentication, authorisation, and input validation.
Applying tutor allocation rules and other business logic.
Managing database operations through Prisma.
Communicating with external services.

The backend is organised around routes, middleware, controllers, services, and shared utilities. Although these layers separate the main responsibilities, some controllers and middleware access the database directly where required.

Data Layer¶

Toodle uses PostgreSQL as its relational database and Prisma ORM for database access and schema migrations.

The database manages information relating to users, courses, academic terms, tutor applications, marks, availability, allocations, timesheets, excusals, session swaps, notifications, and administrative records.

Additional entities support course coordinators, allocation drafts, tutor budgets, overflow opportunities, audit logs, calendar subscriptions, and academic scheduling.

Relationships and constraints are defined through the Prisma schema to support data consistency and application workflows.

External Services¶

Toodle integrates with external services to support authentication, communication, file storage, and academic scheduling.

Service	Purpose
Auth0	Authentication, access-token verification, and user identity management.
Brevo	Transactional email and notification delivery.
Supabase Storage	User avatar storage and management.
Wits Academic Calendar	Retrieval and processing of academic term information from the university website.

External integrations depend on the relevant environment configuration. For example, email delivery and avatar uploads require valid service credentials.

The academic calendar integration retrieves information from an external website rather than a structured API.

Toodle also provides an iCalendar (.ics) subscription feed for compatible calendar applications.

Background Processing¶

In addition to handling HTTP requests, the backend runs an automated reminder job.

The reminder scheduler executes within the API process and periodically invokes the application's service layer to process reminders.

Its behaviour can be configured using REMINDERS_ENABLED and REMINDERS_INTERVAL_MINUTES. The scheduler is disabled in the test environment.

To reduce duplicate reminder attempts, notifications use a database-level unique deduplication key. This prevents duplicate notification creation but does not guarantee successful email delivery.

Repository Separation¶

Toodle is maintained across three repositories in the Infinite Loopers Gitea organisation.

Repository	Responsibility
`Toodle`	React and Vite frontend application
`toodle-api`	Express REST API, business logic, database access, and external integrations
`toodle-docs`	MkDocs project documentation website

This separation supports independent development, testing, dependency management, and deployment.

The frontend and backend communicate through HTTP rather than sharing direct database access, satisfying the project's requirement for a non-monolithic application architecture.

Role Model¶

Toodle uses four application roles, enforced through role-based access control (RBAC).

Role	Responsibilities
Admin	Manages users, roles, courses, coordinators, academic settings, and cross-course administrative workflows.
Lecturer	Manages coordinated courses, allocations, applications, timesheet reviews, excusals, and other authorised academic workflows.
Tutor	Manages allocated work, availability, timesheets, applications, excusals, session swaps, and volunteering.
Student	Submits academic information, applies for tutoring opportunities, and volunteers for eligible work.

The backend stores these roles as ADMIN, LECTURER, TUTOR, and STUDENT.

Course coordination is represented through course assignments rather than a separate application role.

Role Assignment and Access¶

New accounts initially receive the STUDENT role. Administrators can update user roles and assign lecturers to coordinate specific courses.

Course-scoped authorisation restricts relevant lecturer management operations to their assigned courses. Administrators retain broader access across the platform.

Student applications and approved volunteering opportunities can also result in tutor-role promotion where applicable.

The distinction between administrators and lecturers separates platform-wide responsibilities from course-specific academic management.

Key Architectural Constraints¶

Toodle's architecture follows the compulsory requirements of the project brief:

Non-monolithic architecture: Frontend and backend operate as separate applications.
Hand-written REST API: API endpoints are designed and implemented by the team.
Established authentication: Auth0 handles authentication rather than a custom-built authentication system.
External integration: The system integrates with external services for relevant functionality.
CI/CD: Automated workflows support project development and deployment.
Responsiveness and accessibility: The frontend is designed to support different screen sizes and accessible interaction.
Public documentation: Technical documentation is published through a dedicated MkDocs website.