# 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