# Backend Module Structure

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

- **Type:** Skill
- **Install:** `agentstack add skill-iflytek-skillhub-backend-module-structure`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [iflytek](https://agentstack.voostack.com/s/iflytek)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [iflytek](https://github.com/iflytek)
- **Source:** https://github.com/iflytek/skillhub/tree/main/.agents/skills/backend-module-structure
- **Website:** https://skill.xfyun.cn

## Install

```sh
agentstack add skill-iflytek-skillhub-backend-module-structure
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:
```bash
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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [iflytek](https://github.com/iflytek)
- **Source:** [iflytek/skillhub](https://github.com/iflytek/skillhub)
- **License:** Apache-2.0
- **Homepage:** https://skill.xfyun.cn

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-iflytek-skillhub-backend-module-structure
- Seller: https://agentstack.voostack.com/s/iflytek
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.