feat: add FastAPI backend (Phase 1 — feature/backend)

New backend/ package with 35 REST endpoints:
- config.py: pydantic-settings (DB, MinIO, JWT, Ollama, CORS)
- database.py: async SQLAlchemy engine + session dependency
- models/user.py: User, Organization, Role (admin/examiner/viewer)
- models/project.py: Project, Document, Analysis ORM models
- auth/password.py: bcrypt hash/verify
- auth/jwt.py: access token (30min) + refresh token (7d)
- auth/dependencies.py: get_current_user(), require_role()
- routers/auth.py: POST /auth/login|refresh|logout
- routers/users.py: CRUD /users/ + /users/me
- routers/projects.py: CRUD /projects/ + document upload/delete
- routers/analysis.py: POST /analysis/{htr,sig,ner,writer,grapho,pipeline,dating}
- routers/rag.py: streaming SSE /rag/chat + doc management
- storage/minio_client.py: async MinIO wrapper (anyio thread offload)
- main.py: FastAPI app with CORS, lifespan, health check
- Dockerfile: backend container image
- .env.example: environment variable template

Also:
- requirements-backend.txt: fastapi, uvicorn, sqlalchemy[asyncio],
asyncpg, pydantic-settings, python-jose, passlib, minio, anyio
- docker-compose.yml: added postgres, minio, backend, ollama services

All AI processing delegated to core/ — backend is a thin HTTP layer.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/.env.example

@@ -0,0 +1,22 @@
+# Copy this file to .env and fill in the values before running the backend.
+# Never commit .env to git.
+
+# JWT — generate with: openssl rand -hex 32
+SECRET_KEY=change_me_in_production
+
+# Database
+DATABASE_URL=postgresql+asyncpg://grapholab:grapholab@localhost:5432/grapholab
+
+# MinIO
+MINIO_ENDPOINT=localhost:9000
+MINIO_ACCESS_KEY=grapholab
+MINIO_SECRET_KEY=grapholab123
+MINIO_BUCKET=grapholab-docs
+MINIO_SECURE=false
+
+# Ollama
+OLLAMA_HOST=http://localhost:11434
+OLLAMA_MODEL=llama3.2
+
+# Debug (set to true during development)
+DEBUG=false

backend/Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# System deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Python deps
+COPY requirements.txt requirements-backend.txt ./
+RUN pip install --no-cache-dir -r requirements.txt -r requirements-backend.txt
+
+# Application code
+COPY core/ ./core/
+COPY backend/ ./backend/
+COPY data/ ./data/
+
+ENV PYTHONPATH=/app
+CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/auth/dependencies.py

@@ -0,0 +1,57 @@
+"""
+GraphoLab Backend — FastAPI auth dependencies.
+
+Usage in routers:
+    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(require_role(Role.admin))
+"""
+
+from __future__ import annotations
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.auth.jwt import TokenType, decode_token
+from backend.database import get_db
+from backend.models.user import Role, User
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/login")
+
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    credentials_exc = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Credenziali non valide o sessione scaduta.",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = decode_token(token)
+        if payload.get("type") != TokenType.access:
+            raise credentials_exc
+        user_id = int(payload["sub"])
+    except (JWTError, KeyError, ValueError):
+        raise credentials_exc
+
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if user is None or not user.is_active:
+        raise credentials_exc
+    return user
+
+
+def require_role(*roles: Role):
+    """Dependency factory: allow only users with one of the given roles."""
+    async def _check(current_user: User = Depends(get_current_user)) -> User:
+        if current_user.role not in roles:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Permessi insufficienti per questa operazione.",
+            )
+        return current_user
+    return _check

backend/auth/jwt.py

@@ -0,0 +1,50 @@
+"""
+GraphoLab Backend — JWT token creation and verification.
+
+Access tokens: short-lived (30 min default), carry user_id + role.
+Refresh tokens: long-lived (7 days), used only to issue new access tokens.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+
+from jose import JWTError, jwt
+
+from backend.config import settings
+
+
+class TokenType(str, Enum):
+    access = "access"
+    refresh = "refresh"
+
+
+def _now() -> datetime:
+    return datetime.now(tz=timezone.utc)
+
+
+def create_access_token(user_id: int, role: str) -> str:
+    expire = _now() + timedelta(minutes=settings.access_token_expire_minutes)
+    payload = {
+        "sub": str(user_id),
+        "role": role,
+        "type": TokenType.access,
+        "exp": expire,
+    }
+    return jwt.encode(payload, settings.secret_key, algorithm=settings.algorithm)
+
+
+def create_refresh_token(user_id: int) -> str:
+    expire = _now() + timedelta(days=settings.refresh_token_expire_days)
+    payload = {
+        "sub": str(user_id),
+        "type": TokenType.refresh,
+        "exp": expire,
+    }
+    return jwt.encode(payload, settings.secret_key, algorithm=settings.algorithm)
+
+
+def decode_token(token: str) -> dict:
+    """Decode and validate a JWT. Raises JWTError on failure."""
+    return jwt.decode(token, settings.secret_key, algorithms=[settings.algorithm])

backend/auth/password.py

@@ -0,0 +1,15 @@
+"""
+GraphoLab Backend — Password hashing with bcrypt.
+"""
+
+from passlib.context import CryptContext
+
+_ctx = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+def hash_password(plain: str) -> str:
+    return _ctx.hash(plain)
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return _ctx.verify(plain, hashed)

backend/config.py

@@ -0,0 +1,55 @@
+"""
+GraphoLab Backend — Application Settings.
+
+All values can be overridden via environment variables or a .env file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # ── Application ───────────────────────────────────────────────────────────
+    app_name: str = "GraphoLab API"
+    app_version: str = "0.1.0"
+    debug: bool = False
+
+    # ── Security / JWT ────────────────────────────────────────────────────────
+    secret_key: str = "CHANGE_ME_in_production_use_openssl_rand_hex_32"
+    algorithm: str = "HS256"
+    access_token_expire_minutes: int = 30
+    refresh_token_expire_days: int = 7
+
+    # ── Database (PostgreSQL) ─────────────────────────────────────────────────
+    database_url: str = "postgresql+asyncpg://grapholab:grapholab@localhost:5432/grapholab"
+
+    # ── MinIO (S3-compatible storage) ─────────────────────────────────────────
+    minio_endpoint: str = "localhost:9000"
+    minio_access_key: str = "grapholab"
+    minio_secret_key: str = "grapholab123"
+    minio_bucket: str = "grapholab-docs"
+    minio_secure: bool = False
+
+    # ── AI model paths (mirrors Gradio demo defaults) ─────────────────────────
+    signet_weights: Path = Path("data/signet.pth")
+    writer_samples_dir: Path = Path("data/samples")
+    rag_cache_dir: Path = Path("data/rag_cache")
+
+    # ── Ollama ────────────────────────────────────────────────────────────────
+    ollama_host: str = "http://localhost:11434"
+    ollama_model: str = "llama3.2"
+
+    # ── CORS (comma-separated origins for the React frontend) ─────────────────
+    cors_origins: list[str] = ["http://localhost:3000", "http://localhost:5173"]
+
+
+settings = Settings()

backend/database.py

@@ -0,0 +1,44 @@
+"""
+GraphoLab Backend — Async SQLAlchemy database setup.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+
+from backend.config import settings
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=settings.debug,
+    pool_pre_ping=True,
+)
+
+AsyncSessionLocal = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+class Base(DeclarativeBase):
+    """Shared declarative base for all ORM models."""
+    pass
+
+
+async def get_db() -> AsyncSession:
+    """FastAPI dependency: yields an async DB session per request."""
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def init_db() -> None:
+    """Create all tables (called at startup if they don't exist yet)."""
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)

backend/main.py

@@ -0,0 +1,59 @@
+"""
+GraphoLab Backend — FastAPI application entry point.
+
+Run locally:
+    uvicorn backend.main:app --reload --port 8000
+
+Interactive API docs:
+    http://localhost:8000/docs   (Swagger UI)
+    http://localhost:8000/redoc  (ReDoc)
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from backend.config import settings
+from backend.database import init_db
+from backend.routers import auth, users, projects, analysis, rag
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Startup / shutdown lifecycle."""
+    await init_db()
+    yield
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan,
+)
+
+# ── CORS (allow React dev server) ─────────────────────────────────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Routers ───────────────────────────────────────────────────────────────────
+app.include_router(auth.router)
+app.include_router(users.router)
+app.include_router(projects.router)
+app.include_router(analysis.router)
+app.include_router(rag.router)
+
+
+# ── Health check ──────────────────────────────────────────────────────────────
+@app.get("/health", tags=["system"])
+async def health() -> dict:
+    return {"status": "ok", "version": settings.app_version}

backend/models/project.py

@@ -0,0 +1,110 @@
+"""
+GraphoLab Backend — Project and Analysis ORM models.
+
+A Project (= "Perizia") groups one or more Documents and their Analyses.
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+
+from sqlalchemy import DateTime, Enum, ForeignKey, Integer, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.database import Base
+
+
+class ProjectStatus(str, enum.Enum):
+    draft = "draft"
+    in_progress = "in_progress"
+    completed = "completed"
+    archived = "archived"
+
+
+class AnalysisType(str, enum.Enum):
+    htr = "htr"
+    signature_detection = "signature_detection"
+    signature_verification = "signature_verification"
+    ner = "ner"
+    writer_identification = "writer_identification"
+    graphology = "graphology"
+    pipeline = "pipeline"
+    dating = "dating"
+    rag = "rag"
+
+
+class Project(Base):
+    __tablename__ = "projects"
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    title: Mapped[str] = mapped_column(String(256), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    status: Mapped[ProjectStatus] = mapped_column(
+        Enum(ProjectStatus), default=ProjectStatus.draft, nullable=False
+    )
+
+    owner_id: Mapped[int] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    owner: Mapped["User"] = relationship("User", back_populates="projects")
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    documents: Mapped[list[Document]] = relationship(
+        "Document", back_populates="project", cascade="all, delete-orphan"
+    )
+    analyses: Mapped[list[Analysis]] = relationship(
+        "Analysis", back_populates="project", cascade="all, delete-orphan"
+    )
+
+
+class Document(Base):
+    """A file uploaded to a project (stored in MinIO)."""
+
+    __tablename__ = "documents"
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    filename: Mapped[str] = mapped_column(String(512), nullable=False)
+    content_type: Mapped[str] = mapped_column(String(128), nullable=False)
+    storage_key: Mapped[str] = mapped_column(String(512), nullable=False)  # MinIO object key
+    size_bytes: Mapped[int] = mapped_column(Integer, default=0)
+
+    project_id: Mapped[int] = mapped_column(
+        ForeignKey("projects.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    project: Mapped[Project] = relationship("Project", back_populates="documents")
+
+    uploaded_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+
+
+class Analysis(Base):
+    """Result of one AI analysis step on a project document."""
+
+    __tablename__ = "analyses"
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    analysis_type: Mapped[AnalysisType] = mapped_column(Enum(AnalysisType), nullable=False)
+    result_text: Mapped[str | None] = mapped_column(Text, nullable=True)
+    result_storage_key: Mapped[str | None] = mapped_column(
+        String(512), nullable=True  # MinIO key for image/PDF result
+    )
+
+    document_id: Mapped[int | None] = mapped_column(
+        ForeignKey("documents.id", ondelete="SET NULL"), nullable=True
+    )
+    project_id: Mapped[int] = mapped_column(
+        ForeignKey("projects.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    project: Mapped[Project] = relationship("Project", back_populates="analyses")
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )

backend/models/user.py

@@ -0,0 +1,58 @@
+"""
+GraphoLab Backend — User and Organization ORM models.
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, Enum, ForeignKey, String, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.database import Base
+
+
+class Role(str, enum.Enum):
+    admin = "admin"
+    examiner = "examiner"   # perito — full read/write on own projects
+    viewer = "viewer"       # sola lettura
+
+
+class Organization(Base):
+    __tablename__ = "organizations"
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    name: Mapped[str] = mapped_column(String(128), unique=True, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+
+    users: Mapped[list[User]] = relationship("User", back_populates="organization")
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    email: Mapped[str] = mapped_column(String(256), unique=True, index=True, nullable=False)
+    full_name: Mapped[str] = mapped_column(String(256), nullable=False)
+    hashed_password: Mapped[str] = mapped_column(String(256), nullable=False)
+    role: Mapped[Role] = mapped_column(Enum(Role), default=Role.examiner, nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+
+    organization_id: Mapped[int | None] = mapped_column(
+        ForeignKey("organizations.id", ondelete="SET NULL"), nullable=True
+    )
+    organization: Mapped[Organization | None] = relationship(
+        "Organization", back_populates="users"
+    )
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    projects: Mapped[list] = relationship("Project", back_populates="owner")

backend/routers/analysis.py

@@ -0,0 +1,285 @@
+"""
+GraphoLab Backend — Analysis router.
+
+All heavy AI work is delegated to core/. This router is a thin HTTP layer:
+  1. Download the document image from MinIO
+  2. Call the appropriate core/ function
+  3. Persist the result text in the DB
+  4. Return the result to the client
+
+Endpoints:
+  POST /analysis/htr                      → HTR transcription
+  POST /analysis/signature-detection      → YOLO signature detection
+  POST /analysis/signature-verification   → SigNet verification
+  POST /analysis/ner                      → Named Entity Recognition
+  POST /analysis/writer                   → Writer identification
+  POST /analysis/graphology               → Graphological analysis
+  POST /analysis/pipeline                 → Full 7-step forensic pipeline
+  POST /analysis/dating                   → Document dating
+  GET  /analysis/project/{project_id}     → List analyses for a project
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+import numpy as np
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.responses import StreamingResponse
+from PIL import Image
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.auth.dependencies import get_current_user
+from backend.config import settings
+from backend.database import get_db
+from backend.models.project import Analysis, AnalysisType, Document, Project
+from backend.models.user import Role, User
+from backend.storage.minio_client import download_object
+
+router = APIRouter(prefix="/analysis", tags=["analysis"])
+
+
+# ── Schemas ───────────────────────────────────────────────────────────────────
+
+class AnalysisRequest(BaseModel):
+    project_id: int
+    document_id: int
+
+
+class SignatureVerifyRequest(BaseModel):
+    project_id: int
+    document_id: int           # document under examination
+    reference_document_id: int  # known genuine signature document
+
+
+class AnalysisOut(BaseModel):
+    id: int
+    analysis_type: AnalysisType
+    result_text: str | None
+    project_id: int
+    document_id: int | None
+
+    model_config = {"from_attributes": True}
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+async def _load_image(doc: Document) -> np.ndarray:
+    """Download a document from MinIO and return it as an RGB numpy array."""
+    data = await download_object(doc.storage_key)
+    img = Image.open(io.BytesIO(data)).convert("RGB")
+    return np.array(img)
+
+
+async def _get_doc(doc_id: int, project_id: int, db: AsyncSession) -> Document:
+    result = await db.execute(
+        select(Document).where(Document.id == doc_id, Document.project_id == project_id)
+    )
+    doc = result.scalar_one_or_none()
+    if doc is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Documento non trovato.")
+    return doc
+
+
+async def _check_project_access(project_id: int, db: AsyncSession, user: User) -> Project:
+    result = await db.execute(select(Project).where(Project.id == project_id))
+    project = result.scalar_one_or_none()
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Perizia non trovata.")
+    if user.role != Role.admin and project.owner_id != user.id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Accesso negato.")
+    return project
+
+
+async def _save_analysis(
+    db: AsyncSession,
+    project_id: int,
+    doc_id: int | None,
+    analysis_type: AnalysisType,
+    result_text: str,
+) -> Analysis:
+    analysis = Analysis(
+        analysis_type=analysis_type,
+        result_text=result_text,
+        project_id=project_id,
+        document_id=doc_id,
+    )
+    db.add(analysis)
+    await db.flush()
+    return analysis
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.post("/htr", response_model=AnalysisOut, status_code=status.HTTP_201_CREATED)
+async def run_htr(
+    body: AnalysisRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Analysis:
+    await _check_project_access(body.project_id, db, current_user)
+    doc = await _get_doc(body.document_id, body.project_id, db)
+    image = await _load_image(doc)
+
+    from core.ocr import htr_transcribe
+    text = htr_transcribe(image)
+
+    return await _save_analysis(db, body.project_id, doc.id, AnalysisType.htr, text)
+
+
+@router.post("/signature-detection", response_model=AnalysisOut, status_code=status.HTTP_201_CREATED)
+async def run_signature_detection(
+    body: AnalysisRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Analysis:
+    await _check_project_access(body.project_id, db, current_user)
+    doc = await _get_doc(body.document_id, body.project_id, db)
+    image = await _load_image(doc)
+
+    from core.signature import detect_and_crop
+    _, _, summary = detect_and_crop(image)
+
+    return await _save_analysis(
+        db, body.project_id, doc.id, AnalysisType.signature_detection, summary
+    )
+
+
+@router.post("/signature-verification", response_model=AnalysisOut, status_code=status.HTTP_201_CREATED)
+async def run_signature_verification(
+    body: SignatureVerifyRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Analysis:
+    await _check_project_access(body.project_id, db, current_user)
+    doc = await _get_doc(body.document_id, body.project_id, db)
+    ref_doc = await _get_doc(body.reference_document_id, body.project_id, db)
+
+    image = await _load_image(doc)
+    ref_image = await _load_image(ref_doc)
+
+    from core.signature import detect_and_crop, sig_verify
+    _, query_crop, _ = detect_and_crop(image)
+    query = query_crop if query_crop is not None else image
+
+    report, _ = sig_verify(ref_image, None, query, settings.signet_weights)
+
+    return await _save_analysis(
+        db, body.project_id, doc.id, AnalysisType.signature_verification, report
+    )
+
+
+@router.post("/ner", response_model=AnalysisOut, status_code=status.HTTP_201_CREATED)
+async def run_ner(
+    body: AnalysisRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Analysis:
+    await _check_project_access(body.project_id, db, current_user)
+    doc = await _get_doc(body.document_id, body.project_id, db)
+    image = await _load_image(doc)
+
+    from core.ocr import htr_transcribe
+    from core.ner import ner_extract
+    text = htr_transcribe(image)
+    _, ner_summary = ner_extract(text)
+
+    return await _save_analysis(db, body.project_id, doc.id, AnalysisType.ner, ner_summary)
+
+
+@router.post("/writer", response_model=AnalysisOut, status_code=status.HTTP_201_CREATED)
+async def run_writer_identification(
+    body: AnalysisRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Analysis:
+    await _check_project_access(body.project_id, db, current_user)
+    doc = await _get_doc(body.document_id, body.project_id, db)
+    image = await _load_image(doc)
+
+    from core.writer import writer_identify
+    report, _ = writer_identify(image, settings.writer_samples_dir)
+
+    return await _save_analysis(
+        db, body.project_id, doc.id, AnalysisType.writer_identification, report
+    )
+
+
+@router.post("/graphology", response_model=AnalysisOut, status_code=status.HTTP_201_CREATED)
+async def run_graphology(
+    body: AnalysisRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Analysis:
+    await _check_project_access(body.project_id, db, current_user)
+    doc = await _get_doc(body.document_id, body.project_id, db)
+    image = await _load_image(doc)
+
+    from core.graphology import grapho_analyse
+    report, _ = grapho_analyse(image)
+
+    return await _save_analysis(
+        db, body.project_id, doc.id, AnalysisType.graphology, report
+    )
+
+
+@router.post("/dating", response_model=AnalysisOut, status_code=status.HTTP_201_CREATED)
+async def run_dating(
+    body: AnalysisRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Analysis:
+    await _check_project_access(body.project_id, db, current_user)
+    doc = await _get_doc(body.document_id, body.project_id, db)
+    image = await _load_image(doc)
+
+    from core.ocr import htr_transcribe
+    from core.dating import extract_dates
+    text = htr_transcribe(image)
+    dates = extract_dates(text)
+    if dates:
+        result = "\n".join(f"- {raw} → {dt.strftime('%Y-%m-%d')}" for raw, dt in dates)
+    else:
+        result = "Nessuna data rilevata nel documento."
+
+    return await _save_analysis(db, body.project_id, doc.id, AnalysisType.dating, result)
+
+
+@router.post("/pipeline", response_model=AnalysisOut, status_code=status.HTTP_201_CREATED)
+async def run_pipeline(
+    body: AnalysisRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Analysis:
+    """Run the full 7-step forensic pipeline (blocking — may take 30–120 s)."""
+    await _check_project_access(body.project_id, db, current_user)
+    doc = await _get_doc(body.document_id, body.project_id, db)
+    image = await _load_image(doc)
+
+    from core.pipeline import run_pipeline_steps
+    results = None
+    for results in run_pipeline_steps(
+        image, None, settings.signet_weights, settings.writer_samples_dir
+    ):
+        pass  # consume generator to completion
+
+    report = results.final_report if results else "Pipeline non completata."
+    return await _save_analysis(db, body.project_id, doc.id, AnalysisType.pipeline, report)
+
+
+@router.get("/project/{project_id}", response_model=list[AnalysisOut])
+async def list_analyses(
+    project_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> list[Analysis]:
+    await _check_project_access(project_id, db, current_user)
+    result = await db.execute(
+        select(Analysis)
+        .where(Analysis.project_id == project_id)
+        .order_by(Analysis.created_at.desc())
+    )
+    return result.scalars().all()

backend/routers/auth.py

@@ -0,0 +1,94 @@
+"""
+GraphoLab Backend — Authentication router.
+
+Endpoints:
+  POST /auth/login     → access + refresh tokens (OAuth2 password flow)
+  POST /auth/refresh   → new access token from refresh token
+  POST /auth/logout    → client-side only (stateless JWT)
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from jose import JWTError
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.auth.jwt import TokenType, create_access_token, create_refresh_token, decode_token
+from backend.auth.password import verify_password
+from backend.database import get_db
+from backend.models.user import User
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(
+    form: OAuth2PasswordRequestForm = Depends(),
+    db: AsyncSession = Depends(get_db),
+) -> TokenResponse:
+    result = await db.execute(select(User).where(User.email == form.username))
+    user = result.scalar_one_or_none()
+
+    if user is None or not verify_password(form.password, user.hashed_password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Email o password non corretti.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Account disabilitato. Contatta l'amministratore.",
+        )
+
+    return TokenResponse(
+        access_token=create_access_token(user.id, user.role),
+        refresh_token=create_refresh_token(user.id),
+    )
+
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh(
+    body: RefreshRequest,
+    db: AsyncSession = Depends(get_db),
+) -> TokenResponse:
+    credentials_exc = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Refresh token non valido o scaduto.",
+    )
+    try:
+        payload = decode_token(body.refresh_token)
+        if payload.get("type") != TokenType.refresh:
+            raise credentials_exc
+        user_id = int(payload["sub"])
+    except (JWTError, KeyError, ValueError):
+        raise credentials_exc
+
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if user is None or not user.is_active:
+        raise credentials_exc
+
+    return TokenResponse(
+        access_token=create_access_token(user.id, user.role),
+        refresh_token=create_refresh_token(user.id),
+    )
+
+
+@router.post("/logout", status_code=status.HTTP_204_NO_CONTENT)
+async def logout() -> None:
+    """JWT is stateless — logout is handled client-side by discarding the token."""
+    pass

backend/routers/projects.py

@@ -0,0 +1,226 @@
+"""
+GraphoLab Backend — Projects router.
+
+A project (= "Perizia") groups documents and analyses for one case.
+
+Endpoints:
+  GET    /projects/              → list own projects
+  POST   /projects/              → create project
+  GET    /projects/{id}          → get project detail
+  PUT    /projects/{id}          → update project
+  DELETE /projects/{id}          → delete project
+  POST   /projects/{id}/documents → upload document to project
+  GET    /projects/{id}/documents → list project documents
+  DELETE /projects/{id}/documents/{doc_id} → remove document
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile, status
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from backend.auth.dependencies import get_current_user
+from backend.database import get_db
+from backend.models.project import Document, Project, ProjectStatus
+from backend.models.user import Role, User
+from backend.storage.minio_client import delete_object, upload_fileobj
+
+router = APIRouter(prefix="/projects", tags=["projects"])
+
+
+# ── Schemas ───────────────────────────────────────────────────────────────────
+
+class ProjectOut(BaseModel):
+    id: int
+    title: str
+    description: str | None
+    status: ProjectStatus
+    owner_id: int
+    document_count: int = 0
+
+    model_config = {"from_attributes": True}
+
+
+class ProjectCreate(BaseModel):
+    title: str
+    description: str | None = None
+
+
+class ProjectUpdate(BaseModel):
+    title: str | None = None
+    description: str | None = None
+    status: ProjectStatus | None = None
+
+
+class DocumentOut(BaseModel):
+    id: int
+    filename: str
+    content_type: str
+    size_bytes: int
+    storage_key: str
+
+    model_config = {"from_attributes": True}
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+async def _get_project_or_404(
+    project_id: int,
+    db: AsyncSession,
+    current_user: User,
+) -> Project:
+    result = await db.execute(
+        select(Project)
+        .options(selectinload(Project.documents))
+        .where(Project.id == project_id)
+    )
+    project = result.scalar_one_or_none()
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Perizia non trovata.")
+    # Admins can access all projects; examiners/viewers only their own
+    if current_user.role != Role.admin and project.owner_id != current_user.id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Accesso negato.")
+    return project
+
+
+# ── Project CRUD ──────────────────────────────────────────────────────────────
+
+@router.get("/", response_model=list[ProjectOut])
+async def list_projects(
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> list[Project]:
+    if current_user.role == Role.admin:
+        q = select(Project).options(selectinload(Project.documents)).order_by(Project.id.desc())
+    else:
+        q = (
+            select(Project)
+            .options(selectinload(Project.documents))
+            .where(Project.owner_id == current_user.id)
+            .order_by(Project.id.desc())
+        )
+    result = await db.execute(q)
+    projects = result.scalars().all()
+    for p in projects:
+        p.document_count = len(p.documents)
+    return projects
+
+
+@router.post("/", response_model=ProjectOut, status_code=status.HTTP_201_CREATED)
+async def create_project(
+    body: ProjectCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Project:
+    project = Project(
+        title=body.title,
+        description=body.description,
+        owner_id=current_user.id,
+    )
+    db.add(project)
+    await db.flush()
+    project.document_count = 0
+    return project
+
+
+@router.get("/{project_id}", response_model=ProjectOut)
+async def get_project(
+    project_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Project:
+    project = await _get_project_or_404(project_id, db, current_user)
+    project.document_count = len(project.documents)
+    return project
+
+
+@router.put("/{project_id}", response_model=ProjectOut)
+async def update_project(
+    project_id: int,
+    body: ProjectUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Project:
+    project = await _get_project_or_404(project_id, db, current_user)
+    if body.title is not None:
+        project.title = body.title
+    if body.description is not None:
+        project.description = body.description
+    if body.status is not None:
+        project.status = body.status
+    db.add(project)
+    project.document_count = len(project.documents)
+    return project
+
+
+@router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_project(
+    project_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> None:
+    project = await _get_project_or_404(project_id, db, current_user)
+    # Remove files from MinIO
+    for doc in project.documents:
+        await delete_object(doc.storage_key)
+    await db.delete(project)
+
+
+# ── Document upload / list / delete ───────────────────────────────────────────
+
+@router.post("/{project_id}/documents", response_model=DocumentOut,
+             status_code=status.HTTP_201_CREATED)
+async def upload_document(
+    project_id: int,
+    file: UploadFile = File(...),
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> Document:
+    project = await _get_project_or_404(project_id, db, current_user)
+
+    storage_key = f"projects/{project.id}/{file.filename}"
+    content = await file.read()
+    size = len(content)
+    await upload_fileobj(storage_key, content, file.content_type or "application/octet-stream")
+
+    doc = Document(
+        filename=file.filename,
+        content_type=file.content_type or "application/octet-stream",
+        storage_key=storage_key,
+        size_bytes=size,
+        project_id=project.id,
+    )
+    db.add(doc)
+    await db.flush()
+    return doc
+
+
+@router.get("/{project_id}/documents", response_model=list[DocumentOut])
+async def list_documents(
+    project_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> list[Document]:
+    project = await _get_project_or_404(project_id, db, current_user)
+    return project.documents
+
+
+@router.delete("/{project_id}/documents/{doc_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_document(
+    project_id: int,
+    doc_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> None:
+    await _get_project_or_404(project_id, db, current_user)
+    result = await db.execute(
+        select(Document).where(Document.id == doc_id, Document.project_id == project_id)
+    )
+    doc = result.scalar_one_or_none()
+    if doc is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Documento non trovato.")
+    await delete_object(doc.storage_key)
+    await db.delete(doc)

backend/routers/rag.py

@@ -0,0 +1,100 @@
+"""
+GraphoLab Backend — RAG / Consulente Forense IA router.
+
+Endpoints:
+  POST /rag/chat           → streaming chat (SSE)
+  GET  /rag/docs           → list loaded documents
+  POST /rag/docs           → upload and index a new document
+  DELETE /rag/docs/{name}  → remove a document from the index
+  GET  /rag/status         → Ollama reachability check
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile, status
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+from backend.auth.dependencies import get_current_user
+from backend.config import settings
+from backend.models.user import User
+
+router = APIRouter(prefix="/rag", tags=["rag"])
+
+
+# ── Schemas ───────────────────────────────────────────────────────────────────
+
+class ChatRequest(BaseModel):
+    message: str
+    history: list[list[str]] = []
+
+
+class DocInfo(BaseModel):
+    filename: str
+    chunks: int
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.get("/status")
+async def rag_status(_: User = Depends(get_current_user)) -> dict:
+    from core.rag import check_ollama, ollama_list_models
+    reachable = check_ollama()
+    models = ollama_list_models() if reachable else []
+    return {"ollama_reachable": reachable, "models": models}
+
+
+@router.get("/docs", response_model=list[DocInfo])
+async def list_docs(_: User = Depends(get_current_user)) -> list[DocInfo]:
+    from core.rag import rag_doc_list
+    docs = rag_doc_list(settings.rag_cache_dir)
+    return [DocInfo(filename=d["filename"], chunks=d["chunks"]) for d in docs]
+
+
+@router.post("/docs", status_code=status.HTTP_201_CREATED)
+async def add_doc(
+    file: UploadFile = File(...),
+    _: User = Depends(get_current_user),
+) -> dict:
+    import tempfile
+    from pathlib import Path
+    from core.rag import rag_add_docs
+
+    suffix = Path(file.filename).suffix
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+        tmp.write(await file.read())
+        tmp_path = tmp.name
+
+    # rag_add_docs expects a list of file-like objects with a .name attribute
+    class _FileLike:
+        name = tmp_path
+
+    result = rag_add_docs([_FileLike()], settings.rag_cache_dir)
+    return {"detail": result}
+
+
+@router.delete("/docs/{filename}", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_doc(
+    filename: str,
+    _: User = Depends(get_current_user),
+) -> None:
+    from core.rag import rag_remove_doc
+    rag_remove_doc(filename, settings.rag_cache_dir)
+
+
+@router.post("/chat")
+async def chat(
+    body: ChatRequest,
+    _: User = Depends(get_current_user),
+) -> StreamingResponse:
+    """Server-Sent Events stream of the RAG response."""
+    from core.rag import rag_chat_stream
+
+    async def _generate():
+        for partial_text, sources in rag_chat_stream(body.message, body.history):
+            # SSE format: "data: <payload>\n\n"
+            yield f"data: {partial_text}\n\n"
+            if sources:
+                yield f"data: {sources}\n\n"
+
+    return StreamingResponse(_generate(), media_type="text/event-stream")

backend/routers/users.py

@@ -0,0 +1,134 @@
+"""
+GraphoLab Backend — Users router.
+
+Endpoints:
+  GET  /users/me          → current user profile
+  PUT  /users/me          → update own profile / password
+  GET  /users/            → list all users (admin only)
+  POST /users/            → create a new user (admin only)
+  DELETE /users/{id}      → deactivate a user (admin only)
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, EmailStr
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.auth.dependencies import get_current_user, require_role
+from backend.auth.password import hash_password, verify_password
+from backend.database import get_db
+from backend.models.user import Role, User
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+
+# ── Schemas ───────────────────────────────────────────────────────────────────
+
+class UserOut(BaseModel):
+    id: int
+    email: str
+    full_name: str
+    role: Role
+    is_active: bool
+    organization_id: int | None
+
+    model_config = {"from_attributes": True}
+
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    full_name: str
+    password: str
+    role: Role = Role.examiner
+    organization_id: int | None = None
+
+
+class UserUpdate(BaseModel):
+    full_name: str | None = None
+    current_password: str | None = None
+    new_password: str | None = None
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.get("/me", response_model=UserOut)
+async def get_me(current_user: User = Depends(get_current_user)) -> User:
+    return current_user
+
+
+@router.put("/me", response_model=UserOut)
+async def update_me(
+    body: UserUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> User:
+    if body.full_name:
+        current_user.full_name = body.full_name
+
+    if body.new_password:
+        if not body.current_password:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="Fornisci la password attuale per cambiarla.",
+            )
+        if not verify_password(body.current_password, current_user.hashed_password):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Password attuale non corretta.",
+            )
+        current_user.hashed_password = hash_password(body.new_password)
+
+    db.add(current_user)
+    return current_user
+
+
+@router.get("/", response_model=list[UserOut], dependencies=[Depends(require_role(Role.admin))])
+async def list_users(db: AsyncSession = Depends(get_db)) -> list[User]:
+    result = await db.execute(select(User).order_by(User.id))
+    return result.scalars().all()
+
+
+@router.post("/", response_model=UserOut, status_code=status.HTTP_201_CREATED,
+             dependencies=[Depends(require_role(Role.admin))])
+async def create_user(
+    body: UserCreate,
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    existing = await db.execute(select(User).where(User.email == body.email))
+    if existing.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Email '{body.email}' già registrata.",
+        )
+    user = User(
+        email=body.email,
+        full_name=body.full_name,
+        hashed_password=hash_password(body.password),
+        role=body.role,
+        organization_id=body.organization_id,
+    )
+    db.add(user)
+    await db.flush()
+    return user
+
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT,
+               dependencies=[Depends(require_role(Role.admin))])
+async def deactivate_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+) -> None:
+    if user_id == current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Non puoi disattivare il tuo stesso account.",
+        )
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Utente non trovato.")
+    user.is_active = False
+    db.add(user)

backend/storage/minio_client.py

@@ -0,0 +1,100 @@
+"""
+GraphoLab Backend — MinIO async storage client.
+
+Wraps the synchronous `minio` SDK in asyncio-friendly helpers using
+`anyio.to_thread.run_sync` to avoid blocking the event loop.
+
+Public API:
+  upload_fileobj(key, data, content_type)  → None
+  download_object(key)                     → bytes
+  delete_object(key)                       → None
+  get_presigned_url(key, expires_seconds)  → str
+"""
+
+from __future__ import annotations
+
+import io
+from datetime import timedelta
+
+import anyio
+from minio import Minio
+from minio.error import S3Error
+
+from backend.config import settings
+
+# ── Singleton client ──────────────────────────────────────────────────────────
+
+_client: Minio | None = None
+
+
+def _get_client() -> Minio:
+    global _client
+    if _client is None:
+        _client = Minio(
+            settings.minio_endpoint,
+            access_key=settings.minio_access_key,
+            secret_key=settings.minio_secret_key,
+            secure=settings.minio_secure,
+        )
+        # Ensure the bucket exists
+        if not _client.bucket_exists(settings.minio_bucket):
+            _client.make_bucket(settings.minio_bucket)
+    return _client
+
+
+# ── Sync helpers (run in thread pool) ────────────────────────────────────────
+
+def _upload_sync(key: str, data: bytes, content_type: str) -> None:
+    client = _get_client()
+    client.put_object(
+        settings.minio_bucket,
+        key,
+        io.BytesIO(data),
+        length=len(data),
+        content_type=content_type,
+    )
+
+
+def _download_sync(key: str) -> bytes:
+    client = _get_client()
+    response = client.get_object(settings.minio_bucket, key)
+    try:
+        return response.read()
+    finally:
+        response.close()
+        response.release_conn()
+
+
+def _delete_sync(key: str) -> None:
+    client = _get_client()
+    try:
+        client.remove_object(settings.minio_bucket, key)
+    except S3Error:
+        pass  # already deleted or never existed — no-op
+
+
+def _presigned_sync(key: str, expires_seconds: int) -> str:
+    client = _get_client()
+    return client.presigned_get_object(
+        settings.minio_bucket,
+        key,
+        expires=timedelta(seconds=expires_seconds),
+    )
+
+
+# ── Async public API ──────────────────────────────────────────────────────────
+
+async def upload_fileobj(key: str, data: bytes, content_type: str) -> None:
+    await anyio.to_thread.run_sync(lambda: _upload_sync(key, data, content_type))
+
+
+async def download_object(key: str) -> bytes:
+    return await anyio.to_thread.run_sync(lambda: _download_sync(key))
+
+
+async def delete_object(key: str) -> None:
+    await anyio.to_thread.run_sync(lambda: _delete_sync(key))
+
+
+async def get_presigned_url(key: str, expires_seconds: int = 3600) -> str:
+    return await anyio.to_thread.run_sync(lambda: _presigned_sync(key, expires_seconds))

docker-compose.yml

@@ -1,4 +1,7 @@
 services:
+
+  # ── Existing services ────────────────────────────────────────────────────────
+
   jupyter:
     build: .
     container_name: grapholab-jupyter
@@ -41,6 +44,93 @@ services:
               capabilities: [gpu]
     restart: unless-stopped
 
+  # ── New services (Phase 1 — professional backend) ────────────────────────────
+
+  postgres:
+    image: postgres:16-alpine
+    container_name: grapholab-postgres
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: grapholab
+      POSTGRES_PASSWORD: grapholab
+      POSTGRES_DB: grapholab
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U grapholab"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  minio:
+    image: minio/minio:latest
+    container_name: grapholab-minio
+    command: server /data --console-address ":9001"
+    ports:
+      - "9000:9000"   # S3 API
+      - "9001:9001"   # Web console → http://localhost:9001
+    environment:
+      MINIO_ROOT_USER: grapholab
+      MINIO_ROOT_PASSWORD: grapholab123
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  backend:
+    build:
+      context: .
+      dockerfile: backend/Dockerfile
+    container_name: grapholab-backend
+    ports:
+      - "8000:8000"   # FastAPI → http://localhost:8000/docs
+    environment:
+      - DATABASE_URL=postgresql+asyncpg://grapholab:grapholab@postgres:5432/grapholab
+      - MINIO_ENDPOINT=minio:9000
+      - MINIO_ACCESS_KEY=grapholab
+      - MINIO_SECRET_KEY=grapholab123
+      - MINIO_SECURE=false
+      - OLLAMA_HOST=http://ollama:11434
+      - SECRET_KEY=${SECRET_KEY:-change_me_in_production}
+      - HF_HOME=/app/cache
+    volumes:
+      - ./data:/app/data
+      - hf_cache:/app/cache
+    depends_on:
+      postgres:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities: [gpu]
+    restart: unless-stopped
+
+  ollama:
+    image: ollama/ollama:latest
+    container_name: grapholab-ollama
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    restart: unless-stopped
+
 volumes:
   hf_cache:
     name: grapholab-hf-cache
+  postgres_data:
+    name: grapholab-postgres-data
+  minio_data:
+    name: grapholab-minio-data
+  ollama_data:
+    name: grapholab-ollama-data

requirements-backend.txt

@@ -0,0 +1,22 @@
+# GraphoLab Backend — additional dependencies (on top of requirements.txt)
+
+# Web framework
+fastapi>=0.111.0
+uvicorn[standard]>=0.29.0
+
+# Async PostgreSQL
+sqlalchemy[asyncio]>=2.0.0
+asyncpg>=0.29.0
+
+# Settings management
+pydantic-settings>=2.0.0
+
+# Auth
+python-jose[cryptography]>=3.3.0
+passlib[bcrypt]>=1.7.4
+python-multipart>=0.0.9   # required by FastAPI for form/file uploads
+email-validator>=2.1.0    # required by pydantic EmailStr
+
+# MinIO S3-compatible storage
+minio>=7.2.0
+anyio>=4.0.0              # async thread offload for sync MinIO SDK