Skip to content

README.md

Latest commit

 

History

History
276 lines (238 loc) · 8.47 KB

README.md

File metadata and controls

276 lines (238 loc) · 8.47 KB

MULTI-CAFE-POS-BE

FastAPI backend for a multi-cafe Point of Sale (POS) system. Provides RESTful APIs for managing cafes, products, orders, users, authentication, roles, and more.

Table of Contents

Quick Start

  1. Clone the repo and enter the project directory:
git clone <repo-url>
cd "12. python/M5. Python Web Frameworks/MULTI-CAFE-POS-BE"
  1. Create and activate a virtual environment and install dependencies:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
  1. Copy .env.example to .env and edit values (particularly DATABASE_URL and DEFAULT_ADMIN_*):
cp .env.example .env
# then edit .env with your DB credentials and other settings
  1. Run database migrations and then seed initial data (order matters — see Seeding section):
alembic upgrade head
python scripts/seed_roles.py
python scripts/seed_subscription_plans.py
python scripts/seed_categories.py
python scripts/seed_items.py
python scripts/seed_products.py
python scripts/seed_default_admin.py

Notes:

  • The seed scripts are in the scripts/ directory and expect a configured .env (see .env.example).
  • seed_default_admin.py uses DEFAULT_ADMIN_* values from .env.

Requirements

  • Python 3.10+ (project uses async drivers like asyncpg)
  • PostgreSQL (recommended) or another DB supported by SQLAlchemy/asyncpg
  • See requirements.txt for full dependency list

Environment Variables

Copy .env.example and fill these at minimum:

  • DATABASE_URL — e.g. postgresql+asyncpg://user:password@localhost:5432/multi_cafe_pos
  • SECRET_KEY — strong secret for JWT
  • JWT_ALGORITHM — e.g. HS256
  • ACCESS_TOKEN_EXPIRE_MINUTES — token expiry
  • DEFAULT_ADMIN_NAME, DEFAULT_ADMIN_EMAIL, DEFAULT_ADMIN_PASSWORD — used by scripts/seed_default_admin.py
  • SMTP settings (optional) for password reset email functionality

Database Migrations

  • Alembic is configured. To create a migration after model changes:
alembic revision --autogenerate -m "describe change"
alembic upgrade head

If you need to run Alembic with a specific config file:

alembic -c alembic.ini upgrade head

Seeding (seed scripts)

Seed scripts are located in scripts/. Recommended order:

  1. python scripts/seed_roles.py
  2. python scripts/seed_subscription_plans.py
  3. python scripts/seed_categories.py
  4. python scripts/seed_items.py
  5. python scripts/seed_products.py
  6. python scripts/seed_default_admin.py

Run them directly from the project root after .env and migrations are applied. Example:

# from project root
python scripts/seed_roles.py
python scripts/seed_default_admin.py

Each script prints its progress and will exit if it cannot connect to the database — ensure DATABASE_URL is correct and the DB is reachable.

Run the API

Run using Uvicorn (project exposes main:app):

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Base URL: http://localhost:8000

API Docs

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

Project Layout (actual)

.
.
├── alembic
│   ├── env.py
│   ├── README
│   ├── script.py.mako
│   └── versions
│       ├── 0cf912000588_edited_user_and_role_table_fields_length.py
│       ├── 1ce77decbee5_created_base_declarative_class.py
│       ├── 4aa2d6f9c1b7_add_cafe_approval_flag.py
│       ├── 4f769869009a_create_auth_token_tables.py
│       ├── 5bb3e1c4a8d2_convert_cafe_approval_to_status.py
│       ├── 6d9e5f4bf0c2_drop_auth_token_tables.py
│       ├── 7a3f2d1c9b44_make_user_password_nullable.py
│       ├── 9350d45373dc_create_cafe_staff_table.py
│       ├── 9dbd7a78dbe1_add_cafe_id_to_users.py
│       ├── 9f92d61855e8_insert_role_table.py
│       ├── a1d9d5d6f2be_add_served_to_order_status_enum.py
│       ├── b4f1a2548a11_update_images_for_cafe_and_menu.py
│       ├── cde0e95ffb34_initial_setup.py
│       ├── df79981cbcc3_all_models_are_implemented.py
│       ├── e97686754352_created_user_table.py
│       ├── f53a3d831a7e_update_order_payments_schema.py
├── alembic.ini
├── app
│   ├── api
│   │   ├── __init__.py
│   │   └── v1
│   │       ├── __init__.py
│   │       └── routes
│   │           ├── auth.py
│   │           ├── cafes.py
│   │           ├── catalog.py
│   │           ├── __init__.py
│   │           ├── orders.py
│   │           ├── payments.py
│   │           ├── roles.py
│   │           ├── subscriptions.py
│   │           └── users.py
│   ├── authentication
│   ├── config
│   │   ├── config.py
│   │   ├── __init__.py
│   ├── core
│   │   ├── constants.py
│   │   ├── database.py
│   │   ├── __init__.py
│   │   ├── response.py
│   │   └── security.py
│   ├── dependencies
│   │   ├── auth.py
│   │   ├── cafe.py
│   │   ├── __init__.py
│   │   ├── roles.py
│   │   └── subscription.py
│   ├── __init__.py
│   ├── models
│   │   ├── base_declarative_model.py
│   │   ├── cafe_product.py
│   │   ├── cafe.py
│   │   ├── cafe_staff.py
│   │   ├── cafe_table.py
│   │   ├── category.py
│   │   ├── enums.py
│   │   ├── image.py
│   │   ├── __init__.py
│   │   ├── item.py
│   │   ├── order_item.py
│   │   ├── order.py
│   │   ├── payment.py
│   │   ├── product.py
│   │   ├── role.py
│   │   ├── subscription_payment.py
│   │   ├── subscription_plan.py
│   │   ├── subscription.py
│   │   └── user.py
│   ├── repositories
│   │   ├── cafe.py
│   │   ├── cafe_staff.py
│   │   ├── cafe_table.py
│   │   ├── catalog.py
│   │   ├── __init__.py
│   │   ├── order.py
│   │   ├── payment.py
│   │   ├── role.py
│   │   ├── subscription.py
│   │   └── user.py
│   ├── schemas
│   │   ├── auth.py
│   │   ├── catalog.py
│   │   ├── __init__.py
│   │   ├── management.py
│   │   ├── order.py
│   │   ├── payment.py
│   │   ├── response.py
│   │   ├── role.py
│   │   └── subscription.py
│   ├── sereializers
│   │   ├── __init__.py
│   │   └── response.py
│   └── services
│       ├── auth.py
│       ├── cafes.py
│       ├── catalog.py
│       ├── email.py
│       ├── __init__.py
│       ├── orders.py
│       ├── payments.py
│       ├── roles.py
│       ├── subscriptions.py
│       └── users.py
├── FULL_PROJECT_EXPLANATION.md
├── main.py
├── README.md
├── requirements.txt
├── scripts
│   ├── seed_categories.py
│   ├── seed_default_admin.py
│   ├── seed_items.py
│   ├── seed_products.py
│   ├── seed_roles.py
│   └── seed_subscription_plans.py
├── uploads
|── ...

Testing

  • Project includes tests where applicable. Run:
pytest -q

Troubleshooting & Notes

  • If seeds fail with connection errors, verify DATABASE_URL and that the database server accepts connections.
  • If you modify models, create an Alembic revision and run migrations before seeding.
  • Seed scripts are idempotent where possible, but review output before re-running on production databases.

Contributing

Contributions welcome. Please open issues or PRs and follow the standard Git workflow:

git checkout -b feature/your-feature
git commit -m "feat: ..."
git push origin feature/your-feature

License

This project is licensed under the MIT License.