OpenParable
Skip to content
← Back to skills

Backend Module Structure

Development
backend-module-structure

Backend Module Structure is an Agent Skill for development published in the iflytek/skillhub repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Rules for the SkillHub backend Maven multi-module clean architecture. Ensures agents place new code in the correct module and respect dependency direction.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/iflytek/skillhub/blob/HEAD/.agents/skills/backend-module-structure/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/backend-module-structure, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 TypeModuleJava Package
Entity / Value Objectskillhub-domaincom.iflytek.skillhub.domain.{submodule}/
Repository Interfaceskillhub-domaincom.iflytek.skillhub.domain.{submodule}/
Domain Serviceskillhub-domaincom.iflytek.skillhub.domain.{submodule}/service/
Domain Eventskillhub-domaincom.iflytek.skillhub.domain/event/
Domain Exceptionskillhub-domaincom.iflytek.skillhub.domain/shared/exception/
JPA Repository Implskillhub-infracom.iflytek.skillhub.infra.repository/
Controllerskillhub-appcom.iflytek.skillhub.controller/
App Serviceskillhub-appcom.iflytek.skillhub.service/
Query Repositoryskillhub-appcom.iflytek.skillhub.repository/
DTO / Responseskillhub-appcom.iflytek.skillhub.dto/
OAuth2 / Auth Configskillhub-authcom.iflytek.skillhub.auth/
Search SPI / Implskillhub-searchcom.iflytek.skillhub.search/
Storage SPI / Implskillhub-storagecom.iflytek.skillhub.storage/
Notification Serviceskillhub-notificationcom.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.