FiloraFS architecture

Lite architecture

Lite intentionally avoids a database and persistence framework. The service validates the reported content type, creates a UUID stored filename, and reads or writes the configured filesystem directory.

HTTP request + X-API-KEY
  → ApiKeyFilter
  → FileController
  → FileService
  → upload.path

com.file/
├── controller/FileController
├── dtos/FileStream
├── filter/ApiKeyFilter
└── services/FileService

Pro architecture

HTTP request
  → Spring Security / JWT filter
  → Controller
  → Service
  → Repository + storage provider
  → MySQL + local filesystem or S3

com.filorafs/
├── config/       security, storage, S3, async
├── controller/   auth, files, users
├── dto/          API contracts
├── entity/       users, tokens, files
├── exception/    centralized errors
├── repository/   JPA persistence
├── security/     JWT and refresh tokens
├── service/      files, providers, thumbnails, users
└── util/         upload validation

Storage abstraction (Pro)

FileService defines upload, read, list, metadata, delete, temporary access, and thumbnail operations. DelegatingFileService is primary and dispatches reads and deletes from persisted storageType. Upload attempts S3 when available and otherwise uses LocalFileService.

Metadata and persistence (Pro)

• FileMetadata records identity, content, size, provider, uploader, and time.
• PreSignedFile stores local temporary-access tokens and expiry.
• User, Role, and RefreshToken support authentication and RBAC.
• Repositories use Spring Data JPA with MySQL.

Security (Pro)

JwtAuthenticationFilter authenticates Bearer tokens in a stateless filter chain. /api/auth/** and /file/presigned/** are public; other routes require authentication. Method rules restrict selected user endpoints.

Tests and extension points

The projects include Spring Boot test dependencies and product-specific test guidance. Keep controller paths stable, add temporary-directory tests for local storage, mock provider failure intentionally, and test authentication and file-ownership rules when extending Pro.