https://github.com/pokusew/mojekucharka-zwa
A simple web app for managing recipes
https://github.com/pokusew/mojekucharka-zwa
Last synced: 2 months ago
JSON representation
A simple web app for managing recipes
- Host: GitHub
- URL: https://github.com/pokusew/mojekucharka-zwa
- Owner: pokusew
- Created: 2021-11-29T02:50:58.000Z (over 3 years ago)
- Default Branch: mongodb
- Last Pushed: 2024-02-16T10:14:26.000Z (over 1 year ago)
- Last Synced: 2025-02-13T02:44:47.039Z (4 months ago)
- Language: JavaScript
- Size: 15.8 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Mojekucharka.net 2023 (MongoDB version)
A simple web app for managing recipes
Written in **[PHP]** as an SSR (server-side rendered) web app that should work without JavaScript
(but with JavaScript it is more comfortable to use, i.e. [progressive enhancement][mdn-progressive-enhancement]).
Client-side scripts are written in **[TypeScript]**
and compiled to the latest ECMAScript (JavaScript).
The app targets **only modern browsers** (as it uses the latest HTML5, CSS and ECMAScript features).
❗️ **Note:** This is a special (demo) version of Mojekucharka.net web application that uses [MongoDB] for storing data.
It was created specifically as a submission of the [Extra homework on MongoDB][ctu-fee-ds2-extra-mongodb-hw]
in the [CTU FEE][ctu-fee] ([ČVUT FEL][cvut-fel]) [B4M36DS2 course][ctu-fee-ds2]. The code is based on
the [original MySQL version][mojekucharka-zwa-mysql-version] that was created as a semestral project
in the [CTU FEE][ctu-fee] ([ČVUT FEL][cvut-fel]) [B6B39ZWA course][ctu-fee-zwa].
**Additionally**, the [tests](./tests) 🎭 were created as a semestral project
in the [CTU FEE][ctu-fee] ([ČVUT FEL][cvut-fel]) B4M36ZKS (Software Quality Assurance) course.
## Content
- [Description](#description)
- [User Manual](#user-manual)
- [Architecture](#architecture)
- [Technology highlights](#technology-highlights)
- [Backend](#backend)
- [Backend tooling](#backend-tooling)
- [Frontend](#frontend)
- [Frontend tooling](#frontend-tooling)
- [Security](#security)
- [Development](#development)
- [Requirements](#requirements)
- [Set up](#set-up)
- [Available commands](#available-commands)
- [Deployment](#deployment)
## Description
👉 See [this Google Docs document][mojekucharka-desc-doc] (in Czech).
[mojekucharka-desc-doc]: https://docs.google.com/document/d/1go3qb_ei5DVzYgW5VXdc5Khsog45C1alVgtiq0YLpaE/edit?usp=sharing
## User Manual
👉 See [User Manual 📘](./docs/USER-MANUAL.md).
## Architecture
👉 Please see the full **[Technical Manual 📕](./docs/TECHNICAL-MANUAL.md)** that describes the architecture in detail.
### Technology highlights
_Note: The web app was created as a submission of the [Extra homework on MongoDB][ctu-fee-ds2-extra-mongodb-hw]
in the CTU FEE [B4M36DS2 course][ctu-fee-ds2]. Furthermore, the code is based on the
[original MySQL version][mojekucharka-zwa-mysql-version] that was created as a semestral project
in the CTU FEE [B6B39ZWA course][ctu-fee-zwa]. So the architecture of this app was affected by
the [B4M36DS2's Extra homework on MongoDB requirements][ctu-fee-ds2-extra-mongodb-hw] and
the [B6B39ZWA's semestral project's requirements][ctu-fee-zwa-semestral-project]._
#### Backend
* SSR web app in PHP, works without JS
* data stored in MongoDB (accessed using the official MongoDB PHP Driver)
* almost zero dependencies, no frameworks, plain PHP, everything from scratch
* custom-built micro MVC framework with DI (dependency injection)
#### Backend tooling
* [PHPStan] – PHP linter
#### Frontend
* HTML5, CSS, JavaScript (TypeScript compiled to the latest ECMAScript)
* no dependencies, no frameworks, plain CSS/Sass, TypeScript, everything from scratch
* HTML5 semantic elements
* CSS – fully responsive, Flexbox, Grid, animations, transitions, transforms, media queries, ...
* [PWA web app manifest](./frontend/manifest.json)
including [maskable icons][web-dev-maskable-icons] (but no offline support)
#### Frontend tooling
* [webpack] – an assets bundler
* [Babel] – a JavaScript compiler (transpiler)
* CSS written in [Sass] (SCSS), vendor prefixes automatically added by [Autoprefixer]
with [Browserslist]
#### Security
* [Subresource Integrity (SRI)][mdn-sri]
for all scripts and styles
## Development
This section covers setting up everything so that you can get the app running locally on your machine and start
developing.
It also describes the commands that are available to run and automate things
(mainly through `yarn`, `composer` and `make`).
### Requirements
- for running scripts: a POSIX-compliant OS (such as Linux, macOS) (Bash, make, sed, cp)
- [PHP] 8.2+ _(backend)_
- [Composer] _(PHP tooling)_
- [phpDocumentor] 3+ _(generating HTML docs from PHPDoc)_
- [Node.js] >=18.x _(frontend tooling)_
- [Yarn-v1] 1.x _(frontend tooling)_
- You can follow [this Node.js and Yarn Development Setup guide](./NODEJS-SETUP.md).
### Set up
1. Install all PHP dependencies using Composer:
```bash
composer install
```
2. Install all Node.js dependencies using Yarn:
```bash
yarn
```
3. Start a frontend webpack development server with HMR and keep it running:
```bash
yarn start
```
4. Copy the config template and fill it with correct values (mainly for the database connection):
```bash
cp config/config.template.php config/config.local.php
# now fill config/config.local.php with correct values
```
5. Run the app using the built-in PHP web server:
```bash
make run
# make SERVER=addr:port run
```
6. By default, the app will be listening on `http://localhost:8007/`.
### Available commands
* `yarn start` – Starts a frontend webpack development server with [HMR (hot module replacement)][webpack-hmr]. First,
it builds the development version of the frontend assets and outputs them to the `build/development` dir. Then it
continuously and incrementally rebuilds the assets when sources (sourcecode) change. When it is possible (for styles
and scripts), it applies the changes using [HMR][webpack-hmr] without the need for a full browser page refresh.
* `yarn build` – Builds the production version of the frontend assets and outputs them to the `build/production` dir.
Note: Before running an actual build, `build/production` dir is purged.
* `yarn analyze` – Same as `yarn build` but it also outputs `build/stats.production.json`
and runs [webpack-bundle-analyzer CLI][webpack-bundle-analyzer-cli].
* `yarn tsc` – Runs TypeScript compiler. Outputs type errors to console.
* `yarn lint` – Runs [ESLint]. Outputs errors to console.
* `make run` – Runs the app using the built-in PHP web server.
* Optional arguments:
* `MODE` – `development` (default value), `production`
* `SERVER` – `localhost:8007` (default value), any value with format `addr:port`
* Usage examples:
* `make MODE=development run`
* `make MODE=production SERVER=localhost:4000 run`
* `make deploy` – Deploy the app to the specified target. Runs `deploy/$TARGET/deploy.sh`.
* Optional arguments:
* `TARGET` – `fel-ds2.mojekucharka.net` (default value), `docs`
* Usage:
* `make deploy`
* `make TARGET=fel-ds2.mojekucharka.net deploy`
* `make destroy` – Destroys the app deployment on the specified target. Runs `deploy/$TARGET/destroy.sh`.
* Optional arguments:
* `TARGET` – `fel-ds2.mojekucharka.net` (default value), `docs`
* Usage:
* `make deploy`
* `make TARGET=fel-ds2.mojekucharka.net deploy`
* `make lint` – Runs [PHPStan](https://phpstan.org/). Outputs errors to console. PHPStan will automatically use the
[phpstan.neon](./phpstan.neon) config file in the project root.
* `make docs` – Generates HTML docs from PHPDoc using [phpDocumentor].
* `make docs-deploy` / `make-docs-deploy-destroy` – Deploys docs or destroy the deployment.
## Deployment
* the app to https://fel-ds2.mojekucharka.net/ **(currently not deployed)**:
* see [these notes](./deploy/fel-ds2.mojekucharka.net/README.md)
* `make TARGET=fel-ds2.mojekucharka.net deploy`
* `make TARGET=fel-ds2.mojekucharka.net destroy`
* the phpDocumentor-generated docs to https://mojekucharka-zwa-docs.netlify.app/:
* see [these notes](./deploy/docs/README.md)
* `make docs-deploy`
* `make docs-deploy-destroy`
[MongoDB]: https://www.mongodb.com/
[PHP]: https://www.php.net/manual/en/
[Composer]: https://getcomposer.org/
[PHPStan]: https://phpstan.org/
[phpDocumentor]: https://phpdoc.org/
[Node.js]: https://nodejs.org/en/
[Yarn-v1]: https://classic.yarnpkg.com/lang/en/
[webpack]: https://webpack.js.org/
[webpack-hmr]: https://webpack.js.org/guides/hot-module-replacement/
[webpack-bundle-analyzer-cli]: https://github.com/webpack-contrib/webpack-bundle-analyzer#usage-as-a-cli-utility
[Babel]: https://babeljs.io/
[Sass]: https://sass-lang.com/
[Autoprefixer]: https://github.com/postcss/autoprefixer
[Browserslist]: https://github.com/browserslist/browserslist
[TypeScript]: https://www.typescriptlang.org/
[ESLint]: https://eslint.org/
[mdn-progressive-enhancement]: https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement
[mdn-sri]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
[web-dev-maskable-icons]: https://web.dev/maskable-icon/
[ctu-fee]: https://fel.cvut.cz/en/
[cvut-fel]: https://fel.cvut.cz/cz/
[ctu-fee-zwa]: https://cw.fel.cvut.cz/wiki/courses/b6b39zwa/start
[ctu-fee-zwa-semestral-project]: https://cw.fel.cvut.cz/wiki/courses/b6b39zwa/classification/semestralka
[ctu-fee-ds2]: https://cw.fel.cvut.cz/wiki/courses/be4m36ds2/start
[ctu-fee-ds2-extra-mongodb-hw]: https://docs.google.com/document/d/1Dt7SZRiKDnyDfRMDtpAXU1EFcNlstb75zQh97b8kjYw/edit?usp=sharing
[mojekucharka-zwa-mysql-version]: https://github.com/pokusew/mojekucharka-zwa/tree/main