Hexagonal architecture

[bavo]

Hexagonal Architecture in jmolecules

When using a hexagonal architecture, we usually default to the following structure:

src/
├── core/
│   ├── domain/
│   ├── ports/   
│   │   ├── primary/
│   │   │        ├── ....
│   │   │        └── ....
│   │   └── secondary/
│   │   │        ├── ....
│   │   │        └── ....
│   └── application/     (or use-case)
└── adapters/
    ├── primary/     
    │   ├── ....  
    │   └── ....
    └── secondary/     
          ├── ....
          └── ....

But when I look at the jmolecules annotations for hexagonal architecture, there is no annotation for the domain 'layer'. Currently, only the following annotations are available:

• @Application
• @Port (Primary/Secondary)
• @Adapter (Primary/Secondary)

This leaves it unclear how to strictly separate the domain from the application/use-case layer and enforce or document intended dependency direction (e.g., the domain must not depend on the application/use-case code).

Expected structure (logical dependencies):

graph LR;

Adapters --> Ports --> Application --> Domain

Loading

---

Expanded Explanation (you can feel the AI shine through 🫣, sorry about that)

Layering Explained:

• Domain:
  Contains the business logic and domain model. Should be fully independent, without references to applications, ports, or adapters.
  Note: There is currently no @Domain annotation in jmolecules; the domain layer is defined only by convention (e.g., core/domain/).

• Application (Use-Case):
  Orchestrates use-case logic and is annotated with @Application. May depend on the domain model and ports, but never the other way around.

• Ports:
  Interfaces that define contracts for communication between core/application and external systems. Annotated with @Port (Primary or Secondary).

  • Primary Port: Driven by external input.
  • Secondary Port: Driven by the application/core.

• Adapters:
  Implement external interactions, annotated with @Adapter (Primary or Secondary).

Dependency Direction:

• The domain layer must never depend on application/use-case logic, ports, or adapters.
• The application layer may depend on domain and ports, but not on adapters.
• Ports are interfaces that may be referenced by both application and adapter layers.
• Adapters implement ports and may depend on ports and application, but not directly on the domain.

---

Recommended Dependency Table

Layer	Can depend on...	Must NOT depend on...
Domain	(none)	Application, Ports, Adapters
Application	Domain, Ports	Adapters
Ports	Domain (types, rarely)	Adapters
Adapters	Ports, Application	Domain

---

Best Practices with jmolecules

• Use a strict folder structure to clarify the intent, since there is no @Domain annotation.
• Use @Application for orchestration/use-case classes.
• Use @Port for interfaces in the ports package.
• Use @Adapter for adapter implementations.
• Keep domain model code free from jmolecules annotations or framework dependencies.

Open questions:

• Would the addition of a @Domain annotation help clarify these boundaries?
• Should jmolecules annotations be extended to better express strict layering?

Feedback and suggestions for improving this layering and annotation support are welcome!

[bavo]

I think this is the same discussion:
#125