backoffice-ordering-system

Backend

All commands are executed in /backend dir and inside a poetry shell (unless stated otherwise).

Dependencies

I recommend using mise for python versioning (check /.mise.toml for exact version)

• python 3.12
• poetry - dependency management, building, packaging, scripting (after installing python, run python -m pip install poetry to install)

Tech stack

• fastapi - server framework
• sqlmodel - ORM
• pydantic - models, serialization, ENV
• alembic - migrations
• postgresql - db

Refer to the documentations linked if some info is missing here.

Install deps

poetry install

From now on, execute every command inside a poetry shell:

poetry shell

Run dev server

uvicorn app.main:app --reload --host localhost

Run docker dependencies

Excluding the actual service. When developing, you should be using "bare-metal" uvicorn because it allows you to reload seamlessly, and you don't need to rebuild the image on every code change.

Remove the --scale param to also launch the backend.

docker compose up --scale bos-backend=0

Migrations

Run pending migrations:

alembic upgrade head

Generate a new migration based on your new models

alembic revision --autogenerate -m "{MIGRATION NAME}"

IMPORTANT: ALL models NEED to be exported in the /backend/app/models/__init__.py file for them to be picked up by alembic! Like so:

from .ticket import *

(I will know you didn't read the README if you raise this problem)

Run tests

poetry run pytest tests/

Run linters/formatters

Check mode

black --check --verbose app/ && isort --check-only --verbose app/ && bandit -r --verbose app/ && mypy app/ && pylint --verbose app/

Write mode

black app && isort app

PS: Tests and linters will also run on GitHub push so you better run and check them locally first :)

ENV

We're using automatic env parsing lib (pydantic-settings). Check /backend/app/config.py for more details.

NOTE: They need to be present on the server host/container BEFORE starting the server to be respected.

• DB_HOST - host of the postgres server (default: localhost)
• DB_PORT - port of the postgres server (default: 5432)
• DB_USER - user of the postgres server (default: pg)
• DB_PASSWORD - password of the postgres server (default: pg), for production this needs to be changes, obviously
• DB_NAME - name of the postgres db (default postgres)

Frontend

All commands are executed in /frontend dir (unless stated otherwise).

Dependencies

I recommend using mise for node versioning (check /.mise.toml for exact version)

• node@21 - js runtime
• npm - dependency management, building, packaging, scripting (will be installed alongside node)

Tech stack

• Typescript - typing, transpiler
• React 18 - frontend framework
• React Router - client-side routing
• Vite - react initialization/management
• hey-api/openapi-ts - automatic client generation

Install deps

npm install

Run dev server

npm run dev

Build production assets

They will be in the /frontend/dist/ directory. They will be ready to be served on production.

npm run build

Run linters/formatters

Check-only mode

npm run lint

Write mode

npm run format

PS: Linters will also run on GitHub push so you better run and check them locally first :)

Generate Typescript client (for dev)

NOTE: Backend must be running (on http://localhost:8000) for this to work

npm run generate-client

ENV

NOTE: They need to be present to be respected while building the app with npm run build for production.

• VITE_BACKEND_URL - url of the backend server (default: http://localhost:8000)