feat: add project management system with PostgreSQL backend

Full-stack project management for BIM validation projects:
- Backend: async SQLAlchemy 2.0 + PostgreSQL (SQLite fallback for dev)
- REST API: /api/v2/projects CRUD + file upload/download/delete
- Frontend: ProjectStorage abstraction (server + local via File System Access API)
- UI: ProjectList component in Backstage with create/open/delete
- Docker: PostgreSQL service, persistent project file storage volume
- i18n: NL + EN translations for project panel
- .bvp format: local project file format for offline use

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jochem25

Dockerfile

@@ -46,8 +46,8 @@ COPY ids-bestanden/ ./ids-bestanden/
 # Copy built frontend from stage 1
 COPY --from=frontend-build /app/viewer/dist ./viewer/dist
 
-# Create temp directories
-RUN mkdir -p /tmp/ifc_uploads /tmp/ifc_processed /tmp/ids_validation_jobs
+# Create temp directories and persistent project storage
+RUN mkdir -p /tmp/ifc_uploads /tmp/ifc_processed /tmp/ids_validation_jobs /data/projects
 
 EXPOSE 8000
 

docker-compose.yml

@@ -1,12 +1,29 @@
 services:
+  db:
+    image: postgres:16-alpine
+    container_name: bim-validator-db
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: bimvalidator
+      POSTGRES_USER: bimvalidator
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    networks:
+      - default
+
   app:
     build: .
     container_name: bim-validator
     restart: unless-stopped
+    depends_on:
+      - db
     ports:
       - "127.0.0.1:8000:8000"
     environment:
       - CORS_ORIGINS=*
+      - DATABASE_URL=postgresql+asyncpg://bimvalidator:${POSTGRES_PASSWORD:-changeme}@db:5432/bimvalidator
+      - PROJECT_FILES_DIR=/data/projects
       # Nextcloud cloud storage (opt-in — leave empty to disable)
       - NEXTCLOUD_URL=
       - NEXTCLOUD_SERVICE_USER=
@@ -16,6 +33,8 @@ services:
       - bim-uploads:/tmp/ifc_uploads
       - bim-processed:/tmp/ifc_processed
       - bim-jobs:/tmp/ids_validation_jobs
+      # Persistent project file storage
+      - bim-projects:/data/projects
     networks:
       - default
       - openaec_platform
@@ -25,9 +44,11 @@ services:
           memory: 4G
 
 volumes:
+  pgdata:
   bim-uploads:
   bim-processed:
   bim-jobs:
+  bim-projects:
 
 networks:
   openaec_platform:

server/database.py

@@ -0,0 +1,65 @@
+"""
+Database setup — async SQLAlchemy 2.0 with PostgreSQL.
+
+Provides the engine, session factory, and Base for ORM models.
+Falls back to SQLite for local development when DATABASE_URL is not set.
+"""
+
+import os
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+# Default to SQLite for local dev, PostgreSQL in production
+DATABASE_URL = os.environ.get(
+    "DATABASE_URL",
+    "sqlite+aiosqlite:///./bimvalidator.db",
+)
+
+# SQLAlchemy async engine
+engine = create_async_engine(
+    DATABASE_URL,
+    echo=False,
+    pool_pre_ping=True,
+)
+
+# Session factory
+async_session = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+class Base(DeclarativeBase):
+    """Base class for all ORM models."""
+    pass
+
+
+async def init_db() -> None:
+    """Create all tables. Called on app startup."""
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+async def close_db() -> None:
+    """Dispose engine. Called on app shutdown."""
+    await engine.dispose()
+
+
+@asynccontextmanager
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    """Yield an async database session."""
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise

server/main.py

@@ -27,6 +27,7 @@
 from fastapi.staticfiles import StaticFiles
 
 from server.bcf_export import generate_bcf_zip
+from server.database import close_db, init_db
 from server.ids_validator import IDSValidator, ValidationReport, report_to_dict
 from server.ifc_processor import GLTF_AVAILABLE, IFCProcessor
 from server.job_manager import JobManager, JobStatusResponse
@@ -39,6 +40,7 @@
     ValidationStatus,
 )
 from server.project_manager import ProjectManager
+from server.routers.projects import router as projects_router
 from ifc_validator.standards.resolver import get_bundled_ids
 
 
@@ -75,6 +77,22 @@ def format(self, record: logging.LogRecord) -> str:
     redoc_url="/redoc",
 )
 
+# Include persistent project router (PostgreSQL-backed)
+app.include_router(projects_router)
+
+
+@app.on_event("startup")
+async def startup():
+    """Initialize database tables on startup."""
+    await init_db()
+
+
+@app.on_event("shutdown")
+async def shutdown():
+    """Clean up database connections on shutdown."""
+    await close_db()
+
+
 # Configure CORS for browser access
 # In production, set CORS_ORIGINS env var (comma-separated)
 _default_origins = [

server/models/db_models.py

@@ -0,0 +1,101 @@
+"""
+SQLAlchemy ORM models for projects and project files.
+"""
+
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import JSON, BigInteger, DateTime, ForeignKey, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from server.database import Base
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _new_uuid() -> str:
+    return str(uuid.uuid4())
+
+
+class Project(Base):
+    """A BIM validation project containing IFC/BCF/IDS files."""
+
+    __tablename__ = "projects"
+
+    id: Mapped[str] = mapped_column(
+        String(36), primary_key=True, default=_new_uuid
+    )
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=_utcnow
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=_utcnow, onupdate=_utcnow
+    )
+
+    files: Mapped[list["ProjectFile"]] = relationship(
+        back_populates="project",
+        cascade="all, delete-orphan",
+        lazy="selectin",
+    )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "createdAt": self.created_at.isoformat(),
+            "updatedAt": self.updated_at.isoformat(),
+            "files": [f.to_dict() for f in self.files],
+        }
+
+    def to_summary(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "createdAt": self.created_at.isoformat(),
+            "updatedAt": self.updated_at.isoformat(),
+            "fileCount": len(self.files),
+        }
+
+
+class ProjectFile(Base):
+    """A file (IFC, BCF, or IDS) belonging to a project."""
+
+    __tablename__ = "project_files"
+
+    id: Mapped[str] = mapped_column(
+        String(36), primary_key=True, default=_new_uuid
+    )
+    project_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("projects.id", ondelete="CASCADE"), nullable=False
+    )
+    file_type: Mapped[str] = mapped_column(
+        String(10), nullable=False
+    )  # 'ifc', 'bcf', 'ids'
+    file_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    file_size: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    disk_path: Mapped[str] = mapped_column(String(512), nullable=False)
+    uploaded_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=_utcnow
+    )
+    metadata_json: Mapped[dict | None] = mapped_column(
+        "metadata", JSON, nullable=True
+    )
+
+    project: Mapped["Project"] = relationship(back_populates="files")
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "projectId": self.project_id,
+            "fileType": self.file_type,
+            "fileName": self.file_name,
+            "fileSize": self.file_size,
+            "uploadedAt": self.uploaded_at.isoformat(),
+            "metadata": self.metadata_json,
+        }

server/requirements.txt

@@ -21,3 +21,8 @@ aiofiles>=24.0.0
 
 # Async HTTP client (Nextcloud WebDAV integration)
 httpx>=0.27.0
+
+# Database (PostgreSQL + async SQLAlchemy)
+sqlalchemy[asyncio]>=2.0.0
+asyncpg>=0.30.0
+aiosqlite>=0.20.0  # SQLite fallback for local dev