# hmrc/tai-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/hmrc/tai-frontend
- Repository: https://github.com/hmrc/tai-frontend

## Overview

##### Project type and purpose
- This is a full-stack Play Framework (Scala) web application that serves as the “Tax Account for Individuals” frontend.
- It provides UI pages, form journeys and print assets for users to view/edit PAYE tax info, and it orchestrates calls to downstream microservices (the TAI backend, NPS, JRS, etc.).

##### File structure
- app/controllers: HTTP entry points (Play controllers), grouped by feature (income, pensions, benefits, auth, error pages).
- app/views: Twirl templates for rendering HTML.
- app/assets: JS, CSS/SCSS, images for the frontend.
- app/service: Business-logic services that call connectors and prepare view models.
- app/connectors: HTTP clients to downstream microservices (TaiConnector, TaxAccountConnector, CitizenDetailsConnector, etc.).
- app/repository: JourneyCacheRepository (caching wizard state), SessionConnector (session store).
- app/model & viewModels: Domain and presentation models.
- conf: Play routes, configuration.
- test & it: Unit and integration tests.

##### Key insights from README
- It’s a Scala 2.13 & Play 3.0 application that requires JRE 21.
- It’s purely frontend: no internal database; all persistent/stateful calls go through connectors to HMRC microservices.
- Authentication is handled via an Auth stub / Single Customer Account (SCA) service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Zone"
        Client["Browser / Client"]:::client
        Assets["Static Assets (JS/CSS/Images)"]:::assets
    end

    subgraph "Server Zone: Play Framework App"
        subgraph "Configuration & Routing"
            AppConf["application.conf"]:::config
            RoutesFile["tai.routes"]:::config
            ApplicationConfig["ApplicationConfig"]:::config
            FeatureTogglesConfig["FeatureTogglesConfig"]:::config
            TaiModule["TaiModule"]:::config
            SessionModule["SessionModule"]:::config
            ErrorHandler["ErrorHandler"]:::config
        end

        subgraph "HTTP Layer"
            Router["Play Router"]:::http
            Filters["Filters & Actions"]:::http
            Controllers["Controllers"]:::http
        end

        subgraph "Business Layer"
            Services["Business Services"]:::business
            SessionService["SessionService"]:::business
        end

        subgraph "Models & Utils"
            ViewModels["ViewModels"]:::model
            DomainModels["Domain Models"]:::model
            Utils["Utilities & Helpers"]:::model
            Forms["Forms & Validation"]:::model
        end

        subgraph "Data Layer"
            subgraph "Connectors"
                TaiConnector["TaiConnector"]:::data
                TaxAccountConnector["TaxAccountConnector"]:::data
                JrsConnector["JrsConnector"]:::data
                CitizenDetailsConnector["CitizenDetailsConnector"]:::data
                PensionProviderConnector["PensionProviderConnector"]:::data
                EmploymentsConnector["EmploymentsConnector"]:::data
                BenefitsConnector["BenefitsConnector"]:::data
                RtiConnector["RtiConnector"]:::data
            end
            subgraph "Repositories"
                JourneyRepo["JourneyCacheRepository"]:::data
                SessionConnector["SessionConnector"]:::data
            end
        end

        subgraph "View Layer"
            Views["Twirl Templates & HTML Views"]:::view
        end
    end

    subgraph "External Services"
        TAIbackend["TAI Backend"]:::external
        NPS["NPS Service"]:::external
        JRS["JRS Service"]:::external
        CitizenDetails["CitizenDetails Service"]:::external
        SessionCache["Session Cache"]:::external
        AuthService["Authentication Service"]:::external
    end

    %% Flows
    Client -->|"HTTP Request"| Router
    Router -->|calls| Filters
    Filters -->|after auth/data retrieval| Controllers
    Controllers -->|invoke| Services
    Services -->|use| ViewModels
    Services -->|invoke| DomainModels
    Services -->|validate via| Forms
    Services -->|helper logic| Utils
    Services -->|session ops| SessionService
    SessionService -->|stores/reads| JourneyRepo
    SessionService -->|stores/reads| SessionConnector
    Services -->|calls downstream| TaiConnector
    Services -->|calls downstream| TaxAccountConnector
    Services -->|calls downstream| JrsConnector
    Services -->|calls downstream| CitizenDetailsConnector
    Services -->|calls downstream| PensionProviderConnector
    Services -->|calls downstream| EmploymentsConnector
    Services -->|calls downstream| BenefitsConnector
    Services -->|calls downstream| RtiConnector
    TaiConnector -->|REST/JSON over HTTPS| TAIbackend
    TaxAccountConnector -->|REST/JSON over HTTPS| NPS
    JrsConnector -->|REST/JSON over HTTPS| JRS
    CitizenDetailsConnector -->|REST/JSON over HTTPS| CitizenDetails
    SessionConnector -->|connects to| SessionCache
    Filters -->|auth checks| AuthService
    Controllers -->|render| Views
    Client -->|requests assets| Assets

    %% Click Events
    click Assets "https://github.com/hmrc/tai-frontend/tree/main/app/assets"
    click Controllers "https://github.com/hmrc/tai-frontend/tree/main/app/controllers"
    click Filters "https://github.com/hmrc/tai-frontend/tree/main/app/controllers/actions"
    click Filters "https://github.com/hmrc/tai-frontend/tree/main/app/controllers/auth"
    click Filters "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/filters/TaxAccountFilter.scala"
    click Services "https://github.com/hmrc/tai-frontend/tree/main/app/uk/gov/hmrc/tai/service"
    click SessionService "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/service/SessionService.scala"
    click JourneyRepo "https://github.com/hmrc/tai-frontend/blob/main/app/repository/JourneyCacheRepository.scala"
    click SessionConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/SessionConnector.scala"
    click TaiConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/TaiConnector.scala"
    click TaxAccountConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/TaxAccountConnector.scala"
    click JrsConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/JrsConnector.scala"
    click CitizenDetailsConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/CitizenDetailsConnector.scala"
    click PensionProviderConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/PensionProviderConnector.scala"
    click EmploymentsConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/EmploymentsConnector.scala"
    click BenefitsConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/BenefitsConnector.scala"
    click RtiConnector "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/connectors/RtiConnector.scala"
    click Views "https://github.com/hmrc/tai-frontend/tree/main/app/views"
    click AppConf "https://github.com/hmrc/tai-frontend/blob/main/conf/application.conf"
    click RoutesFile "https://github.com/hmrc/tai-frontend/blob/main/conf/tai.routes"
    click ApplicationConfig "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/config/ApplicationConfig.scala"
    click FeatureTogglesConfig "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/config/FeatureTogglesConfig.scala"
    click TaiModule "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/config/TaiModule.scala"
    click SessionModule "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/config/SessionModule.scala"
    click ErrorHandler "https://github.com/hmrc/tai-frontend/blob/main/app/uk/gov/hmrc/tai/config/ErrorHandler.scala"
    click ViewModels "https://github.com/hmrc/tai-frontend/tree/main/app/uk/gov/hmrc/tai/viewModels"
    click DomainModels "https://github.com/hmrc/tai-frontend/tree/main/app/uk/gov/hmrc/tai/model/domain"
    click Utils "https://github.com/hmrc/tai-frontend/tree/main/app/uk/gov/hmrc/tai/util"
    click Forms "https://github.com/hmrc/tai-frontend/tree/main/app/uk/gov/hmrc/tai/forms"

    %% Styles
    classDef client fill:#e3f2fd,stroke:#90caf9,color:#0d47a1;
    classDef assets fill:#eceff1,stroke:#b0bec5,color:#37474f;
    classDef config fill:#fff3e0,stroke:#ffb74d,color:#e65100;
    classDef http fill:#bbdefb,stroke:#64b5f6,color:#0d47a1;
    classDef business fill:#c8e6c9,stroke:#81c784,color:#1b5e20;
    classDef data fill:#dcedc8,stroke:#aed581,color:#33691e;
    classDef view fill:#f3e5f5,stroke:#ba68c8,color:#4a148c;
    classDef model fill:#fff9c4,stroke:#fff176,color:#f57f17;
    classDef external fill:#ffccbc,stroke:#ff8a65,color:#bf360c;
```
