REST API for inventory management using RFID, developed as part of the EmbarcaTech Program. It allows real-time stock verification sessions, product catalog management, and report generation through a structured API with role-based access control.
Built with FastAPI, SQLAlchemy, and PostgreSQL.
- JWT Authentication with token rotation
- Role-based access control —
adminandstockistroles - Parts Management — Complete CRUD with filterable listing
- Stock checking sessions — start, register RFID scans, register events, close, or cancel
- Reports — inventory metrics and PDF generation
- Database migrations via Alembic
- Integration test suite with pytest and an in-memory SQLite database
| Layer | Technology |
|---|---|
| Framework | FastAPI 0.116 |
| ORM | SQLAlchemy 2.0 + psycopg3 |
| Database | PostgreSQL 16 |
| Migrations | Alembic |
| Linting | Ruff |
| Testing | pytest + pytest-asyncio |
| Runtime | Python 3.13 |
git clone {smartstock-backend repository}
cd smartstock-backendcp .env.example .envEdit the .env file with the necessary configurations.
# Start the services
docker compose -f local.yml up
# Start and force rebuild of images
docker compose -f local.yml up --buildTo stop and remove containers:
docker compose -f local.yml downThe API will be available at http://localhost:8000. The interactive documentation is at http://localhost:8000/docs.
docker compose -f local.yml run --rm fastapi task cli createsuperuserdocker compose -f local.yml run --rm fastapi task cli seedThe API is divided into the following resource groups:
/auth— Login, token refresh, and authenticated user data/produtos— Products CRUD (mutations restricted toadmin)/inventarios— Stock checking sessions with RFID scans and events/relatorios— Inventory metrics and PDF export/usuarios— User management (restricted toadmin)
All endpoints require a Bearer token unless stated otherwise. Complete interactive documentation with request/response examples is available at /docs.
The project includes integration tests written with pytest. See tests/README.md for full documentation.
| Task | Command | Description |
|---|---|---|
up |
task up |
Starts the development server with reload |
migrate |
task migrate |
Applies database migrations |
makemigrations |
task makemigrations "msg" |
Generates a new migration |
createsuperuser |
task createsuperuser |
Creates an admin user interactively |
cli seed |
task cli seed |
Populates the database with sample products |
test |
task test |
Runs the test suite |
test-cov |
task test-cov |
Runs tests with an HTML coverage report |
requirements |
task requirements |
Regenerates requirements.txt via uv |
app/
├── main.py # FastAPI app and middleware configuration
├── auth.py # JWT token creation and verification
├── database.py # SQLAlchemy session management
├── settings.py # Environment variable-based configuration
├── seed.py # Sample data population
├── cli/ # CLI with Typer (createsuperuser, seed)
├── core/ # Exception handlers and shared utilities
├── models/ # SQLAlchemy ORM models
├── schemas/ # Pydantic request/response schemas
├── crud/ # Database query functions
└── routers/ # FastAPI route handlers
tests/ # Integration tests (pytest + in-memory SQLite)
tk_client/ # Optional Tkinter desktop client for local testing
migrations/ # Alembic migrations history
The tk_client/ directory contains a Tkinter interface for local API testing, without the need for tools like curl or Postman. To use it, set up a local Python environment and run:
python tk_client/main.pyPrerequisite: Python 3.13 installed locally with the dependencies for
tk_client/.
This project is licensed under the MIT License. See the LICENSE file for more details.
This project was created and maintained by:
Developed for the Smart Stock project under the EmbarcaTech Program.