Skip to main content

Architecture

1. Summary​

The Portal Backend is built using a clear, modular architecture that keeps API handling, business logic, data processing, and storage concerns separate.

Core Principles​

  • Clear Responsibility Boundaries
  • Controlled Inter-Layer Dependencies
  • Extensibility Without Refactoring
  • Strong Reliability and Type Safety

2. System Architecture Overview​

2.1 Layered Architecture (High-Level)​

┌─────────────────────────────────────────────────┐
│  1. API LAYER - Client Interface                │
│     Handles external requests and responses     │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────────────┐
│  2. RESPONSE LAYER - Output Preparation                         │
│     Shapes, enriches, and optimizes API response structures     │
└─────────────────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────────────┐
│  3. BUSINESS LAYER - Core Logic                                 │
│     Enforces business rules and coordinates workflows           │
└─────────────────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────────────┐
│  4. CONVERSION LAYER - Data Transformation                      │
│     Converts between API-facing DTOs and internal domain models │
└─────────────────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────────────┐
│  5. DATA ACCESS LAYER - Persistence                             │
│     Manages structured access to the database                   │
└─────────────────────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────────────┐
│  6. DOMAIN MODEL - Core Structures                              │
│     Defines entities and shared data definitions                │
└─────────────────────────────────────────────────────────────────┘

2.2 Technology Stack Summary​

  • Runtime: Spring Boot
  • Database: PostgreSQL
  • Data Access: Spring Data JPA
  • API: REST (JSON)
  • Mapping: MapStruct

3. Architectural Components

This section describes the key components that make up each layer of the backend architecture. While Section 2 focuses on the structure of the architecture, this section focuses on the purpose and role of each component.

3.1 Controllers (API Layer)​

Component Name: Controller Primary Role: Entry point for all client interactions. Responsibilities:

  • Receive and validate HTTP requests
  • Delegate operations to Services
  • Return standardized API responses
  • Maintain API contract without hosting business logic

Controllers keep the API surface stable even as internal behavior evolves.

3.2 Assemblers (Response Layer)​

Component Name: Assembler Primary Role: Prepare client-facing output structures. Responsibilities:

  • Convert domain entities into OutputDTOs
  • Add summaries of related entities
  • Shape responses for usability and efficiency
  • Keep domain internals hidden from API consumers

Assemblers ensure responses are optimized, consistent, and decoupled from internal models.

3.3 Services (Business Layer)​

Component Name: Service Primary Role: Core executor of business processes. Responsibilities:

  • Enforce business rules and validation
  • Coordinate multiple repositories
  • Manage transactional boundaries
  • Implement workflows for create, update, and retrieval operations

Services represent the authoritative business logic of the system.

3.4 Mappers (Conversion Layer)​

Component Name: Mapper Primary Role: Transform data between internal and external structures. Responsibilities:

  • Convert Input DTOs → Entities
  • Convert Entities → Output or Summary DTOs
  • Apply partial updates (PATCH)
  • Keep transformation logic consistent and stateless

Mappers ensure data moves cleanly and safely across architectural boundaries.

3.5 Repositories (Data Access Layer)​

Component Name: Repository Primary Role: Structured access to the database. Responsibilities:

  • CRUD operations
  • Query filtering, pagination, sorting
  • Optimized data fetching strategies
  • Abstracting SQL/JPA complexity

Repositories isolate the rest of the system from persistence concerns.

3.6 Domain Model (Model Layer)​

Components: Entities, InputDTOs, OutputDTOs, SummaryDTOs, Specifications Primary Role: Define the system’s core data structures and relationships. Responsibilities:

  • Represent real-world business concepts
  • Define database mappings
  • Provide query specifications
  • Maintain separation between internal and API-facing structures

The domain model is the foundation upon which all higher layers operate.

4. Component Interactions​

4.1 Example Flow – Creating a Resource​

Client → API Layer → Business Layer → Conversion Layer → Data Access Layer → Database
                        ↓
                   Response Layer → API Layer → Client

4.2 Example Flow – Retrieving Data​

Client → API Layer → Business Layer → Data Access Layer → Database
                        ↓
              Response Layer → API Layer → Client

4.3 Dependency Direction (Strict)​

  • API → Business → Data → Domain Model
  • No layer reaches back “upward”
  • No cross-layer shortcuts

This ensures predictability and reduces long-term coupling.

5. Key Architectural Choices​

5.1 Layered Architecture Benefits​

  • Maintains clarity and order
  • Enables straightforward testing
  • Allows parallel development
  • Scales naturally with new features

5.2 Dedicated Response Layer​

Keeps client-facing structures stable and optimized, even as domain models evolve.

5.3 DTO Strategy​

  • Input DTOs – Data provided by clients
  • Output DTOs – Full responses for clients
  • Summary DTOs – Lightweight nested structures

This minimizes payload size and protects internal structures.

5.4 Declarative Querying​

Filtering is handled automatically based on request parameters—no manual query construction needed.

6. Cross-Cutting Concerns​

6.1 Transactions​

Business logic is executed inside controlled, automatic transactional boundaries.

6.2 Performance​

  • Smart relation loading
  • Pagination everywhere
  • Summary objects for nested data

6.3 Validation​

  • API-level validation
  • Business rule validation
  • Database constraints

7. Scalability and Extensibility​

7.1 Adding New Features​

New entities follow a predictable pattern with minimal custom work due to shared base components.

7.2 Lifecycle Hooks​

Optional pre/post logic allows extensions without modifying the core framework.

7.3 Query Extensions​

New filters can be added without code changes to core logic.

8. Data Model Overview​

Entity Structure​

A set of shared base entities unify IDs, timestamps, names, and descriptions.

Relationship Patterns​

  • Ownership
  • Hierarchical relationships
  • Many-to-many structures

9. Glossary​

  • Entity – Internal representation of a real-world object
  • DTO – Client-facing data structure
  • Repository – Database access interface
  • Service – Core business logic component
  • Assembler – Builds structured API responses
  • Mapper – Converts between DTOs and domain models