S3 Storage Structure

CertiLock images are stored in an AWS S3 bucket configured via Laravel's filesystems.php. This page describes the bucket layout, naming conventions, and how the middleware accesses files.

Bucket Configuration

Setting	Value
Bucket name	`certilock-storage` (set via `AWS_BUCKET`)
Region	`us-east-1` (set via `AWS_DEFAULT_REGION`)
Access control	Private — no public read
Laravel disk	`s3`

File Naming Convention

CertiLock-Files/{SERIAL_NUMBER}_SS.JPG

CertiLock-Files/ — root prefix for all sealing images
{SERIAL_NUMBER} — exact serial number as stored in the serial_numbers database table
_SS — suffix indicating a sealed-state photograph
.JPG — always uppercase extension

Example

CertiLock-Files/SM-2024-001234_SS.JPG

Database Table: `serial_numbers`

Column	Type	Description
`id`	`bigint`	Auto-increment primary key
`serial_number`	`varchar`	The unique CertiLock serial number
`created_at`	`timestamp`	Date and time of sealing
`updated_at`	`timestamp`	Last update timestamp

The created_at value is returned as date_of_sealing in the Image API response.

How the Controller Accesses Files

// Check file existence
Storage::disk('s3')->exists('CertiLock-Files/' . $serial_number . '_SS.JPG');

// Fetch file content
$fileContent = Storage::disk('s3')->get('CertiLock-Files/' . $serial_number . '_SS.JPG');

The content is then base64-encoded and returned in the JSON response (for GET /api/image) or returned as a raw binary response (for GET /api/image-random).

Uploading New Images

Images are uploaded externally (typically by the sealing workstation software) directly to S3 using the same naming convention. The middleware is read-only with respect to S3; it does not handle uploads.

Bucket Configuration​

File Naming Convention​

Example​

Database Table: serial_numbers​

How the Controller Accesses Files​

Uploading New Images​