Local Development

Toodle is split across separate frontend, backend API, and documentation repositories. Each part can be run independently during development, allowing team members to work on different areas of the system without needing to start the entire project.

This page explains how to run each repository locally and how the different parts connect during development.

Frontend

The Toodle frontend is located in the Toodle repository and is built using React and Vite.

From the root of the frontend repository, install the project dependencies if you have not already done so:

npm install

Then start the local development server:

npm run dev

Vite starts a development server that allows developers to preview the application in a browser. Changes made to the frontend source code are automatically reflected during development without requiring a complete rebuild.

By default, Vite typically serves the frontend at:

http://localhost:5173

The actual address will be displayed in the terminal when the development server starts.

Once running, the frontend should connect to the locally running Toodle API using the configured VITE_API_URL environment variable.

This configuration allows the frontend to communicate with the backend through HTTP requests while keeping both applications independently developed and maintained.

Backend API

The Toodle backend is located in the toodle-api repository and is built using Express.js.

From the root of the backend repository, install the project dependencies if required:

npm install

Then start the API development server:

npm run dev

The backend handles requests from the frontend, processes application logic, communicates with the database, and enforces authentication and authorisation requirements.

The backend requires the necessary environment variables to be configured before it can connect to services such as the database and authentication provider. These settings are described in the Environment Setup section.

During local development, the API runs separately from the frontend and exposes the application's HTTP endpoints under the /api/v1 base path.

The API server should remain running while testing frontend features that require backend communication.

Documentation Site

The project documentation is maintained in the toodle-docs repository using MkDocs with the Material theme.

From the root of the documentation repository, install the required Python dependencies if they have not already been installed:

pip install -r requirements.txt

Start the local documentation server with:

mkdocs serve

MkDocs will serve the site locally at:

http://127.0.0.1:8000

The local site automatically reloads when documentation files are saved, allowing changes to be previewed before they are committed and deployed.

This allows the team to review documentation updates, verify navigation links, inspect formatting, and ensure that technical explanations remain clear and consistent with the implemented system.

Documentation changes are maintained through the team's established Git workflow, with updates reviewed before being merged and published.

Running the Full System Locally

To test the application as a complete system, run the backend API and frontend application at the same time in separate terminals.

Although the repositories are maintained independently, the frontend and backend work together to provide the complete Toodle experience.

A typical local setup is:

1. Start the backend API from the toodle-api repository using npm run dev.
2. Confirm that the API is running and connected to the configured database and authentication services.
3. Start the frontend application from the Toodle repository using npm run dev.
4. Ensure the frontend environment is configured to send requests to the local API through VITE_API_URL.
5. Open the frontend in the browser and test the required user flow.

The frontend and backend remain separate applications during development and communicate through HTTP requests to the Toodle API.

This separation allows developers to work on individual components without requiring changes to the entire system. It also supports independent testing, troubleshooting, and deployment of the frontend and backend applications.

When testing features that depend on authentication, database operations, or external services, the relevant configurations must be available and correctly configured.

Stopping the Development Servers

To stop a locally running development server, return to the terminal where it is running and press:

Ctrl + C

Repeat this for each running service, such as the frontend, backend API, or documentation server.

Stopping the development servers does not remove installed dependencies or modify the project files. The services can be started again whenever development work resumes.