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
• Requirements
• Environment Variables
• Database Migrations
• Seeding (seed scripts)
• Run the API
• API Docs
• Project Layout (high level)
• Testing
• Troubleshooting & Notes
• Contributing
• License

---

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"

2. Create and activate a virtual environment and install dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. 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

4. 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.