FiloraFS-Pro architecture

Request flow

HTTP request
  → Spring Security / JWT
  → Controller
  → Service
  → Repository + storage provider
  → H2 + local storage (default)
  → external database + local/S3 (.env)

Project structure

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

The file service defines upload, read, list, metadata, delete, temporary access, and thumbnail operations. Provider selection stays behind the service boundary and persisted storage type resolves later reads and deletes.

Metadata and persistence

• File metadata records identity, content, size, provider, uploader, and time.
• Temporary-access records store local tokens and expiry.
• User, role, and refresh-token records support authentication and authorization.
• H2 supports evaluation; .env selects a persistent external database for development.

Security boundary

Bearer JWTs authenticate protected routes while selected authentication and temporary-access routes remain public.

Testing and extension points

• Keep controller paths stable.
• Use temporary directories for local storage tests.
• Mock provider failures intentionally.
• Test authentication, authorization, and file ownership rules.
• Verify both default and externalized configuration paths.