Merge pull request 'chore: initial project scaffolding with fastapi, docker and modular' (#1) from feat/setup into main

Reviewed-on: #1

.env_example

@@ -0,0 +1,7 @@
+PROJECT_NAME="Playtomic Wrapper"
+VERSION="1.0.0"
+API_V1_STR="/api/v1"
+
+PLAYTOMIC_EMAIL="tua@email.it"
+PLAYTOMIC_PASSWORD="la_tua_password"
+PLAYTOMIC_API_URL="https://api.playtomic.io"

.gitignore

@@ -0,0 +1,13 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+env/
+
+# Config
+.env
+
+# IDE
+.vscode/
+.idea/

Dockerfile

@@ -0,0 +1,30 @@
+# Usa un'immagine Python ufficiale leggera
+FROM python:3.11-slim
+
+# Imposta variabili d'ambiente per Python
+# PYTHONDONTWRITEBYTECODE: evita la scrittura dei file .pyc
+# PYTHONUNBUFFERED: permette di vedere i log in tempo reale
+ENV PYTHONDONTWRITEBYTECODE 1
+ENV PYTHONUNBUFFERED 1
+
+# Imposta la directory di lavoro
+WORKDIR /code
+
+# Installa le dipendenze di sistema necessarie (opzionale, ma utile per alcune lib)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copia i file delle dipendenze
+COPY pyproject.toml .
+# Se hai anche un requirements.txt, copialo, altrimenti installa via pyproject
+RUN pip install --no-cache-dir .
+
+# Copia il resto del codice dell'applicazione
+COPY . .
+
+# Espone la porta su cui girerà FastAPI
+EXPOSE 8000
+
+# Comando per avviare l'app con Uvicorn
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

README.md

@@ -1 +1,36 @@
-# Playtomic Wrapper
+# Playtomic API Wrapper 🎾
+
+A **FastAPI-based** microservice that provides a clean, structured REST interface over Playtomic's private APIs. It automatically handles authentication, token persistence, and data normalization.
+
+## 🚀 Key Features
+
+- **Auto-Auth**: Manages Bearer tokens and handles automatic 401 refresh logic.
+- **Modular Design**: Organized by domain (Users, Bookings, Clubs) for easy scaling.
+- **Docker-Ready**: Fully containerized with Docker Compose for instant deployment.
+- **Auto-Documentation**: Integrated Swagger UI and ReDoc.
+- **Developer Friendly**: Built with modern Python standards (PEP 621, Pydantic v2).
+
+## 🛠 Tech Stack
+
+- **Python 3.11+**
+- **FastAPI** (Web framework)
+- **Pydantic** (Data validation & Settings)
+- **Requests** (HTTP Client with Session reuse)
+- **Docker & Docker Compose**
+
+---
+
+## 🚦 Getting Started
+
+### 1. Configuration
+
+Create a `.env` file in the project root based on the provided environment variables:
+
+```env
+PROJECT_NAME="Playtomic Wrapper"
+VERSION="1.0.0"
+API_V1_STR="/api/v1"
+
+PLAYTOMIC_EMAIL="your_email@example.com"
+PLAYTOMIC_PASSWORD="your_password"
+PLAYTOMIC_API_URL="[https://api.playtomic.io](https://api.playtomic.io)"

app/api/v1/router.py

@@ -0,0 +1,4 @@
+from fastapi import APIRouter
+
+api_router = APIRouter()
+# Qui includi tutti i moduli (scope) che creerai

app/core/config.py

@@ -0,0 +1,17 @@
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "Playtomic Wrapper"
+    VERSION: str = "1.0.0"
+    API_V1_STR: str = "/api/v1"
+
+    PLAYTOMIC_EMAIL: str
+    PLAYTOMIC_PASSWORD: str
+    PLAYTOMIC_API_URL: str = "https://api.playtomic.io"
+
+    class Config:
+        env_file = ".env"
+
+
+settings = Settings()

app/main.py

@@ -0,0 +1,17 @@
+from fastapi import FastAPI
+
+from app.api.v1.router import api_router
+from app.core.config import settings
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version=settings.VERSION,  # Versioning dell'app
+)
+
+# Montiamo le rotte sotto il prefisso /api/v1
+app.include_router(api_router, prefix=settings.API_V1_STR)
+
+
+@app.get("/health")
+def health_check():
+    return {"status": "ok", "version": settings.VERSION}

docker-compose.yml

@@ -0,0 +1,18 @@
+version: "3.8"
+
+services:
+  playtomic-wrapper:
+    build: .
+    container_name: playtomic_api_wrapper
+    # Mappa la porta 8000 del container sulla 8000 del tuo PC
+    ports:
+      - "8000:8000"
+    # Carica le credenziali dal file .env
+    env_file:
+      - .env
+    # Volumi: permette di modificare il codice e vedere i cambiamenti
+    # senza riavviare il container (Hot Reload)
+    volumes:
+      - .:/code
+    # Riavvia il container se crasha (a meno che non venga stoppato a mano)
+    restart: unless-stopped

pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "playtomic-wrapper"
+version = "1.0.0"
+description = "A FastAPI wrapper for Playtomic private APIs"
+authors = [
+    { name = "Tuo Nome", email = "tua@email.it" }
+]
+dependencies = [
+    "fastapi>=0.109.0",
+    "uvicorn[standard]>=0.27.0",
+    "pydantic-settings>=2.1.0",
+    "requests>=2.31.0",
+]
+requires-python = ">=3.10"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+# Configurazione opzionale per il linter (molto consigliato)
+line-length = 88
+select = ["E", "F", "I"]

requirements.txt

@@ -0,0 +1,20 @@
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.12.1
+certifi==2026.1.4
+charset-normalizer==3.4.4
+click==8.1.8
+exceptiongroup==1.3.1
+fastapi==0.128.0
+h11==0.16.0
+idna==3.11
+pydantic==2.12.5
+pydantic-settings==2.11.0
+pydantic_core==2.41.5
+python-dotenv==1.2.1
+requests==2.32.5
+starlette==0.49.3
+typing-inspection==0.4.2
+typing_extensions==4.15.0
+urllib3==2.6.3
+uvicorn==0.39.0