---

Visit oriori: https://oriori.app

Table of Contents

Click here to expand

1. Project Description
   • What is oriori?
   • Why use oriori?
   • Tech Stack
   • Roadmap
   • Contribution
2. For Developers: How to Use This Project
   • Installation
     • Prerequisites
     • 1. Setup a Firebase Project for Development
     • 2. Clone the Repository
     • 3. Setup a Python Virtual Environment
     • 4. Install Dependencies
     • 5. Initialize a Development Database
     • 6. Create your .env Files
     • 7. Local PostgreSQL Only Run Migrations Seed Data
   • Running the Server
     • Using Docker
     • Using Local PostgreSQL
   • Using the App
     • Sign Up
     • Log In
     • Navbar
     • Product Cards
     • Settings
     • Admin Features
       • Add Products
3. Credits
4. License

Project Description

What is Oriori?

(四し季き折おり々おり) - shikioriori

Oriori is a tracking tool for seasonal and regional goods in Japan. The name comes from the Japanese phrase shikioriori, which means ‘from season to season.’

Why use Oriori?

Have you ever wondered when the Sakura-themed drinks are gonna drop this year? Or have you gone somewhere and wondered what yummy things you can try that you can't find in another prefecture? Look no further, Oriori's got you covered!

Tech Stack

Tech	Usage
	Used to manage PostgreSQL database for product data
	A secure, scalable database
	Used to implement Django :)
	Responsive framework to manage the client DOM
	Type-safe coding with the familiarity of JavaScript
	Used for a consistent dev. environment and for containerized deployment
	User authentication and user metadata

Roadmap

See the GitHub Issues for this repository.

Contribution

You can contribute by:

• providing feedback
• making suggestions/sharing ideas
• reporting bugs
• submitting Pull Requests (must be associated w/ an Issue)

Be sure to read our Contribution Guidelines

For Developers: How to Use This Project

Installation

Prerequisites

Please make sure the following technologies are installed on your system before starting development on Oriori:

1. Python
2. NodeJS
3. Either Docker or PostgreSQL
   • We recommend using Docker to keep your local environment clean, however, for reduced build times, it is also possible to use a local PostgreSQL installation.
4. A Firebase account

1. Setup a Firebase Project for Development

Firebase is required to handle user authentication and certain user metadata.

1. Create a Firebase project for your use. (Google Analytics is not required.)
2. Register a Web App to the project.
   • Don't include Firebase hosting
   • Skip 'Add Firebase SDK'
3. Add Authentication with Email/Password sign-in.
   • Email link is not currently enabled
4. Add a Realtime Database.
   • Select a location convenient for you
   • Start in test mode
   • Update the Rules to match the following:

     {
       "rules": {
         "users": {
           "$userId": {
             ".read": "$userId === auth.uid",
             ".write": "$userId === auth.uid"
           }
         }
       }
     }

2. Clone the Repository

Clone the repository (use a personal fork if contributing) into a working directory on your computer.

• How to Clone a GitHub Repo

3. Setup a Python Virtual Environment

• In the project's root directory, run this command in the terminal:

  python -m venv venv

  (You may need to use python3 instead of python depending on your installation.)
• IMPORTANT: Please ensure you are always inside the virtual enviromnent whenever working on Oriori. To activate the virtual environment run this command in the terminal:

  source venv/bin/activate

  To close the virtual environment, run this command in the terminal:

  deactivate

4. Install Dependencies

• Run the following command in the terminal:

  pip install -r requirements.txt

• After the Python requirements have been properly installed, run this command next:

  cd client && npm install && cd ..

5. Initialize a Development Database

Option A: Docker

• Make sure Docker is running

Option B: PostgreSQL

• Create a database to use with Oriori
  • Make sure to take note of the database's name and a username and password combination with read/write access to the database
  • PostgreSQL: CREATE DATABASE

6. Create your .env Files

Two .env files are used the following locations:

• in the oriori project directory
• in the oriori/client subdirectory

Duplicate the .env.example files in each directory, rename them to .env and fill out the missing information:

.env

• SECRET_KEY

  Generate a new Django Secret Key and copy + paste it here.

  • How to Generate a Django Secret Key
  • Follow steps 1-3 at the above link. At step 4, paste the secret key into .env instead of config/settings.py.

• DEBUG

  This can be either True or False - we recommend setting this as False in almost every circumstance

• DATABASE_URL - Required when using PostgreSQL for development

  The PostgreSQL URL consists of your username, password, and the database name. Replace the respective square-bracketed sections in the line below and set it as the value for DATABASE_URL:

  postgres://[USERNAME]:[PASSWORD]@localhost:5432/[DB_NAME]
  

• HOSTNAMES

  For development use, it's okay to set this as a wildcard (i.e., "*"), but for production, you should set this to the URL(s) where the app will be hosted. The values should be wrapped in double-quotes, and multiple URLs should be separated by a space.

client/.env

• Firebase Config

  In your Firebase Project Settings, on the General tab, scroll down to the section titled 'Your apps'. You should see a code snippet with an object named firebaseConfig. Set the values to the following environment variables with the corresponding information:

  REACT_APP_API_KEY=
  REACT_APP_FB_AUTH_DOMAIN=
  REACT_APP_FB_PROJECT_ID=
  REACT_APP_FB_STORAGE_BUCKET=
  REACT_APP_FB_MESSAGING_SENDER_ID=
  REACT_APP_FB_APP_ID=
  

• REACT_APP_FB_DB_URL

  To find your Firebase Realtime Database URL, go to the Realtime Database dashboard in your Firebase project and on the Data tab, click the link icon to copy the URL to set for this variable.

7. (Local PostgreSQL Only) Run Migrations/Seed Data

• These steps are not required when using Docker.

1. Run the following command in the terminal:

   python manage.py migrate

2. You can load seed product data to immediately display when running the app. Run the following command to load the data:

   python manage.py loaddata 004_Products.json

Running the Server

Using Docker

• To start the Docker containers:

  docker compose up

• To stop the Docker containers (use a separate terminal window in the project directory):

  docker compose down

• To update the server Docker container after making changes to the code:

  docker compose build server

Using Local PostgreSQL

• To start the server:

  sh rundev.sh

• To stop the server press Ctrl+C in the terminal window while it is running.

Using the App

Sign Up

A user account is required to access the app.

Creating an account will create a Firebase user record and a user record in the app database. You will be directed to the Onboarding page to select your Home Prefecture.

Log In

Log in with a user account to access the app.

An error will occur if you attempt to log in with an account that does not exist in the app database.

Navbar

The Navbar is how you navigate the app.

Nav Icon	Description
Home	Shows all the products found in the user's Home Prefecture
Bookmarks	Shows all the products bookmarked by the user
Tried Products	Shows all the products logged as 'tried' by the user
Popular	Shows the products with the most 'likes' in the app database
Search	Shows all the products available in the selected prefecture

Product Cards

Buttons are displayed next to a product's image with the following functions:

Button	Description
Bookmark ribbon	Marks a product as 'bookmarked'
Checkmark	Marks a product as 'tried'; displays Like button if active
Thumbs up	Marks a product as 'liked'
Share icon	Invokes the device's share function if available; copies permalink to clipboard otherwise

Settings

Setting	Description
Username	Allows user to change Username
Select Prefecture	Allows user to change Home Prefecture

Clicking 'Save' will save changes and redirect the user back to Home.

Admin Features

Users with the role 'ADMIN' set in the Firebase Realtime Database will have access to the following features:

Add Products

Products can be added to the app database on this page.

Field	Description
Product Name	Product name displayed on Product Card
Link URL	Link accessible by tapping on Product Card
Image	Upload an image to display in app
Start Date (optional)	The date the product will become available
End Date (optional)	The date the product will no longer be available
Location Options	Prefectures to choose from when setting product's available locations
Add & Remove Buttons	These buttons move Prefecture options between the Location Options and Selected Locations lists
Selected Locations	Prefectures selected as the product's availability

Credits

Name	Title / Position	GitHub or Social Media
Joe V.	- Tech Lead - DevOps & CI/CD - Support	https://github.com/kappanjoe
Nicole Boci	- Product Owner - Fullstack Engineer - Server - Data Sourcing	https://github.com/nikobatzi1990
Ikuno Kanasugi	- Fullstack Engineer - Data Sourcing - Database	https://github.com/ikuno815
Chadwick Au	- Fullstack Engineer - Client Pages - UI Components	https://github.com/SirrorsMoore1975

License

MIT License

Copyright (c) 2023 OriOri-CCP7

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.