# hmrc/sdlt-filing-frontend architecture

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

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

## Overview

sdlt-filing-frontend is an HMRC frontend for creating new Stamp Duty Land Tax returns and completing existing in-progress returns. Users enter return details across preliminary, transaction, purchaser, land, lease, residency, and agent sections, review and save them, then proceed through tax calculation and submission. The task list is the central return-workflow hub; the sampled transaction and agent review controllers show persistence-backed checks and calls to the SDLT backend. The tree documents the other major sections, but their internal wiring and some integrations were not sampled, so uncertain links are omitted.

Main entry points: [`app/controllers/ReturnTaskListController.scala`](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/controllers/ReturnTaskListController.scala) (Return task list), [`app/controllers/purchaserAgent`](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/purchaserAgent) (Purchaser and vendor agents), [`app/controllers/transaction`](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/transaction) (Transaction details), [`app/connectors/StampDutyLandTaxConnector.scala`](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/connectors/StampDutyLandTaxConnector.scala) (SDLT backend connector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_return["Return workflow"]
  node_index["Frontend entry"]
  node_tasklist["Return task list"]
  node_useranswers["Return answers<br/>[UserAnswers.scala]"]
end

subgraph group_details["Return details"]
  node_preliminary["Preliminary details"]
  node_transaction["Transaction details"]
  node_purchaser["Purchaser details"]
  node_land["Land details"]
  node_lease["Lease details"]
  node_residency["Residency details"]
end

subgraph group_tax["Tax and submission"]
  node_taxcalc["Tax calculation"]
  node_submission["Return submission"]
end

subgraph group_agents["Agent details"]
  node_agentcontrollers["Purchaser and vendor agents"]
  node_agentservice["Agent services"]
end

subgraph group_integrations["Integrations"]
  node_backendconnector["SDLT backend connector"]
  node_calculationconnector["Calculation connector"]
  node_addressconnector["Address lookup connector"]
end

node_user(("Return filer"))

node_user -->|"opens service"| node_index
node_user -->|"continues return"| node_tasklist
node_tasklist -->|"opens section"| node_preliminary
node_tasklist -->|"opens section"| node_transaction
node_tasklist -->|"opens section"| node_purchaser
node_tasklist -->|"opens section"| node_land
node_tasklist -->|"opens section"| node_lease
node_tasklist -->|"opens section"| node_residency
node_tasklist -->|"opens section"| node_agentcontrollers
node_tasklist -->|"opens section"| node_taxcalc
node_tasklist -->|"opens section"| node_submission
node_agentcontrollers -->|"validates and populates"| node_agentservice
node_agentcontrollers -->|"creates agent"| node_backendconnector
node_transaction -->|"creates lease"| node_backendconnector

click node_index "https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/controllers/IndexController.scala"
click node_tasklist "https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/controllers/ReturnTaskListController.scala"
click node_preliminary "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/preliminary"
click node_transaction "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/transaction"
click node_purchaser "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/purchaser"
click node_land "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/land"
click node_lease "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/lease"
click node_residency "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/ukResidency"
click node_useranswers "https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/models/UserAnswers.scala"
click node_agentcontrollers "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/purchaserAgent"
click node_agentservice "https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/services/purchaserAgent/PurchaserAgentService.scala"
click node_taxcalc "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/taxCalculation"
click node_submission "https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/submission"
click node_backendconnector "https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/connectors/StampDutyLandTaxConnector.scala"
click node_calculationconnector "https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/connectors/SdltCalculationConnector.scala"
click node_addressconnector "https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/connectors/AddressLookupConnector.scala"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_tasklist,node_useranswers toneBlue
class node_preliminary,node_transaction,node_purchaser,node_land,node_lease,node_residency toneAmber
class node_taxcalc,node_submission toneMint
class node_agentcontrollers,node_agentservice toneRose
class node_backendconnector,node_calculationconnector,node_addressconnector,node_user toneIndigo
```

## Components

### Return workflow

- [Frontend entry](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/controllers/IndexController.scala): `app/controllers/IndexController.scala`
- [Return task list](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/controllers/ReturnTaskListController.scala): `app/controllers/ReturnTaskListController.scala`
- [Return answers](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/models/UserAnswers.scala): `app/models/UserAnswers.scala`

### Return details

- [Preliminary details](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/preliminary): `app/controllers/preliminary`
- [Transaction details](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/transaction): `app/controllers/transaction`
- [Purchaser details](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/purchaser): `app/controllers/purchaser`
- [Land details](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/land): `app/controllers/land`
- [Lease details](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/lease): `app/controllers/lease`
- [Residency details](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/ukResidency): `app/controllers/ukResidency`

### Tax and submission

- [Tax calculation](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/taxCalculation): `app/controllers/taxCalculation`
- [Return submission](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/submission): `app/controllers/submission`

### Agent details

- [Purchaser and vendor agents](https://github.com/hmrc/sdlt-filing-frontend/tree/main/app/controllers/purchaserAgent): `app/controllers/purchaserAgent`
- [Agent services](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/services/purchaserAgent/PurchaserAgentService.scala): `app/services/purchaserAgent/PurchaserAgentService.scala`

### Integrations

- [SDLT backend connector](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/connectors/StampDutyLandTaxConnector.scala): `app/connectors/StampDutyLandTaxConnector.scala`
- [Calculation connector](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/connectors/SdltCalculationConnector.scala): `app/connectors/SdltCalculationConnector.scala`
- [Address lookup connector](https://github.com/hmrc/sdlt-filing-frontend/blob/main/app/connectors/AddressLookupConnector.scala): `app/connectors/AddressLookupConnector.scala`

### Other components

- **Return filer**

## Connections

- Return filer → Frontend entry: opens service
- Return filer → Return task list: continues return
- Return task list → Preliminary details: opens section
- Return task list → Transaction details: opens section
- Return task list → Purchaser details: opens section
- Return task list → Land details: opens section
- Return task list → Lease details: opens section
- Return task list → Residency details: opens section
- Return task list → Purchaser and vendor agents: opens section
- Return task list → Tax calculation: opens section
- Return task list → Return submission: opens section
- Purchaser and vendor agents → Agent services: validates and populates
- Purchaser and vendor agents → SDLT backend connector: creates agent
- Transaction details → SDLT backend connector: creates lease