FiloraFS-Pro architecture

Request flow

Bearer JWT request
  → Spring Security validates signature, issuer, audience, time, user, and session
  → Controller resolves authenticated username and ROLE_ADMIN
  → FileAccessService enforces owner/admin access
  → DelegatingFileService selects the file's persisted provider
  → LOCAL filesystem or S3-compatible object
  ↔ Flyway-managed H2/MySQL metadata

Project structure

com.filorafs/
├── config/       security, CORS, files, S3, async, workbench
├── controller/   auth, users, files, storage administration
├── dto/          request and safe response contracts
├── entity/       users, roles, sessions, files, storage config/audit
├── exception/    sanitized centralized errors
├── repository/   JPA persistence
├── security/     password/JWT/refresh-session flows
├── service/      access, files, providers, credentials, thumbnails
└── util/         upload validation

Minimal identity layer

Password login creates a server-tracked AuthSession, a short-lived HS256 JWT, and an opaque refresh credential stored only as a SHA-256 digest. Refresh rotates the credential under locking; replay revokes that family. Logout requires a JWT and revokes the owned session.

Ownership and authorization

The uploader's User entity is attached before physical storage and owner_id is non-null. FileAccessService filters normal-user lists and checks owner identity for metadata, stream, download, delete, temporary access, and thumbnail operations. ROLE_ADMIN bypasses the owner match for file administration.

Storage abstraction

The active provider is consulted only for new uploads. DelegatingFileService reads each stored file's provider metadata for later operations, preserving mixed LOCAL/S3 collections across provider switches.

Storage configuration and encryption

• A singleton database row stores active provider, LOCAL path, S3 endpoint, bucket, region, encrypted credentials, timestamps, and updater.
• AES-256-GCM encrypts access and secret keys with a runtime-only Base64 32-byte master key.
• Safe API responses expose credential-presence flags rather than decrypted values.
• Configuration, testing, and switching are separate ROLE_ADMIN operations.
• A storage audit table records configuration updates and provider switches.

Metadata and persistence

• Flyway creates users, roles, sessions, refresh credentials, file metadata, temporary links, storage configuration, and storage audit tables.
• H2 in MySQL compatibility mode provides the dependency-free path; DB_URL, DB_USERNAME, and DB_PASSWORD select MySQL.
• Hibernate validates the Flyway schema instead of creating it.
• File metadata and provider objects must be backed up and restored together.

Testing and operations

• Automated tests cover registration, password login, JWT validation, refresh rotation/replay, logout, roles, owner isolation, validation, LOCAL storage, provider selection, no fallback, encryption/masking, temporary expiry, and thumbnails.
• Fresh migration, H2 defaults, production defaults, workbench availability, and Actuator endpoints have dedicated checks.
• The Postman collection and /api-test workbench exercise the same public, user, administrator, file, and storage workflows.
• Public operational access is limited to Actuator discovery, health, and info; unmatched routes are denied.