FiloraFS-Lite architecture

Request flow

HTTP request + X-API-KEY
  → ApiKeyFilter
  → FileController
  → FileService
  → local filesystem

Project structure

FiloraFSProperties binds the storage path and shared key. FileController maps HTTP requests and delegates file behavior to FileService. FileMetadata is a response record derived from the filesystem. There is no metadata database, persistence framework, or storage-provider abstraction.

com.file/
├── FileUploadApiApplication
├── config/FiloraFSProperties
├── controller/
│   ├── FileController
│   └── ApiTestController
├── dtos/FileMetadata
├── filter/ApiKeyFilter
└── services/FileService

File handling

• Uploads check extension, declared media type, and a short content signature before generating a UUID filename. The destination is reserved without overwriting an existing file; failed transfers attempt to remove partial output.
• FileService normalizes the configured root, creates it at startup, and restricts operations to flat filenames within it. Reads and listing exclude symbolic links and non-regular files; deletion rejects them.
• Downloads return ResponseEntity<Resource> with attachment headers; Spring MVC streams the resource. Listing is sorted, and metadata contains no absolute paths.

Framework and tooling

ApiKeyFilter checks /file requests using Spring-normalized paths and constant-time key comparison. ApiTestController redirects /api-test and /api-test/ to the public static/api-test/index.html client; file calls still require the key.

Spring Boot owns configuration loading, multipart limits, error handling, Actuator health, and graceful shutdown. Existing tests cover startup, configuration binding, HTTP access, and storage with isolated temporary directories.

Extension points

• Replace shared API-key access with application-specific authentication when required.
• Add deeper content inspection, quotas, retention, and ownership rules when required.
• Keep local file tests isolated in temporary directories.
• Preserve controller paths when extending the implementation.