SST Frontend

Databases

All data is stored in MySQL databases for dev/staging/prod, these are databases in GCP's Cloud SQL. The local databases are stored in sqlite. See database/migrations/ for a view of all the databases tracked and generated by the frontend.

Note that the users table is the only one that, in production, is shared by the frontend and backend. That means, the table definition needs to be kept in sync between the API repo and this repo. If you make changes to the database here, make sure to make those changes in the sst-app-api repo as well.

Development environments

1. Local development with calls to external systems are mocked out. See the mocked out values in Http/Controllers/ApiController.php.
2. Dev environment with fake data to test integration with the API + GCP databases
3. Staging environment with real data (potentially sampled if your datasets are large) to test real data flowing through the full end to end setup of a real system that mimics prod.
4. Prod environment with real data on real systems.

It's not recommended for the local environment to connect to the dev environment. The four environments, local, dev, staging, prod, should ideally be isolated from each other.

While working in the local environment, it's recommended you mock out/stub out the calls to external systems like the backend API. For references as to what the backend API input/output looks like, see the API endpoint swagger documentation. If you don't want to do that feel free to spin up a local version of the backend and update the .env fields for the frontend/backend to reflect the connection, keeping in mind that because each local program is spun up with its own isolated databases, you'll have two users tables that are isolated even though in deployed environments, they'd be reading/writing the same users table.

Environment Variables

For the deployed instances (dev, staging, prod) database related environment variables are set in the terraform templates, but most are set per project in Cloud Secret Manager. To update the environment variables in secret manager, create a new version from the UI, copying the previous values with your changes.

Comment on Deployment

• Dev environment: gets deployed upon any new commit to b/develop.
• Staging environment: requires manual Cloud Build Trigger Run initiated by a human to pick up the most recent changes from b/develop.
• Prod environment: requires manual Cloud Build Trigger Run initiated by a human to pick up the most recent changes from b/develop.

For more information on deployment, see the Terraform setup and the GCP setup in the GCP console.

Local Development

Prerequisites:

You only have to do this once in your local development system.

1. brew install composer (Assuming you are on Mac, but install as you think best)
2. brew install npm (Assuming you are on Mac, but install as you think best)

Spinning up the frontend

1. Clone this project
2. cd [project-name]
3. Copy .env.example file to .env in the root of the repo folder and populate needed values.
4. Open two terminals and navigate to the root directory of the cloned repo.
5. In one of the terminals, run ./local_run sh which performs the following

• composer install
• npm install + cache clearing
• php artisan key:generate
• php artisan migrate
• npm run dev

6. In another terminal, run php artisan serve

NOTE: if you've made any database definition changes and want to reload the db you will have to remove the database/database.sqlite file before running ./local_run.sh.

Optionally install the React Dev Tools: https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en

Use console.log() and fn+12 to open the chrome dev panel.

Feel free to modify the mocked out return values in Http/Controllers/ApiController.php if you want to test other cases.

Creating users in the local frontend

To create a test user, use the same process you would to create a user normally, which is, hit the register button and register a user with email and password. This will create a user that doesn't have an access_type or institution. To change the access_type of your local user, modify the user's access_type in the local sqlite users table.

This is required for the first datakinder type user, as only datakinder users can add other datakinders or perform many admin-only actions. At initial set up time of the local development environment, you won't have any existing datakinder type users, and when you create users in the frontend you can't escalate your own permissions. Because of this, the first datakinder will need to be manually set.

You can do that via the sqlite commandline functionality where you can issue direct sql queries to your local sqlite database https://sqlite.org/cli.html.

1. cd database
2. sqlite3 database.sqlite
3. Issue commands like select * from users; or update users set access_type = 'DATAKINDER' where email = '<the email of the user you've created>';

NOTE: The local database is sqlite, the deployed databases in GCP are all mysql.

NOTE: for dev and staging, email verification is turned off. Email verification IS required in prod.

Other Notes

Frameworks Used

the Student Success Tool is built on:

• Laravel Framework. Documentation

• Inertiajs. Documentation

• Reactjs. Documentation

• Tailwindcss. Documentation

Notes on files and locations of interest

• routes/web.php is the main entrypoint to define all routes and available functions.
• resources/js/Layouts/AppLayout.jsx contains the page layout and function renderNavLinks() modifies which links are available in the nav bar.
• resources/js/Pages/ contains all the separate page views (e.g. Welcome.jsx is the front page, Dashboard.jsx is what's shown when the Dashboard route is clicked etc.)

So for example, to add a new page, Foopage, which you'd like to be visible in the nav bar, you'd have to:

1. Add a Foopage route in web.php (include auth middleware if that page should require user login: Route::middleware('auth')->get('/foopage', function () { return Inertia::render('Foopage'); })->name('foopage');
2. In AppLayout.jsx add the Foopage item to route mapping in renderNavLinks(): const renderNavLinks = () => (['home', 'FAQ', 'data-dictionary', 'dashboard', 'foopage'].map((routeName)...
3. Add a Foopage.jsx file under resources/js/Pages/... subdirectory that contains the actual page rendering code.

General Notes

Postgresql does not work with certs that are volume mounted secrets in GCP, so using mysql.