Skip to main content
Version: 2.0.0

Backend Architecture

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

System Architecture Overview​

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                │
└─────────────────────────────────────────────────────────────────┘

Technology Stack Summary​

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

Architectural Components​

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

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.

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.

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.

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.

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.

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.

Component Interactions​

Example Flow – Creating a Resource​

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

Example Flow – Retrieving Data​

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

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.

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