Storix / Documentation
Laravel storage infrastructure DOCS / V1.1

One API.
Every Storage.

A unified, driver-based storage and transfer layer for Laravel. Move files across providers with one consistent interface—without coupling your application to a single backend.

PHP 8.5+ Laravel 13 Driver-first architecture
SSTORIXUNIFIED STORAGE API
⌘Your appLaravel
▤LocalFilesystem
☁CloudProviders
↗TelegramOptional driver
ONE CONTRACT · MULTIPLE DRIVERS
Project status: engineering specification. This portal describes planned architecture and capabilities. It does not imply every feature is implemented or production-ready. Check code, tests, and release notes for verified status.
PHP 8.5+Target runtime
Laravel 13Target framework
14 EpicsImplementation roadmap
Driver-basedStorage architecture
01

Quick start

Start with the product model, understand the driver boundary, then follow the implementation roadmap. Storix is a backend-only Composer package; it does not ship a dashboard or frontend.

1
Understand the product

Read the Product Requirements Document for goals, scope, user journeys, and acceptance criteria.

2
Review the architecture

Study System Architecture and Storage Drivers before changing boundaries.

3
Implement in roadmap order

Begin with E01 Foundation: Composer metadata, service provider, configuration, CI, and conventions.

4
Prove behavior with tests

Use the Testing Strategy and Acceptance Checklist. Documentation alone is not implementation evidence.

02

Why Storix?

Storage providers expose different APIs and capabilities. Large transfers introduce interruptions, duplicate requests, rate limits, partial writes, and uncertainty about data integrity. Storix centralizes those concerns behind a consistent Laravel API.

One stable API

Keep application business logic independent from provider-specific SDKs and response objects.

Resilient transfers

Persist sessions and chunk state so eligible transfers can recover after interruptions.

Integrity first

Verify chunks and final content with SHA-256 where bytes are available. Never infer success from metadata alone.

Laravel native

Integrate with the service container, queues, events, migrations, scheduler, cache, and filesystem.

03

Core concepts

Storage driver

A provider adapter implementing a provider-neutral contract. Each driver declares its capabilities and operational limits.

File metadata

Application-facing metadata and opaque identifiers. Physical provider keys stay private to infrastructure.

Transfer session

A durable workflow tracking intent, state, retries, ownership, and completion evidence.

Chunk

A bounded part of a transfer with an offset, expected size, state, checksum, and provider reference.

Capability model

Describes whether a driver supports streaming, range reads, multipart writes, atomic finalize, or pause/resume.

Idempotency

Allows safe request replay and duplicate detection without crossing tenant or owner boundaries.

04

Feature overview

The following are planned capabilities defined by the current engineering specification.

File & directory management

Put, stream, inspect, list, rename, and delete files/directories through a unified API, subject to driver capabilities.

StorageMetadata

Chunked transfers

Configurable chunk planning, bounded parallelism, chunk checksums, and durable transfer state.

UploadDownload

Resume & recovery

Reconcile persisted state, reuse verified chunks within the same security scope, and retry transient failures.

IdempotencyBackoff

Progress & events

Bytes, percentage, speed, ETA when measurable, chunk counts, lifecycle events, and structured diagnostics.

ObservabilityEvents

Security & tenancy

Owner/tenant scopes, policy hooks, path safety, quotas, secret redaction, and integrity checks.

AuthorizationIsolation

Laravel integrations

Service provider, config, migrations, facade, queues, scheduler, optional Redis optimizations, and optional REST adapter.

LaravelAPI
05

Architecture

Storix uses a modular, domain-oriented core. Application services depend on contracts; infrastructure adapters integrate provider SDKs and Laravel facilities.

Laravel Application / CLI / Optional REST
                  |
           Storix PHP API
                  |
       Application Services + Domain
          +-------+--------+
     Authorization  Metadata DB  Transfer Orchestrator
                                  |
                            Laravel Queue
                                  |
                       Chunk + Integrity Engine
                                  |
                            Driver Manager
                       +----------+----------+
                      Local   Telegram   Future Drivers

For detailed sequences and consistency rules, read System Architecture and Database Design.

06

Storage drivers

DriverPurposeScope
LocalBaseline filesystem-backed storagePlanned first usable driver
TelegramOptional remote provider adapterRequires current official API/policy validation
S3-compatible / R2Object storage backendsFuture extensions
CustomApplication/vendor-specific backendVia driver contract
Scope boundary: Telegram Serverless is explicitly excluded. Storix must not assume Telegram-specific identifiers or behavior in its core domain.
07

Transfer lifecycle

Expected high-level lifecycle:

pending → preparing → transferring → verifying → completed
                     |               |
                     +--- retry_wait-+

Terminal states: failed · cancelled · expired
Optional state: paused (only where safely supported)
  • Validate authorization, limits, source metadata, and available temporary storage.
  • Create or reuse an eligible idempotent session.
  • Transfer chunks with bounded concurrency and persist verified progress.
  • Reconcile provider state after interruptions and retry only eligible failures.
  • Finalize through the driver and verify final integrity before marking complete.

See Transfer Engine for protocol and failure handling.

08

Security model

Authorization by scope

Every read, write, list, resume, share, and delete operation must enforce owner and tenant access.

Safe object keys

Generate opaque keys independently of user filenames; normalize paths and reject traversal.

Secrets stay private

Never expose provider tokens, signed URLs, private storage references, or raw exception traces.

Resource controls

Bound file size, chunk size, concurrency, queue attempts, quotas, and temporary disk usage.

Read the complete Security Design before implementing access or sharing features.

18

Basic upload · E05

E05 implements a stream-first, single-object upload workflow on the existing Local driver and persistence layer and is merged into main.

Bounded input

Readable PHP streams, 64 MiB configured default (also capped by driver limits), 8 MiB memory spool threshold, and validation while bytes are read.

Durable metadata

Scoped file and transfer records, a validated state lifecycle, tenant/owner-aware directory lookup, and private-only visibility.

Integrity before availability

Compare staged bytes, driver write metadata, stat size, and an independent streamed SHA-256 read-back.

Safe replay

Scoped idempotency returns an existing completed upload only for the same request fingerprint; conflicts never overwrite an object.

Scope: E05 provides the single-object streaming path; E06 adds verified sequential multipart chunk writes; E07 adds idempotent resume and provider-part reconciliation; E08 adds stale-transfer recovery and bounded retry scheduling. Queued parallel workers, download chunking, REST endpoints, and Telegram storage remain later milestones.

Implementation specifications: E05 Basic Upload and E06 Chunk Engine.

09

Installation

Expected Composer installation after a compatible package release is published:

composer require shamimstack/storix
This is the intended distribution command. Until a tagged release is published, do not assume Packagist installation is available. Use the repository's development setup instructions for active implementation.
10

PHP API direction

The intended primary interface is PHP services/facade. Exact signatures and DTOs are subject to implementation and API review.

use ShamimStack\\Storix\\Facades\\Storix;

$file = Storix::files()->put(
    source: $uploadedFile,
    directory: 'invoices/2026',
    options: ['visibility' => 'private'],
);

$stream = Storix::files()->readStream($file->id);

$transfer = Storix::uploads()->start($source, [
    'directory' => 'backups',
    'idempotency_key' => $requestId,
]);

$status = Storix::transfers()->status($transfer->id);

See Core PHP API and REST API for suggested routes, response envelopes, and error conventions.

11

Configuration

Configuration is expected to cover default driver, driver credentials/settings, chunk policy, concurrency, retry policy, session retention, progress persistence, quotas, and optional REST adapter settings.

return [
    'default_driver' => env('STORIX_DRIVER', 'local'),
    'transfers' => [
        'chunk_size' => 8 * 1024 * 1024,
        'max_concurrency' => 3,
        'max_attempts' => 5,
    ],
    'api' => [
        'enabled' => false,
        'prefix' => 'api/v1/storix',
    ],
];

Values are illustrative only. See Configuration & Operations for the complete example and operational guidance.

12

Queues & operations

  • Use Laravel queues for long-running transfers.
  • Separate transfer and cleanup workloads when needed.
  • Use idempotent jobs, bounded attempts, locks, and worker timeouts aligned with queue retry settings.
  • Schedule stale-session recovery and temporary-resource cleanup.
  • Log sanitized structured fields such as transfer ID, driver, state, attempt, duration, and error code.

Redis may improve queue/progress workloads but should not replace durable relational metadata.

13

Testing strategy

Unit tests

State machine, chunk planner, fingerprinting, retry policy, DTO validation, and progress math.

Driver contract tests

Common behavior for stream read/write, stat, delete, capability declarations, and error mapping.

Integration tests

Laravel container, migrations, queues, events, filesystem, and end-to-end local transfers.

Security & performance

IDOR, tenant isolation, path traversal, secret redaction, memory bounds, concurrency, and realistic benchmarks.

14

Implementation roadmap

EpicScope
E01Foundation — Composer, provider, config, CI
E02Contracts & PHP API
E03Persistence & state machine
E04Local storage driver
E05Basic upload
E06Chunk engine
E07Resume & idempotency
E08Recovery & retry
E09Download engine
E10Progress & events
E11Performance & benchmarks
E12Optional Telegram driver after validation
E13Optional REST adapter & security hardening
E14Release & operations

Implement sequentially. Do not begin provider-specific work before core contracts and transfer state are stable. See the full roadmap.

15

Documentation library

Each document is the detailed source of truth for its subject.

16

Frequently asked questions

Does Storix include a frontend or dashboard?

No. It is a backend-only package. Applications can build their own UI using the PHP API, events, or optional REST adapter.

Is Telegram required?

No. Telegram is an optional driver. The core architecture is provider-neutral, and Telegram Serverless is excluded.

Does every driver support pause, resume, and range downloads?

No. These behaviors depend on driver capabilities and execution mode. Storix must expose support explicitly instead of promising identical behavior for every provider.

Are all features implemented now?

No. This documentation describes the intended design and roadmap. Consult repository code, tests, and release notes for verified implementation status.

When is a transfer considered successful?

Only after the driver finalizes the object and the required integrity verification succeeds.