🧩 Simple Modular FastAPI Backend

A minimal, module-based FastAPI backend with:

• Feature-first structure (modules/*)
• JWT authentication
• PostgreSQL + PostGIS (Docker only)
• Backend runs locally inside a virtual environment

---

⚙️ Requirements

• Python 3.10+
• Docker & Docker Compose

---

🚀 First-Time Setup (Windows)

1️⃣ Clone the repository

git clone <repo-url>
cd backend

---

2️⃣ Allow PowerShell to activate venv (one-time per terminal)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

---

3️⃣ Create and activate virtual environment

.\.venv\Scripts\Activate.ps1

You should now see:

(.venv)

---

4️⃣ Install dependencies

python -m pip install --upgrade pip
pip install -r requirements.txt

---

🐳 Start Database (PostGIS)

docker compose up -d

PostgreSQL + PostGIS will be available on:

localhost:5432

---

▶️ Run the Backend (ALWAYS inside venv)

uvicorn app.main:app --reload

---

📚 API Documentation

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

---

🔐 Authentication (JWT)

• JWT logic is in app/core/security.py
• Protect routes using:

Depends(get_current_user)

Clients must send:

Authorization: Bearer <token>

---

⚠️ Important Rules

✅ Always run inside the virtual environment

If (venv) is not visible in the terminal, the app will not work correctly.

To re-enter venv anytime:

.\.venv\Scripts\Activate.ps1

🧩 Creating a New Module

1. Create a new folder:

app/modules/<module_name>/

2. Add these files:

router.py
service.py
repository.py
models.py
schemas.py

3. Register the router in app/main.py:

from app.modules.<module_name>.router import router as module_router
app.include_router(module_router, prefix="/<module_name>")

🗄️ Database Migrations (Quick Guide)

Whenever you add or modify a database model:

1. Register the model

   # Add your model import to:
   app/db/models.py
   

2. Generate a migration

   alembic revision --autogenerate -m "describe your change"

3. Apply the migration

   alembic upgrade head

That’s it.

⚠️ Never edit the database schema manually. ⚠️ Never delete or modify existing migration files.

🧠 Environment Variables

All required values are defined in .env:

ENVIRONMENT=local

SECRET_KEY=supersecret
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60

POSTGRES_USER=app
POSTGRES_PASSWORD=app
POSTGRES_DB=app
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

---

🧪 Common Commands

Activate venv

.\.venv\Scripts\Activate.ps1

Start DB

docker compose up -d

Run backend

uvicorn app.main:app --reload

Stop DB

docker compose down

---

🎯 Philosophy

• Keep infrastructure minimal
• Keep modules isolated
• Add complexity only when needed
• Optimize for speed and clarity

---