backend-module-structure

Backend Module Structure Skill

Trigger

Use this skill when:

• Adding or modifying Java backend code
• Creating new services, controllers, repositories, or entities
• Refactoring backend code across files
• Reviewing backend code placement

Rules

Dependency Direction

The design-doc dependency direction:

app → domain, auth, search, storage, infra, notification
infra → domain          # implements domain repository interfaces
auth → domain
search → domain
notification → domain
storage → (independent) # pure SPI

Design intent: skillhub-domain should be the innermost layer, defining entities,

repository interfaces, and domain services without depending on infra, auth, search, or storage.

Code reality: skillhub-domain declares a Maven dependency on skillhub-storage (via

pom.xml), and several domain services (SkillHardDeleteService, SkillDownloadService,

SkillPublishService, SkillGovernanceService, SkillQueryService,

SkillStorageDeletionCompensationService) import com.iflytek.skillhub.storage.ObjectStorageService.

This is an existing deviation from the ideal clean architecture. New code should avoid adding

further cross-module dependencies from domain.

Where to Place Code

| Code Type | Module | Java Package |

|-----------|--------|-------------|

| Entity / Value Object | skillhub-domain | com.iflytek.skillhub.domain.{submodule}/ |

| Repository Interface | skillhub-domain | com.iflytek.skillhub.domain.{submodule}/ |

| Domain Service | skillhub-domain | com.iflytek.skillhub.domain.{submodule}/service/ |

| Domain Event | skillhub-domain | com.iflytek.skillhub.domain/event/ |

| Domain Exception | skillhub-domain | com.iflytek.skillhub.domain/shared/exception/ |

| JPA Repository Impl | skillhub-infra | com.iflytek.skillhub.infra.repository/ |

| Controller | skillhub-app | com.iflytek.skillhub.controller/ |

| App Service | skillhub-app | com.iflytek.skillhub.service/ |

| Query Repository | skillhub-app | com.iflytek.skillhub.repository/ |

| DTO / Response | skillhub-app | com.iflytek.skillhub.dto/ |

| OAuth2 / Auth Config | skillhub-auth | com.iflytek.skillhub.auth/ |

| Search SPI / Impl | skillhub-search | com.iflytek.skillhub.search/ |

| Storage SPI / Impl | skillhub-storage | com.iflytek.skillhub.storage/ |

| Notification Service | skillhub-notification | com.iflytek.skillhub.notification/ |

Maven Modules

The parent POM (server/pom.xml) defines 7 modules with spring-boot-starter-parent:3.2.3:

skillhub-app | skillhub-domain | skillhub-auth | skillhub-search
skillhub-storage | skillhub-infra | skillhub-notification

Repository vs Query Repository

• Domain Repository (skillhub-domain): Aggregate reads, state transitions, rule evaluation.

Returns domain objects. Defined as interfaces, implemented in skillhub-infra via Spring Data JPA.

• Query Repository (com.iflytek.skillhub.repository): Read-model assembly, joins multiple

sources, presentation projection. Returns DTOs. Implemented directly in skillhub-app.

Current query repositories:

• GovernanceQueryRepository / JpaGovernanceQueryRepository
• MySkillQueryRepository / JpaMySkillQueryRepository
• ProfileReviewQueryRepository / JpaProfileReviewQueryRepository
• AdminSkillReportQueryRepository / JpaAdminSkillReportQueryRepository

When a new read use case arrives:

1. If it's for state transition or domain rule → domain repository port
2. If it's for page/list/detail response assembly with joins → app query repository
3. If it's a thin single-aggregate read → direct domain repository call from app service
4. If direct SQL/EntityManager is needed → add class-level comment explaining why

Building Backend Tests

Never run ./mvnw -pl skillhub-app clean test directly under server/. Use:

make test-backend-app   # skillhub-app + dependencies (includes -am)
make test-backend       # all backend modules

Running clean test on skillhub-app alone can fall back to stale artifacts from the local Maven

repository, surfacing misleading cannot find symbol and signature-mismatch errors.

User Identity Type

User identity is always String throughout the codebase. This covers:

• Authentication, API params, permissions, audit
• Resource owner, creator, reviewer, actor, submittedBy
• All user-associated fields

The UserAccount entity uses @Column(length = 128) for its ID. The platform needs to support

external SSO/OIDC/SCIM identity sources whose UIDs are typically stable strings.