# hmrc/income-tax-property-frontend architecture

> Architecture diagram of the GitHub repository hmrc/income-tax-property-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hmrc/income-tax-property-frontend
- Repository: https://github.com/hmrc/income-tax-property-frontend

## Overview

This project is an income-tax property frontend service used for presenting and modifying the “Property” section within a user’s income tax return. It is built in Scala and follows the Play Framework’s MVC and modular architectural conventions. In other words, it is a full-stack web application “front end” that manages a complex set of pages and forms related to property tax information, and then routes those requests through dedicated controllers and services to interact with external systems (e.g., via connectors, repositories and integrations with MongoDB and other backend services).

##### Main Components
- User Interface (Views/Assets): At the top are the HTML templates and client-side assets (in app/assets, app/views, and even govuk-specific viewmodels) that render the user interface. These are used by a multitude of pages that cover topics such as adjustments, allowances, foreign property, property rentals, UK and foreign property details, etc.
- Controllers: The app/controllers directory is well structured with sub-packages (about, adjustments, allowances, foreign, premiumlease, propertyrentals, ukandforeignproperty, ukrentaroom, structurebuildingallowance, etc.). Each set of controllers handles specific user requests and orchestrates the flow from the incoming HTTP requests to the business logic.
- Forms and Viewmodels: The app/forms and app/viewmodels directories encapsulate data validation and the presentation logic for the pages (e.g. check your answers summaries). These are tightly coupled to the controllers and views.
- Business Services & Connectors: The app/service directory contains core services (like BusinessService, JourneyAnswersService, PropertySubmissionService, etc.) that implement the business logic. In parallel, the app/connectors package defines how the service communicates with external APIs (e.g. the BusinessConnector, PropertySubmissionConnector, and others) – representing the integration layer with backend systems.
- Repositories & Database Integration: The app/repositories directory (with SessionRepository for example) indicates that the application uses a persistence layer (MongoDB is mentioned in the README) to store session and journey data.
- Configuration & Routing: The “conf” folder holds the routes definitions and various runtime properties. This is key in mapping the incoming HTTP requests to their corresponding controllers.
- Audit and Error Handling: The app/audit package logs user actions and audit information, while the app/handlers and app/controllers/exceptions directories contain components designed to manage errors.

##### Relationships and Interactions
- The controllers (organized by business domain such as “Adjustments”, “Allowances”, “Foreign”, etc.) receive these requests. They—in collaboration with the form validations and page viewmodels—coordinate actions.
- Business Services are then invoked by controllers to process the request. These services enforce business logic (e.g. validating tax property rules) and often call connectors.
- The Connectors serve as bridges to external backend systems (such as the “Property Submission Connector” or “Journey Answers Connector”) and sometimes interact with a MongoDB repository.
- Audit and error handling modules are integrated throughout the flow so that all significant actions and failures are logged and managed appropriately.
- Finally, the processed data is bound into viewmodels and rendered by the views/templates to form the HTML response sent back to the user.

##### Architectural Patterns and Design Principles
- MVC: The design follows the Model–View–Controller pattern. Separate presentation (views and forms), control (controllers), and business logic (services, connectors) components ensure a clean separation of concerns.
- Layering: You have distinct layers—presentation, domain services, data access, and configuration.
- Modularity: Each property tax domain is split into well-named packages (e.g., about, adjustments, foreign, etc.), which helps in scaling and maintenance.
- Integration: The connectors and repositories demonstrate an integration layer that connects this front end with other HMRC services and a local MongoDB instance.

##### Additional Notes
- Remember to note that the configuration layer (contained in “conf” and the project configuration files) plays a crucial role in routing and environment-based behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        A1("HTML Templates"):::ui
        A2("Client-side Assets"):::ui
        A3("ViewModels"):::ui
    end

    %% Configuration & Routing Layer
    subgraph "Configuration & Routing"
        B1("Routes & Config"):::config
    end

    %% Controllers Layer
    subgraph "Controllers Layer"
        C1("Controllers"):::controller
        C2("Forms & Viewmodels (Validation)"):::controller
        C3("Exception Handlers"):::controller
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        D1("Business Services"):::service
        D2("Connectors"):::service
    end

    %% Data Persistence Layer
    subgraph "Data Persistence Layer"
        E1("Repositories"):::database
        E2("MongoDB"):::database
    end

    %% Audit & Error Handling
    subgraph "Audit & Error Handling"
        F1("Audit Logging"):::audit
        F2("Error Handlers"):::audit
    end

    %% External Integrations
    subgraph "External Dependencies"
        G1("Service Manager"):::external
        G2("Backend Services"):::external
    end

    %% User Interaction
    U("User Browser"):::external

    %% Connections
    U -->|"HTTP Request"| B1
    B1 -->|"routes to"| C1
    C1 -->|"validates via"| C2
    C1 -->|"invokes"| D1
    C2 -->|"submits data to"| D1
    D1 -->|"calls"| D2
    D1 -->|"persists data via"| E1
    D2 -->|"integrates with"| G2
    E1 -->|"stores data in"| E2
    D1 -->|"logs action"| F1
    C1 -->|"handles errors with"| F2
    D1 -->|"renders response to"| A1
    A1 -->|"returns HTML to"| U

    %% Click Events
    click A1 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/views"
    click A2 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/assets"
    click A3 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/viewmodels"
    click B1 "https://github.com/hmrc/income-tax-property-frontend/tree/main/conf"
    click C1 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/controllers"
    click C2 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/forms"
    click C3 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/controllers/exceptions"
    click D1 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/service"
    click D2 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/connectors"
    click E1 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/repositories"
    click F1 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/audit"
    click F2 "https://github.com/hmrc/income-tax-property-frontend/tree/main/app/handlers"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef controller fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef service fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef audit fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef external fill:#fefefe,stroke:#6c757d,stroke-width:2px;
```
