Initial commit

Author: adiffpirate

.gitignore

@@ -0,0 +1,62 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Test / coverage
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Type checkers
+.mypy_cache/
+.pyre/
+.pytype/
+
+# IDE / editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# SQLite (tests / local)
+*.db
+*.sqlite3
+
+# Alembic (keep migrations, ignore cache)
+alembic/__pycache__/
+
+# Docker (optional, if you use later)
+docker-compose.override.yml
+
+# Misc
+*.bak
+*.tmp

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luiz K. Monteiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,175 @@
+# Order Management System API
+
+A simple, modular FastAPI application for managing orders.
+Built as a **modular monolith** with clean separation of concerns, PostgreSQL for persistence,
+Alembic for migrations, and SQLite for fast unit tests.
+
+## 📁 Project Structure
+
+```
+.
+├── app/
+│   ├── main.py
+│   ├── api/
+│   │   └── router.py
+│   ├── core/
+│   ├── db/
+│   │   └── session.py
+│   └── modules/
+│       └── orders/
+│           ├── models.py
+│           ├── schemas.py
+│           ├── repository.py
+│           ├── service.py
+│           └── routes.py
+│
+├── alembic/
+├── tests/
+│   └── unit/
+├── pyproject.toml
+└── README.md
+```
+
+## 🐍 Python Virtual Environment (venv)
+
+It’s recommended to use a virtual environment to isolate dependencies.
+
+### Create venv
+
+```bash
+python -m venv .venv
+```
+
+### Activate
+
+**Linux / macOS**
+
+```bash
+source .venv/bin/activate
+```
+
+**Windows (PowerShell)**
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+### Install dependencies
+
+```bash
+pip install --upgrade pip
+pip install -e .[dev]
+```
+
+## 🐘 Running PostgreSQL (Docker)
+
+Start a local PostgreSQL instance:
+
+```bash
+docker run -d \
+  --name postgres-dev \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=app \
+  -p 5432:5432 \
+  postgres:15
+```
+
+## ⚙️ Environment Variables
+
+Set your database connection:
+
+```bash
+export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app
+```
+
+## 🗄️ Database Migrations (Alembic)
+
+Create migration:
+
+```bash
+python -m alembic revision --autogenerate -m "init"
+```
+
+Apply migrations:
+
+```bash
+python -m alembic upgrade head
+```
+
+## ▶️ Run the API
+
+```bash
+uvicorn app.main:app --reload
+```
+
+API will be available at:
+
+```
+http://localhost:8000
+```
+
+Interactive docs:
+
+```
+http://localhost:8000/docs
+```
+
+## 🧪 Running Tests
+
+Tests use **SQLite in-memory**, so no database setup is required.
+
+```bash
+pytest
+```
+
+## 🔌 Example API Usage
+
+### Create Order
+
+```bash
+curl -X POST http://localhost:8000/orders/ \
+  -H "Content-Type: application/json" \
+  -d '{"item": "laptop"}'
+```
+
+### Get Order
+
+```bash
+curl http://localhost:8000/orders/1
+```
+
+### List Orders
+
+```bash
+curl http://localhost:8000/orders/
+```
+
+## 🧠 Architecture
+
+This project uses a **feature-based modular structure**:
+
+* `modules/orders` contains everything related to orders
+* `repository.py` → database access
+* `service.py` → business logic
+* `routes.py` → API layer
+
+This keeps the codebase:
+
+* easy to navigate
+* easy to extend
+* ready to evolve into microservices if needed
+
+## ⚠️ Notes
+
+* Tests use SQLite (`:memory:`) with `StaticPool`
+* Alembic requires models to be imported in `env.py`
+* No need to install the package globally
+
+## 📌 Future Improvements
+
+* Order state transitions (finite state machine)
+* Update / delete endpoints
+* Authentication & authorization
+* Integration tests with PostgreSQL
+* Docker support for full deployment