How hmrc/income-tax-property-frontend works
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.