unstructuredstudio / zubhub

Creative Education Platform

Intro

ZubHub is an open-source, documentation & collaboration tool for activity-based learning. It is available for custom use for schools, libraries, hackerspaces, educational organizations, etc. Imagine your own online community built around your educational activities! 

Zubhub is designed and developed by Unstructured Studio. We are an educational non-profit organization incorporated in Canada and India. We have our own ZubHub and we use it to expand access to low-cost creative learning opportunities to children and educators. On our ZubHub, children, and educators can get inspired by a collection of activity ideas and projects, learn how to build with the materials and tools that they already have access to, and share their creations with others. Some of the primary features are creator portfolios, community-curated projects, discussion-based collaboration, and workshops. ZubHub takes inspiration from the research conducted on the Build In Progress platform at the MIT Media Lab. 😃

ZubHub is currently in public beta. A public ZubHub instance is hosted here: https://zubhub.unstructured.studio

Want to know more about ZubHub and our feature roadmap? Head to 👉 ZubHub Wiki!

Development Setup

Follow the instructions below to set up your local development environment

Steps

1. Install Git. ( jump to section )
2. Fork and clone zubhub repository. ( jump to section )
3. Install docker. ( jump to section )
4. Install docker-compose. ( jump to section )
5. Install Node.js 14 and npm 7 or later. ( jump to section )
6. Install make. ( jump to section )
7. Setup Backend. ( jump to section )
8. Setup Frontend. ( jump to section )
9. Tests
10. Making changes and Commiting

Windows Specific Setup

• Install Docker and Docker Compose by installing Docker Desktop for Windows.

• Install tools (git, make, cygwin): The easiest way is to use a package manager like Chocolatey. Follow the installation instructions for Windows Powershell (Admin), then run choco install make git cygwin to install all packages. Follow the prompt requests allowing script execution. In the end, verify that packages are available with make --version and git --version, it should return a version for each command. Contributors also reported that installing MozillaBuild automates the installation of a number of these tools. At this point, you need to disable the config core.autocrlf before cloning the zubhub repository, otherwise, all files will use Windows line-endings (CRLF), and docker images will fail to build. To do so, open a Powershell as Admin (right-click on the Start Menu, select Windows Powershell (Admin)), and run:

git config --system --unset core.autocrlf
git config --global core.autocrlf false

You can use git config -l to verify that the value for core.autocrlf is correctly set.

Install Git

NOTE: You can skip this step if you already have git installed on your machine. To check if git is running on your machine, run the following command git --version.

• click on this link, select your operating system from the options given, then download and install git on your local machine.

Fork and clone Zubhub repository

• fork the zubhub repository to your Github account.

• On the homepage of the cloned repository in your own Github account, click on the code button, copy the URL in the dropdown then run the following code in your computer terminal:

      $ git clone <copied url>

The copied URL will have the format of https://github.com/<your github username>/zubhub.git

Install Docker

NOTE: You can skip this step if you already have docker installed on your machine. To check if docker is running on your machine, run the following command docker --version.

• Click on this link, select your operating system from the options given, then download and install docker on your local machine.

Install Docker Compose

NOTE: You can skip this step if you already have docker-compose installed on your machine. To check if docker-compose is running on your machine, run the following command docker-compose --version.

• Click on this link, go through the page and select your operating system from the options given, then follow the given instructions to download and install docker-compose on your local machine.

Install Node and NPM

NOTE: You can skip this step if you already have node and npm installed on your machine. To check if node and npm are already installed on your machine, run the following command node --version and npm --version.

• Click on this link and follow the given instructions to install node and npm on your local machine.

Install Make

NOTE: You can skip this step if you already have make installed on your machine. To check if make is running on your machine, run the following command make --version.

• If you are on a Linux machine, you can install make through this link.
• If you are on a Mac machine, you can google the specific steps of installing make on a mac machine.
• If you are on a Windows machine, you should refer to the Windows Specific Setup section at the beginning of the Developer Setup section.

Setup Backend

NOTE: For windows users, before running the commands below switch to bash (available through WSL), you can achieve that by typing bash to your command line.

• From the root of the repository, run:

       $ cd ./zubhub_backend

• Run:

       $ make init

This will run all the initial setups required and start the server, generate the minimal .env file required to run the backend, spins-up all containers defined in the backend docker-compose file, applies all necessary migrations to the database, and creates a default admin user with username and password of dummy and dummy_password respectively.

In case you're facing issues after running the above, like make: Error, kindly run this before the above command:

       $ docker-compose up

• Run the server:

Subsequently, to start and stop the docker containers, you run the following

To start:

       $ make start

To stop:

• Stop the running container

       $ make stop

• Stop & remove the running container

       $ make down

You can run test by running make test. For other make commands: run make help

Visit http://localhost:8000 on your browser to access the API documentation.

Setup Frontend

• On your terminal/command line, navigate to ./zubhub/zubhub_frontend/zubhub directory

• Create a file named .env in the frontend root folder (same directory with package.json), with the following content

#.env
REACT_APP_NODE_ENV=developement
REACT_APP_BACKEND_DEVELOPMENT_URL=http://127.0.0.1:8000

Using npm

This is advisable for a better development experience.

• Run npm install --legacy-peer-deps to install the dependencies.
• Run npm start to start the frontend.

Using the Docker Container

Use this when you are done with making your changes and you want to test your code on the Docker container.

• Run make start to spin up the frontend container.

Visit localhost:3000 on your browser to access the frontend.

Tests

Before you get started making changes and commiting, you should setup pre-commit on your development machine:

• Run pip install pre-commit
• Run pre-commit --version to verify that pre-commit installation was successful
• Run cd <path to cloned zubhub repository>
• Run pre-commit install to install the git hook scripts

To verify that your setup was successful, run pre-commit in the root of your cloned zubhub repo. You should see this running a number of checks.

Frontend

You can also test the frontend seperately by going to the root of the frontend project (the place you have package.json) and running npm run test -- --coverage --watchAll=false

Backend

To test the backend seperately,

• Run cd ./zubhub_backend
• Run make zubhub-test to run the test suites of the web django app
• Run make media-test to run the test suites of the media django app

Making changes and Commiting

Before making changes, make sure that you've set up pre-commit as described in the previous step. After that just git add . and git commit your changes. pre-commit will automatically run the different tests and will fail to commit until you fix all the errors.

NOTE: If you fail to setup pre-commit on your local machine before making pull requests, our pre-commit action on github will run the same tests on your code and if it fails to pass, your code won't be merged.

Deployment

ZubHub is currently deployed on its main website using Github Actions that act as our build and deployment tooling. If you are interested in deploying Zubhub on your VM for testing and hosting purposes, follow the Single VM Deployment instructions.

API Documentation

• Architecture Overview
• Web Server
• Media Server
• Database and ER Diagram
• Background Tasks
• Reverse-Proxy

Contributions

Contributions are welcome! We suggest you first go through the Contribution Guidelines and Code of Conduct and the Feature Roadmap and Ideas we have been working on. Search the Issues to see there are no duplicates or overlaps before filing new feature requests and bugs.

NOTE: If you are interested in the API documentation instead, you need to follow the instructions above about running the backend on your local machine and afterward visit localhost:8000 on your browser to view the API documentation.

zubhub's Issues

Add more actions to the profile dropdown menu

In the profile dropdown menu, when the user's image is clicked, show Followers, Following, Bookmarks

Add following button which shows who we are following

Currently, a user can only see who is following them or other users, but it is not possible to see who they or others are following. This needs to be fixed

Remove the line behind the DOB text

Date of birth text appears on the line as shown in the first screenshot. But, when I try to enter something, the line behind the text goes away (as in the second screenshot).

Ideally, there is no line anytime behind the DOB text.

Password reset: "failed to fetch" error

Steps to reproduce:

• Go to https://zubhub.unstructured.studio/password-reset
• Enter email address
• Hit "Send reset link"

And, you see the following error after a while:

horizontal scaling feature

Currently, the only way to scale zubhub is vertically. There is a need to build horizontal scaling into the devops process.

Implement Badge Feature

Currently, when you visit the profile of any creator account, there is no way of knowing the role of the creator (e.g. staff, moderator, group). We need to create a badge system that displays a badge on the creator's profile to indicate the role of the creator

Fix email address

Replace [email protected] with [email protected]

Password reset: failed to fetch error

Improve the "materials" field ui

It is not obvious from the project creation form UI how to add materials. I see now that we have a placeholder that says "add a material and click the + button". But, we could make more UI improvements to make it self-explanatory how one can add materials.

@tuxology can provide more input here on how the UI could be.

Share projects privately with another user

In the user testing today with a 6th grader, the user shares a wish to share projects with others privately. I think this is super ambitious for us at this point. Something to consider in the future..

Improve footer on the site with important links

Some important sections:

- Privacy

• Guidelines and Policy
• Terms of Use

- About

• ZubHub
• Unstructured Studio

- Help

• Tinkering Resources
• FAQs
• Contact Us

So other ideas here:

Allow for project creation when only one media source is provided

In the testing today, the user put the video URL but didn't want to upload any images, and the app wasn't allowing them to create the project.

We should not allow creating projects only if both inputs are empty. If there is one media input, it should be okay; we let it pass.

Add Option for Zubhub admins to download phone numbers as csv

We need a feature that allows admins to be able to download certain user details like phone number as csv

Fix bug in phone number field

I discovered a bug that causes django to throw a unique constraint error when more than one Creator register their profile and omit submitting a phone number

Implement Category and tags feature

Currently there is no way to assign category and tags to projects. Categories and tags will help to organize the posts on the platform and make it easy to perform search and filtering

Improve comment infra

This involves two major changes:

• adding feature to make it possible to reply to comments and mention other users on a comment
• Adding feature to make it possible to leave comments on a creator's profile
  (This would allow kids to publicly leave comments/testimonials to each other just like Scratch allows:
  https://scratch.mit.edu/users/yasharegs/)

Add a prompt / help text in the project description field

In the project description field, enter a prompt / help text that explains what one can include/ share in their project description.

@srish to give text for prompt to @NdibeRaymond

Create Curated Projects Feature

• We need a new section on main page which shows some project of the week, highlighted project
• Curated projects once curated should also fire up emails and text messages with Zubhub Links

Internationalization

The project in its current state is not set up for localization. There is a need to internationalize the project so as to enable easy localization when the time comes

Add Phone number field to the registration process

Requirement

So, based on on-ground feedback, it seems that its easy for people to register via their phone numbers. Therefore, lets add an option to add phone numbers as well to the registration process. This is needed because some kids may not have emails, but have ready phone numbers.

UX Details

We can allow users to register by either phone number only or email only or both phone number + email. We don't need to verify is the phone number is valid for now. Just that it has a country code and then some numbers (upto 10 digits). Also, for kids that get phone numbers, we can add a tick-box below which says:

• I would like to receive updates on new tinkering projects and ideas via WhatsApp/SMS or e-mail"

If the users tick that, we can later on in some distant future, implement engagement systems that send them such messages via messages or email - whatever they chose during registration. Since there is an option to already update email, later on, we also need an option to update phone number via registration interface.

Refactoring: Code styling and Code issues (functional components + styles separation)

This issue addresses the need to switch from class-based components to functional components, take a more intuitive and organized approach in structuring the frontend, moving components and views styling to different files, and other minor code refactoring issues.

Expected Outcome After Issue is fixed

• All class-based components should be converted to functional components
• Change the general folder structure of the frontend to a more intuitive approach
• Separating styles to their own different files with easy to locate file names
• Other minor but important refactoring issues

Implement Search feature

Zubhub as it is doesn't have a search feature. This is currently not that much noticeable because we have very little projects created. But as projects start to grow, creators are going to need a way to search through the growing projects and get the projects they need. We need a search feature for this

Anti-spam feature for filtering spam in comments

There is a need for zubhub to automatically detect spam comments or atleast flag them for moderators or admins to checkout later. One approach can be to use Askimet for this

Create project button embedded twice on `/profile` page

Perhaps, we should remove one of the "Create profile" buttons from the navbar. Maybe there is a reason we have two?

After project is created, user is taken to the home page

Ideally, after project is created, user should be taken to their profile page.

3 mb size for images, is it too less?

In the testing today also, we encountered this issue when the user tried to upload images. This made me wonder if we are being too restrictive when it comes to image size. Should we try to keep the image upload size limit a bit higher?

Add prompt about what is the Video link while creating project

While creating project, users are just prompted to add a video link. We should explain with some text below that "YouTube, Vimeo, Google Drive links are supported"

Add more actions to the footer

Footer of the site with something like this:

Add functionality to edit and delete projects

Right now the only way to edit and delete projects is through the admin site. There is a need for creators to able to edit and delete there projects

Implement activity notification

administrators should receive an email notification (so it helps us quickly monitor in the beginning) at least:

• List of new accounts per day
• List of daily new comments
• List of daily new projects created
• When a project is edited

Improve materials field ui

The materials field ui needs to be made more clear, that it can be used to add several materials. I noticed in the user study today. The child got stuck and kept writing a long sentence.

Implement Group feature

• School admins create an account (just like us Unstructured_Studio) and we provide special status to that account - "Group"
  Groups can have its own page where you input some different profile details (some images of creations, description and a list of members) and can add/remove other profiles (called “members”) that are shown on the Group's profile page. Only admin can add/remove
• On that profile page, all creations from all members are listed together

Implement feature to allow certain creators to become moderators

The work of moderators can involve keeping users in check by having the ability to delete comments that violate the terms of use. They can also help report posts that violate the terms of use too

Minor UI bugs

• When creating account on mobile phone, date of birth on android phones open calendar widget with today's date. Its a bit loooong and complex to navigate to your birth year. What can we do about it? Would this be an issue?

• "Video link is optional"
  

• When you select one image, there is no feedback as to what happened? Can we do it like materials where image upload happens on individual images? Users would generally upload images one by one and then would want to see a feedback that it has been uploaded and "how it looks". Then they may delete the ones they don't like. Is it too late to implement that? If its too late, its fine, we can do it in next round

• Confirmation email seems to be coming from [email protected]. Replace it with [email protected]

• When a youtu.be shortlink is shared, follow redirect and get the correct link? Currently we get a firefox/chrome security issue rendered in iframe

• Can we add a "Create Project" Button here whenever you are logged in?
  

Newly created projects don't appear on user profile page until the project is modified

Found out that newly created projects do not get included in the "user projects" part of the user profile

Misc UX Improvement Suggestions

I've been trying to fix here and there and not getting it completely right so, I am sending you some ideas to improve the UX. Its already looking very amazing!

• Use "Raleway" font in whole app. Make sure all titles are font-weight:900. Increase font sized of other headings like DEscription, Comments etc (2.2em)

• Experiment with following background colors (#FFCC00)

• Change App name from Create React App to Zubhub. Also change favicon. Take favicon from https://zubhub.unstructured.studio/ Also modify README.md to reflect ZubHub name

• The right buttons next to video/image could be probably more like "buttons". maybe use this style with button shadow on the whole "pill" and white text/icons. If this does not look good, use red color background (same as title bar) with yellow icons and text and see if that is good. Otherwise, use the vertical pill and put same styled buttons as the Clap and like buttons you have on cards in gallery view for visual consistency. Also buttons here have a "ghost layer" on hover. We should remove it or restrict it to width of container.

• Increase comment box with to 100% of its container. Its also not looking that prominent. Maybe put the whole thing in another "box" to show that its separate from the other sections? In current ZubHub we have put it in a gray box to show that its a separate interaction from main page.

• Use larger font (same size) and same Raleway font in the comment box as well for visual consistency

• Maybe try to use following card styling. Note that the buttons need to have yellow icons/text. Also see if we can replace these icons with "solid icons" rather than "line icons".
  

• If there is no video in card, show the first image

• Increase height of carousel so shadow is not cut suddenly.

• Maybe remove the robohash background from signups for now and replace with previous gradient on pages? Other things to experiment are https://svgeez.com/ (snowball dots or sprinkles styles with our yellow/red/cyan styled palette may work)
• Replace left/right arrows in following with something more elegant - maybe buttons (same as Signup style), same height as carousel with some more minimal arrows? (like we have on unstructured impact page?)
  

"This field is required" gets displayed multiple times if there are multiple validation errors

Same roundness for all buttons

Don't have best advice to share here may be @tuxology has. I think all our buttons should have same roundness (border radius).

Google drive error: sorry unable to open the file at this time

At the time of project creation, I provided the following google drive link: https://drive.google.com/file/d/1HuozYMFXS4XAEL-HYdPUnf-ofcb4pSSS/view

I didn't receive an error when I tried to hit submit. But on the project page now, I see the following error:

Is there something wrong about the URL I provided?

Project creation still now working without video link

Tried to create a project without video link and it shows the bug as follows

Remove metadata from images

Because of privacy concerns, there is a need to remove metadata from images before storing them on our server

Document Problems faced during deployment (like ssl and https issues we encountered)

Before deploying and during the first few days after deployment, we faced a number of production grade problems some of which had to do with SSL and https. There is a need to document how these problems where solved. This is so as to make sure that other people who get to work on this project don't end up making the same mistake we made and solving the same problems over again

Invalid email error when the email seems to be valid

@srish to send a DM to @NdibeRaymond and @tuxology with details.

Add Following and Bookmarks in user profiles

We removed this from phase 1, probably time to bring this back - a Following link which shows who we are following. Also a Bookmarks link. At same location:

Fix the content in and placement of "Enter a valid username..." error

This error is likely coming from Django. I couldn't find it on the frontend side. Ideally, we detect the exact problem in the username, and then display a short message like "Usernames can't have spaces". As far as the placement goes, we display this message right below the username input and not on the top. of the form.

Carousel on desktop is broken when less images are uploaded

Example Project (view on Dekstop only)

https://www.zubhub.unstructured.studio/projects/d5bb27b5-c87b-471a-a034-8245f6e067a1

Character limit for materials used is too high

I see that we are using 10,000 as character limit for materials used. Is it for each material? Is so, it is too high. I think for each there should be a limit of 100, and then another limit on number of materials one can enter, that also we can keep as 100.

All validation errors show at once as soon after exiting without entering any information in an input

Not sure, what the best alternative to address this is though. See screenshot below:

Disable debug mode from production backend

We know that debug mode is enabled in django - this exposes a lot of internal info about backend when errors are encountered. We need to disable it

Make user profile details fully editable, and allow creators to delete their accounts

Currently, it is only possible to edit just the username. This needs to change to make it possible to edit other user infos