# Copyright (C) 2026 Mattia Zatelli # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU Affero General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Affero General Public License for more details. # # You should have received a copy of the GNU Affero General Public License # along with this program. If not, see . """ Project model for storing IFC project information This model represents the core of the BIM system, containing: - Project and IFC file metadata - Processing state and progress tracking - Element and geometry statistics - Tiered storage configuration - Multi-tenant isolation - Complete audit trail Each project goes through well-defined states from upload to ready, with robust error handling and automatic recovery. """ import enum from datetime import datetime from typing import Optional, Dict, Any, List from sqlalchemy import Column, Integer, String, DateTime, Text, JSON, Float, Boolean, Enum as SQLEnum, ForeignKey from sqlalchemy.orm import relationship from sqlalchemy.sql import func from app.core.database import Base class ProjectStatus(str, enum.Enum): """IFC project processing states Defines the state machine for project processing: - QUEUED: Upload completed, waiting for processing - PROCESSING: IFC processing in progress (parsing, geometries, indexes) - READY: Processing completed, ready for queries - FAILED: Processing failed (corrupted file, timeout, etc.) - ARCHIVED: Project archived but recoverable Transitions are monitored and logged for debugging. """ QUEUED = "queued" PROCESSING = "processing" READY = "ready" FAILED = "failed" ARCHIVED = "archived" class StorageTier(str, enum.Enum): """Storage tiers for the tiered storage system Automatically manages data lifecycle based on access patterns: - HOT: Frequent access, fast storage (SSD), no compression - WARM: Medium access, standard storage, lz4 compression - COLD: Rare access, economical storage, gzip compression - FROZEN: Archive, glacier storage, maximum compression Transitions are automatic based on last_accessed_at with pinning support for critical projects. """ HOT = "hot" WARM = "warm" COLD = "cold" FROZEN = "frozen" class Project(Base): """ IFC project model Stores complete information about uploaded BIM projects: **Identification and Security:** - Internal numeric ID + external format "prj_123" - tenant_id for MANDATORY multi-tenant isolation - api_key_hash for usage tracking **File Metadata:** - Name, description, original filename - SHA256 hash for deduplication and integrity - Size and S3 storage locations **Processing State:** - Status with validated state machine - Progress 0-100% with descriptive stage - Error handling with structured details **Processed IFC Data:** - IFC schema, version, project_info - Element statistics by type - Geometries: bounding_box, area, height - Boolean flags for capabilities **Tiered Storage:** - Automatic tier based on access - Versioning for rollback - Compression paths for optimization - Pinning for critical projects **Relationships:** - elements: Extracted BIM elements - queries: Queries executed on the project - usage_events: Usage events - artifacts_manifest: Artifacts management """ __tablename__ = "projects" # === PRIMARY IDENTIFICATION === id = Column(Integer, primary_key=True, index=True) # === MULTI-TENANT ISOLATION (CRITICAL FOR SECURITY) === tenant_id = Column(String(50), nullable=False, index=True) # ALWAYS verify in queries api_key_hash = Column(String(100), nullable=True, index=True) # For usage tracking # === PROJECT METADATA === name = Column(String(255), nullable=False) # Project name (user-friendly) description = Column(Text, nullable=True) # Optional description original_filename = Column(String(255), nullable=False) # Original IFC filename file_size = Column(Integer, nullable=False) # Size in bytes file_hash = Column(String(64), nullable=False, unique=True) # SHA256 for deduplication # === S3 STORAGE INFORMATION === s3_bucket = Column(String(100), nullable=False) # S3 bucket name s3_key = Column(String(500), nullable=False) # S3 object key s3_region = Column(String(50), nullable=False) # AWS region # === PROCESSING STATE === status = Column(SQLEnum(ProjectStatus), nullable=False, default=ProjectStatus.QUEUED) processing_progress = Column(Integer, default=0) # Progress 0-100% processing_stage = Column(String(50), nullable=True) # Current stage (parsing, geometry, etc.) error_message = Column(Text, nullable=True) # Human-readable error message error_details = Column(JSON, nullable=True) # Structured error details # IFC metadata (populated after processing) ifc_schema = Column(String(20), nullable=True) # IFC2X3, IFC4, etc. ifc_version = Column(String(50), nullable=True) project_info = Column(JSON, nullable=True) # IFC project information site_info = Column(JSON, nullable=True) # Site/building information # Statistics (populated after processing) element_count = Column(Integer, default=0) element_types = Column(JSON, nullable=True) # {type: count} gross_floor_area = Column(Float, nullable=True) building_height = Column(Float, nullable=True) bounding_box = Column(JSON, nullable=True) # {min: [x,y,z], max: [x,y,z]} # Flags has_geometry = Column(Boolean, default=False) has_properties = Column(Boolean, default=False) has_materials = Column(Boolean, default=False) has_spaces = Column(Boolean, default=False) # Tiered Storage last_accessed_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now()) tier = Column(SQLEnum(StorageTier), nullable=False, default=StorageTier.HOT) version = Column(Integer, nullable=False, default=1) pinned = Column(Boolean, nullable=False, default=False) compressed_s3_key = Column(String(500), nullable=True) manifest_s3_key = Column(String(500), nullable=True) # Timestamps created_at = Column(DateTime(timezone=True), server_default=func.now()) updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now()) processed_at = Column(DateTime(timezone=True), nullable=True) last_queried_at = Column(DateTime(timezone=True), nullable=True) # Relationships elements = relationship("Element", back_populates="project", cascade="all, delete-orphan") queries = relationship("Query", back_populates="project", cascade="all, delete-orphan") usage_events = relationship("UsageEvent", back_populates="project") artifacts_manifest = relationship("ProjectArtifactsManifest", back_populates="project", cascade="all, delete-orphan") tiering_operations = relationship("TieringOperation", back_populates="project", cascade="all, delete-orphan") def __repr__(self): return f"" def to_dict(self) -> Dict[str, Any]: """Convert to dictionary for API responses""" return { "id": f"prj_{self.id}", "name": self.name, "description": self.description, "status": self.status.value, "processing_progress": self.processing_progress, "processing_stage": self.processing_stage, "original_filename": self.original_filename, "file_size": self.file_size, "ifc_schema": self.ifc_schema, "ifc_version": self.ifc_version, "element_count": self.element_count, "element_types": self.element_types or {}, "gross_floor_area": self.gross_floor_area, "building_height": self.building_height, "bounding_box": self.bounding_box, "has_geometry": self.has_geometry, "has_properties": self.has_properties, "has_materials": self.has_materials, "has_spaces": self.has_spaces, "tier": self.tier.value, "pinned": self.pinned, "version": self.version, "days_since_last_access": self.days_since_last_access(), "created_at": self.created_at.isoformat() if self.created_at else None, "processed_at": self.processed_at.isoformat() if self.processed_at else None, "last_queried_at": self.last_queried_at.isoformat() if self.last_queried_at else None, "last_accessed_at": self.last_accessed_at.isoformat() if self.last_accessed_at else None, } def get_progress_info(self) -> Dict[str, Any]: """Get detailed progress information""" return { "project_id": f"prj_{self.id}", "status": self.status.value, "progress": { "percent": self.processing_progress, "stage": self.processing_stage or "queued" }, "error": { "message": self.error_message, "details": self.error_details } if self.error_message else None } def is_ready(self) -> bool: """Check if project is ready for queries""" return self.status == ProjectStatus.READY def is_processing(self) -> bool: """Check if project is currently processing""" return self.status == ProjectStatus.PROCESSING def is_failed(self) -> bool: """Check if project processing failed""" return self.status == ProjectStatus.FAILED def mark_processing(self, stage: str = "parsing"): """Mark project as processing with stage""" self.status = ProjectStatus.PROCESSING self.processing_stage = stage self.processing_progress = 0 self.error_message = None self.error_details = None def update_progress(self, progress: int, stage: str = None): """Update processing progress""" self.processing_progress = min(100, max(0, progress)) if stage: self.processing_stage = stage def mark_ready(self): """Mark project as ready""" self.status = ProjectStatus.READY self.processing_progress = 100 self.processing_stage = "ready" self.processed_at = func.now() self.error_message = None self.error_details = None def mark_failed(self, error_message: str, error_details: Dict = None): """Mark project as failed""" self.status = ProjectStatus.FAILED self.error_message = error_message self.error_details = error_details or {} self.processing_stage = "failed" def update_query_timestamp(self): """Update last queried timestamp""" self.last_queried_at = func.now() def touch_last_access(self): """Update last accessed timestamp (for tiered storage)""" self.last_accessed_at = func.now() def is_hot(self) -> bool: """Check if project is in HOT tier""" return self.tier == StorageTier.HOT def is_warm(self) -> bool: """Check if project is in WARM tier""" return self.tier == StorageTier.WARM def is_cold(self) -> bool: """Check if project is in COLD tier""" return self.tier == StorageTier.COLD def is_frozen(self) -> bool: """Check if project is in FROZEN tier""" return self.tier == StorageTier.FROZEN def can_demote(self) -> bool: """Check if project can be demoted (not pinned and ready)""" return not self.pinned and self.is_ready() def pin(self): """Pin project to prevent demotion""" self.pinned = True def unpin(self): """Unpin project to allow demotion""" self.pinned = False def set_tier(self, tier: StorageTier): """Set storage tier""" self.tier = tier self.version += 1 def days_since_last_access(self) -> int: """Get days since last access""" from datetime import datetime, timezone if not self.last_accessed_at: return 0 now = datetime.now(timezone.utc) if self.last_accessed_at.tzinfo is None: # Handle timezone-naive datetime self.last_accessed_at = self.last_accessed_at.replace(tzinfo=timezone.utc) delta = now - self.last_accessed_at return delta.days @classmethod def get_public_id(cls, internal_id: int) -> str: """Convert internal ID to public format""" return f"prj_{internal_id}" @classmethod def parse_public_id(cls, public_id: str) -> Optional[int]: """Parse public ID to internal ID""" if not public_id.startswith("prj_"): return None try: return int(public_id[4:]) except ValueError: return None def get_summary_stats(self) -> Dict[str, Any]: """Get project summary statistics""" return { "counts_by_type": self.element_types or {}, "gross_floor_area_sqm": self.gross_floor_area, "building_height_m": self.building_height, "element_count": self.element_count, "has_geometry": self.has_geometry, "has_properties": self.has_properties, "has_materials": self.has_materials, "has_spaces": self.has_spaces, "ifc_schema": self.ifc_schema, "bounding_box": self.bounding_box } class ProjectArtifactsManifest(Base): """ Manifest for project artifacts stored in S3 Used for tracking compressed and archived project data """ __tablename__ = "project_artifacts_manifest" # Primary key id = Column(Integer, primary_key=True, index=True) # Foreign key to project project_id = Column(Integer, ForeignKey('projects.id'), nullable=False, index=True) # Storage info s3_uri = Column(String(500), nullable=False, index=True) bytes_stored = Column(Integer, nullable=False) # Compressed size sha256_hash = Column(String(64), nullable=False) # Content flags has_embeddings = Column(Boolean, nullable=False, default=False) has_aggregates = Column(Boolean, nullable=False, default=False) has_extended_props = Column(Boolean, nullable=False, default=False) # Compression info compression_type = Column(String(20), nullable=True) # gzip, zstd, etc. original_size = Column(Integer, nullable=True) # Uncompressed size # Timestamps created_at = Column(DateTime(timezone=True), server_default=func.now()) updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now()) # Relationship project = relationship("Project", back_populates="artifacts_manifest") def __repr__(self): return f"" def to_dict(self) -> Dict[str, Any]: """Convert to dictionary""" return { "id": self.id, "project_id": self.project_id, "s3_uri": self.s3_uri, "bytes_stored": self.bytes_stored, "sha256_hash": self.sha256_hash, "has_embeddings": self.has_embeddings, "has_aggregates": self.has_aggregates, "has_extended_props": self.has_extended_props, "compression_type": self.compression_type, "original_size": self.original_size, "compression_ratio": self.get_compression_ratio(), "created_at": self.created_at.isoformat() if self.created_at else None, "updated_at": self.updated_at.isoformat() if self.updated_at else None, } def get_compression_ratio(self) -> Optional[float]: """Calculate compression ratio if both sizes are available""" if self.original_size and self.bytes_stored and self.original_size > 0: return round(self.bytes_stored / self.original_size, 3) return None class TieringOperationStatus(str, enum.Enum): """Status of tiering operations""" PENDING = "pending" RUNNING = "running" COMPLETED = "completed" FAILED = "failed" class TieringOperationType(str, enum.Enum): """Types of tiering operations""" DEMOTE = "demote" REHYDRATE = "rehydrate" COMPRESS = "compress" ARCHIVE = "archive" class TieringOperation(Base): """ Records of tiering operations for auditing and monitoring """ __tablename__ = "tiering_operations" # Primary key id = Column(Integer, primary_key=True, index=True) # Foreign key to project project_id = Column(Integer, ForeignKey('projects.id'), nullable=False, index=True) # Operation info operation_type = Column(SQLEnum(TieringOperationType), nullable=False) from_tier = Column(SQLEnum(StorageTier), nullable=True) to_tier = Column(SQLEnum(StorageTier), nullable=True) status = Column(SQLEnum(TieringOperationStatus), nullable=False, default=TieringOperationStatus.PENDING, index=True) # Metrics bytes_moved = Column(Integer, nullable=True) processing_time_ms = Column(Integer, nullable=True) # Error handling error_message = Column(Text, nullable=True) # Timestamps started_at = Column(DateTime(timezone=True), nullable=True) completed_at = Column(DateTime(timezone=True), nullable=True) created_at = Column(DateTime(timezone=True), server_default=func.now(), index=True) # Relationship project = relationship("Project", back_populates="tiering_operations") def __repr__(self): return f"" def to_dict(self) -> Dict[str, Any]: """Convert to dictionary""" return { "id": self.id, "project_id": self.project_id, "operation_type": self.operation_type.value, "from_tier": self.from_tier.value if self.from_tier else None, "to_tier": self.to_tier.value if self.to_tier else None, "status": self.status.value, "bytes_moved": self.bytes_moved, "processing_time_ms": self.processing_time_ms, "error_message": self.error_message, "started_at": self.started_at.isoformat() if self.started_at else None, "completed_at": self.completed_at.isoformat() if self.completed_at else None, "created_at": self.created_at.isoformat() if self.created_at else None, } def mark_started(self): """Mark operation as started""" self.status = TieringOperationStatus.RUNNING self.started_at = func.now() def mark_completed(self, bytes_moved: int = None, processing_time_ms: int = None): """Mark operation as completed""" self.status = TieringOperationStatus.COMPLETED self.completed_at = func.now() if bytes_moved is not None: self.bytes_moved = bytes_moved if processing_time_ms is not None: self.processing_time_ms = processing_time_ms def mark_failed(self, error_message: str): """Mark operation as failed""" self.status = TieringOperationStatus.FAILED self.completed_at = func.now() self.error_message = error_message