Andrew Martinez

Image Models

Overview

This module defines the entity image storage and processing layer used across ICAO aircraft types and aircraft registration entities. The models manage ingestion (upload or remote fetch), S3 object projection into multiple image sizes, DynamoDB persistence of metadata, default-image state management, moderation workflows, and search indexing projections.

The image pipeline operates as follows: an image is uploaded or imported to a raw S3 bucket, processing workers generate resized derivatives into the processed bucket, the metadata record is stored in DynamoDB using a multi-entity key structure, and optional moderation or default-image projections are applied. Repository-style Objects managers provide query, mutation, upload, deletion, and moderation orchestration utilities.

WikimediaMetadataModel

Purpose

Stores normalized source attribution and licensing metadata for externally sourced images.

Fields
  • Source identification: source, source_id, source_url, url
  • Attribution: license, license_url, attribution, author
  • Image attributes: mime, width, height, aspect_ratio, orientation
  • Context: categories, captured_at, assessments
Validation
  • Unicode normalization removes non-ASCII characters for consistent indexing.

DefaultEntityImage

Purpose

Stores the authoritative default image assignment for an entity. S3 DEFAULT/ projections are derived from this DynamoDB record.

Fields
  • entity_type (EntityTypeEnum)
  • org_id (str)
  • entity_id (str)
  • image_id (str)
Primary keys
  • PK: IMAGES#ORG#{org_id}#ENTITY#{entity_type}#ID#{entity_id}
  • SK: DEFAULT

ImageModel

Purpose

Base entity image record containing upload metadata, attribution information, EXIF metadata, and entity association. Supports generation of presigned URLs for size-specific assets.

Fields
  • id (ULID)
  • org_id, entity_id, entity_type
  • image_hash (Optional[str])
  • wikimedia (Optional[WikimediaMetadataModel])
  • exif_tags (Optional[EXIFMetadata])
  • user_id (Optional[str])
Primary keys
  • PK: IMAGES#ORG#{org_id}#ENTITY#{entity_type}#ID#{entity_id}
  • SK: IMG#{id}
Indexes
  • GSI1: IMAGEHASH#ORG#{org_id}#HASH#{image_hash} → deduplication lock lookup

ICAOImageModel

Purpose

ICAO aircraft type–scoped image record using the base ImageModel schema.

RegistrationImageModel

Purpose

Registration-specific image record supporting moderation workflows, user attribution, and search indexing for approved aircraft registration photos.

Additional fields
  • icao, serial, make, model, year
  • approval_status (PENDING | APPROVED | REJECTED)
  • approval_note, reviewed_by, reviewed_at
  • uploaded_at
Primary keys
  • PK: IMAGES#ORG#{org_id}#ENTITY#REGISTRATION#ID#{entity_id}
  • SK: IMG#{approval_status}#{created_at}#{id}
Indexes
  • GSI2: USER#{user_id}#IMAGES → images uploaded by user
  • GSI3: IMAGES#ORG#{org_id}#ENTITY#{entity_type} → pending moderation queue
  • GSI1: image hash deduplication lock
Query strategy
  • Status-prefixed SK enables efficient queries for APPROVED/PENDING/REJECTED subsets.
  • User-based browsing via GSI2.
  • Moderation queue scanning via GSI3.

Repository / Objects Manager

Core capabilities
  • Presigned upload generation and remote URL ingestion
  • DynamoDB persistence and pagination queries
  • S3 projection repair for default images
  • Moderation state transitions (Put + Delete relocation)
  • Atomic deduplication lock checks via hash GSI
Worker / job orchestration integration
  • Upload workers generate resized image derivatives into processed buckets.
  • Moderation jobs update approval status and relocate records.
  • Repair jobs rebuild default-image S3 projections from DynamoDB truth.
Operational Flow
  1. Client uploads image using presigned POST or remote fetch.
  2. Worker processes raw image and writes processed size variants.
  3. DynamoDB metadata record is written.
  4. Moderation workflow optionally updates approval state.
  5. Search index ingestion reads approved image records for indexing.
← ICAO Models Normalized Registration Models →