FileFlexManager Architecture
A domain-driven design (DDD) web file manager for Linux NAS systems with mobile-first UI, multi-user support, and permission control.
Project Overview
FileFlexManager is a web-based file management system built with:
**Backend**: Spring Boot 3 (JDK 21), Gradle multi-module, MyBatis Plus, MapStruct, H2/SQLite**Frontend**: Vue 3, TypeScript, Vant UI (mobile-first)**Architecture**: Domain-Driven Design with strict layer boundaries**Deployment**: Docker containers on LinuxArchitecture Principles
1. DDD Layer Structure
Follow strict layer boundaries with dependencies flowing inward:
**Interfaces** → **Application** → **Domain** ← **Infrastructure****Domain Layer** contains pure business logic with no external dependencies:
`domain/event/` - Domain events`domain/model/` - Core domain models`domain/repository/` - Repository interfaces`domain/service/` - Domain services`domain/utils/` - Domain utilities**Application Layer** orchestrates domain logic:
`application/assembler/` - Application-level data transformations`application/config/` - Application configuration`application/dto/` - Application data transfer objects`application/event/` - Event handlers`application/scheduler/` - Scheduled tasks`application/service/` - Application services**Infrastructure Layer** provides technical implementations:
`infrastructure/persistence/` - Database implementations (converter, entity, mapper, po, repository)`infrastructure/security/` - Security implementations`infrastructure/config/` - Infrastructure configuration`infrastructure/external/` - External service integrations`infrastructure/task/handler/` - Task handlers**Interfaces Layer** handles external communication:
`interfaces/api/controller/` - REST controllers`interfaces/api/assembler/` - Request/Response assemblers`interfaces/api/advice/` - Global exception handlers`interfaces/model/` - DTOs, requests, responses, VOs2. Data Model Separation
Use three distinct model types with MapStruct for type-safe conversions:
**DTO (Data Transfer Object)**: Interfaces layer, external communication**Domain Model**: Pure business entities in domain layer**PO (Persistent Object)**: Infrastructure layer, database mapping**MapStruct mappings:**
Interfaces layer: DTO ↔ Domain ModelInfrastructure layer: Domain Model ↔ PO/EntityAlways generate MapStruct mappers with `@Mapper(componentModel = "spring")` annotation.
3. Backend Standards
**Response Handling:**
All API responses wrapped in `BaseResponse`Success/failure handled consistentlyGlobal exception handler in `interfaces/api/advice/`**Data Access:**
Repository pattern enforcedDomain defines interfacesInfrastructure provides implementationsUse MyBatis Plus for database operations**Domain Events:**
Publish domain events for cross-aggregate communicationEvent handlers in application layerKeep domain layer event definitions pure**Validation:**
Unified validation at interfaces layerUse Jakarta validation annotationsValidate early, fail fast4. Frontend Standards
**Mobile-First Development:**
Use Vant UI components exclusivelyDesign for mobile screens firstResponsive layouts with viewport units**Type Safety:**
TypeScript strict mode enabledDefine interfaces for all API responsesType all props, events, and state**API Integration:**
Centralize API calls in `src/api/`Use composition API (`<script setup>`)Unified request handler in `config.ts`Handle `BaseResponse` format consistently**Import Paths:**
Use path aliases only (configured in tsconfig)No relative imports (../../)Example: `@/components/`, `@/api/`, `@/utils/`**State Management:**
Use Pinia stores in `src/stores/`Composition API styleType all store state and actions5. Testing Requirements
**Unit Tests:**
Location: `src/test/java/{package}/*Test.java`Framework: JUnit 5Naming: `@Test` methods in camelCaseSetup: `@BeforeEach` for test initializationCoverage: Required for core business logicMock external dependenciesTest both success and failure scenarios**Integration Tests:**
Location: `backend/interfaces/src/test/java/*IntegrationTest.java`Use `TestConfig.java` for test configurationTest full request/response cyclesValidate layer interactions6. Module Structure
**Backend Gradle Multi-Module:**
```
backend/
├── domain/ (pure business logic)
├── application/ (use cases, orchestration)
├── infrastructure/ (technical implementations)
└── interfaces/ (API, web controllers)
```
**Frontend Structure:**
```
frontend/
├── src/
│ ├── api/ (API client functions)
│ ├── components/ (reusable Vue components)
│ ├── views/ (page components)
│ ├── stores/ (Pinia state management)
│ ├── router/ (Vue Router configuration)
│ └── utils/ (utility functions)
├── public/ (static assets)
└── config/ (build and environment config)
```
Implementation Guidelines
When Creating Backend Features:
1. **Start with Domain Layer**: Define domain models, repository interfaces, and domain services
2. **Add Application Layer**: Create DTOs and application services that orchestrate domain logic
3. **Implement Infrastructure**: Provide repository implementations, POs, MyBatis mappers
4. **Expose via Interfaces**: Create controllers, request/response models, MapStruct assemblers
5. **Add Global Exception Handling**: Use `@ControllerAdvice` for consistent error responses
6. **Write Tests**: Unit tests for domain/application logic, integration tests for API endpoints
When Creating Frontend Features:
1. **Define API Client**: Add typed API functions in `src/api/`
2. **Create Store (if needed)**: Add Pinia store in `src/stores/`
3. **Build Components**: Use Vant UI components with TypeScript
4. **Handle Responses**: Use unified handler from `config.ts` for `BaseResponse`
5. **Mobile-First Design**: Test on mobile viewport first
6. **Type Everything**: Add interfaces for props, emits, API responses
Docker Deployment:
Use Docker for containerizationTarget OS: LinuxDatabase: H2 or SQLite for lightweight persistenceBuild with Gradle wrapperFrontend builds to `dist/` and serves as static assetsKey Files
**Backend Entry**: `backend/interfaces/src/main/java/com/huanzhen/fileflexmanager/FileFlexManagerApplication.java`**Backend Config**: `backend/interfaces/src/main/resources/application*.yml`**Frontend Entry**: `frontend/src/main.ts`**API Config**: `frontend/src/config.ts`**Test Config**: `backend/interfaces/src/test/java/TestConfig.java`Development Environment
**Docker**: Container runtime**Gradle**: Build automation (use Gradle wrapper)**Git**: Version control**JDK**: Version 21**Node**: For frontend developmentConstraints
Never violate DDD layer boundaries (infrastructure cannot call application, etc.)Always use MapStruct for model conversions (no manual mapping)All API responses must use `BaseResponse` wrapperFrontend must be mobile-first (desktop is enhancement)Database must be H2 or SQLite (lightweight, embedded)All exceptions handled globally (no try-catch in controllers)Use path aliases for imports (no relative paths)