dreams-for-schools

Docker

Prerequisites

• Docker installed on your machine.
• Docker Compose installed.

Setup and Running the Application

1. Clone the Repository

   git clone git@github.com:developforgood/dreams-for-schools.git
   cd dreams-for-schools
   

2. Environment Variables

   Create a .env file in the backend directory with the following content:

   DATABASE_URL=postgresql://postgres:password@db:5432/mydatabase
   NODE_ENV=development
   

   Note: Adjust the DATABASE_URL as needed.

3. Project Structure

   The project should have a structure similar to:

   project-root/
   ├── frontend/
   │   ├── src/
   │   ├── public/
   │   ├── package.json
   │   ├── tsconfig.json
   │   ├── Dockerfile
   │   └── Dockerfile.dev
   ├── backend/
   │   ├── src/
   │   ├── prisma/
   │   ├── package.json
   │   ├── tsconfig.json
   │   ├── Dockerfile
   ├── docker-compose.yml
   └── README.md
   

   Particularly:

   • dockerfile.dev (frontend) is located in the frontend folder for development
   • dockerfile (backend) is located in the backend folder for development
   • docker-compose.yml is located in the main repository

4. Start the Application

   From the root directory, run:

   docker-compose up
   

   This will:

   Build and start the frontend container on http://localhost:5173.
   Build and start the backend container on http://localhost:8000.
   Start the PostgreSQL database on port 5432.
   

   Accessing the Application

   Frontend: http://localhost:5173
   Backend API: http://localhost:8000
   

   Live Reloading:

   Frontend: Changes in the frontend directory will automatically reload the frontend application.
   Backend: Changes in the backend directory will automatically reload the backend server using nodemon.
   

5. Debugging Common Issues

   Dependency Caching Issues: The Dockerfile may not be caching dependencies effectively - changes to package.json may not trigger proper reinstallation of dependencies.

   When dependencies are updated, run:

   # Rebuild containers without using cache
   docker-compose build frontend --no-cache  # For frontend changes
   docker-compose build backend --no-cache   # For backend changes
   
   # Start the containers
   docker-compose up

Frontend

React + TypeScript + Vite

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

Currently, two official plugins are available:

• @vitejs/plugin-react uses Babel for Fast Refresh
• @vitejs/plugin-react-swc uses SWC for Fast Refresh

Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:

• Configure the top-level parserOptions property like this:

export default tseslint.config({
  languageOptions: {
    // other options...
    parserOptions: {
      project: ["./tsconfig.node.json", "./tsconfig.app.json"],
      tsconfigRootDir: import.meta.dirname,
    },
  },
});

• Replace tseslint.configs.recommended to tseslint.configs.recommendedTypeChecked or tseslint.configs.strictTypeChecked
• Optionally add ...tseslint.configs.stylisticTypeChecked
• Install eslint-plugin-react and update the config:

// eslint.config.js
import react from "eslint-plugin-react";

export default tseslint.config({
  // Set the react version
  settings: { react: { version: "18.3" } },
  plugins: {
    // Add the react plugin
    react,
  },
  rules: {
    // other rules...
    // Enable its recommended rules
    ...react.configs.recommended.rules,
    ...react.configs["jsx-runtime"].rules,
  },
});

Backend

Prisma Development Workflow

This project uses the Prisma ORM in order to manage schema changes and interact with the PostgreSQL database in a type-safe way. Below are useful commands in the Prisma development workflow. Note that this section only covers development mode, not deployment. The Dockerfile for the backend installs the Prisma CLI, and also generates the Prisma Client as build-time commands.

When the app is running, you would need to manually execute the prisma migrate dev command inside the running container, for example, by attaching to the container and running the command (docker exec -it dreams-for-schools-backend-1 npx prisma migrate dev). However, this should be rare. Alternatively you can stop the app and rebuild it with docker compose.

Note that the seed.ts seed script is not run automatically upon app startup since it is not always needed, but instead if you need to run it you can run it manually afterwards inside the backend container.

Possible commands of use are:

• npx prisma migrate dev (to apply or create migrations, auto-runs the seed script),
• npx prisma migrate reset (if you want to drop all tables, run all migrations, then seed script)
• npx prisma generate (to regenerate the Prisma Client - best practice is to run this whenever changes are made to schema.prisma), or
• npx prisma db seed (to run seed script)
• npx prisma studio (to launch the Prisma Studio UI for database inspection). This will open on Port 8000.

Data Processing

This task involves a Python script designed to process instructor availability data from an Excel file and export the cleaned data as a JSON file.

The script handles data cleaning, formatting, and transformation for specific columns, such as availability schedules and programming languages, ensuring the data is well-structured for downstream use.

Features

• Splits multi-line or comma-separated data into lists.
• Cleans and formats availability schedules:
  • Parses days, times, and timezones.
  • Converts times to 24-hour format.
  • Sorts days in logical order (Monday to Friday).
• Exports the processed data to a JSON file with proper indentation.

Prerequisites

Python Dependencies

• Python 3.6 or later
• Required Python packages:
  • pandas
  • openpyxl

Install dependencies using the following command:

pip install pandas openpyxl

Scripts to Parse JSON to Database

Running the Script

To parse JSON data and insert it into the database, use the following command:

1. Go to the backend Directory: Open your terminal and navigate to the backend directory where the script is located:

  cd backend

2. Run the Script: On the terminal, run the following command to execute the script that parses the JSON file and inserts the data into the database:

npx ts-node src/scripts/parseJsonToDatabase.ts

Debug Your problem

If by any chance you couldn't run it successfully in your terminal, do the following:

1. Open terminal in your backend Docker container Open the docker app, click the running backend container, go to "Terminal".
2. Execute following commands

# 1. Generate Prisma client
npx prisma generate

# 2. Run migrations
npx prisma migrate deploy

# 3. Verify database connection
npx prisma db push

# 4. Then run your script
npx ts-node src/scripts/parseJsonToDatabase.ts

3. Verify you have successfully inserted data In the same terminal in this container, run

npx prisma studio

Then you'll see data that's been successfully inserted by checking the count of entries for each table.

Notes

• Ensure Correct JSON Path: Make sure that the path to the JSON file is correctly referenced in the script located at src/scripts/parseJsonToDatabase.ts. If the file path is incorrect, the script will fail to load the data.

• Prisma Database Connection: The script relies on Prisma to connect to your database. Ensure that your DATABASE_URL in the .env file is correctly set up and points to the appropriate database.

• Handling Duplicates: If you use skipDuplicates: true in the Prisma queries, the script will ignore entries that already exist in the database based on unique constraints, such as cityName and state for the City model.

• Error Logging: Any issues or errors during the execution will be logged to the console for debugging purposes. If the script doesn't work as expected, carefully review the console output for specific error messages.

• Database Schema: Ensure that your Prisma schema is up to date with all necessary models and relationships defined, as the script will attempt to insert data into these models based on the JSON file's structure.

Random

ShadCn MultiSelect Component