Architecture Rules

Dependency Direction

• domain must not depend on application or infrastructure
• application may depend on domain
• infrastructure may depend on application and domain
• ui must only depend on backend API contracts, never on backend internals

Layer Responsibilities

Domain

Owns:

• entities
• value objects
• domain services
• core business rules

Must not contain:

• Spring-specific code
• persistence details
• HTTP concerns
• infrastructure details

Application

Owns:

• use cases
• orchestration
• input/output ports
• transaction boundaries where appropriate

Must not contain:

• persistence implementation details
• delivery/framework-heavy concerns

Infrastructure

Owns:

• REST controllers
• persistence adapters
• JPA repositories
• external clients
• messaging integrations
• configuration
• framework-specific code

Must not contain:

• core business rules that belong in domain

Frontend Architecture

• Treat the UI as a client of the backend
• Keep components focused on presentation
• Keep API communication in services, hooks, or dedicated client modules
• Prefer feature-oriented organization when it improves clarity
• Avoid mixing API access directly into presentation components
• Avoid placing business rules inside UI components

Folder Guidelines

UI

Preferred structure:

• ui/src/components
• ui/src/services

Other folders may be used when helpful:

• ui/src/pages
• ui/src/hooks
• ui/src/features
• ui/src/types

Backend

Preferred structure:

• backend/src/application
• backend/src/domain
• backend/src/infrastructure

Use subpackages by concept or use case when helpful, for example:

• backend/src/application/findshipments
• backend/src/application/createalert

Platform Conventions

• Use modern Spring Boot annotations where appropriate
• Prefer MapStruct for mapping
• Prefer UUID for entity IDs unless the project already uses another pattern consistently

Naming Conventions

• Use names that reflect business intent
• Prefer names like:
  • CreateAlert
  • FindShipments
  • ResolveAlert
• Avoid vague names like:
  • HandleAlert
  • ProcessThing
  • DoShipment
• Use consistent naming across backend and UI

TypeScript Rules

• Use strict typing
• Avoid any
• Use explicit types for public interfaces
• Prefer narrow, intention-revealing types over loose object shapes

Error Handling

• Handle expected errors explicitly
• Do not swallow errors silently
• Return meaningful error information where relevant
• Prefer explicit failure handling over hidden fallback behaviour

Testing Rules

• Add solitary tests for isolated logic
• Add sociable tests where collaboration between real components matters
• Use Testcontainers when needed
• Prioritize tests for:
  • domain logic
  • use cases
  • critical mapping logic
  • important API flows
• Avoid brittle UI snapshot tests unless they provide clear value