# ministryofjustice/laa-ccms-data-api architecture

> Architecture diagram of the GitHub repository ministryofjustice/laa-ccms-data-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ministryofjustice/laa-ccms-data-api
- Repository: https://github.com/ministryofjustice/laa-ccms-data-api

## Overview

##### Project Type and Purpose
- This is a backend API microservice split into two Gradle subprojects:
– data‑api: a thin layer generated from an OpenAPI spec (YAML) containing request/response models and interface stubs.
– data‑service: a Spring‑Boot application that implements those interfaces, providing controllers, services, repositories, mappers and JPA entities to talk to an Oracle (or H2 for tests) database.
- It is packaged into a Docker image, deployed to Kubernetes via the kubectl_deploy manifests, and has CI/CD pipelines in GitHub Actions that run builds, tests, Snyk scans, and deployments.

##### High‑Level File Structure & Architectural Patterns
– Top‑level modules:
- data‑api: holds the OpenAPI spec and generated code
- data‑service: holds the Spring‑Boot application
– Typical layered architecture in data‑service:
- controller layer (uk.gov.laa.ccms.data.controller)
- service layer (uk.gov.laa.ccms.data.service)
- data access layer:
· repository interfaces (JPA/EntityManager)
· mappers (MapStruct or manual XML mappers)
· entity classes (JPA @Entity)
– Configuration & Infra:
- application.yml variants, Dockerfile, Kubernetes manifests (kubectl_deploy/)
- CI/CD config (.github/workflows, .snyk)

##### Key Insights from README
– data‑api is auto‑generated; keep open-api-specification.yml in sync
– data‑service implements the generated interfaces
– Uses common Spring Boot plugins & starters from the LAA CCMS common library
– CI/CD runs Snyk scans on main and feature branches

##### Components & Their Relationships
A. External Client(s): Postman, front‑end apps, other services
↓ invoke
B. API Interface Layer (data‑api stub):
- Exposes REST endpoints as defined in open-api-specification.yml
- Models (DTOs) and interface definitions
↓ invokes
C. Core Application (data‑service):
1. Controllers map HTTP requests to service calls
2. Services contain business logic and orchestrate data access
3. Mappers convert between entity and DTO models
4. Repositories talk to the database via JPA/Hibernate or raw SQL
↓ persists/queries
D. Database: Oracle (production), H2 (integration tests)

E. CI/CD & Infra:
- GitHub Actions: build/test, Snyk scan, deploy to Kubernetes
- Dockerfile: builds the service image
- Kubernetes: ingress + service definitions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    ExternalClients["External Clients"]:::cloud

    %% API Interface Layer
    subgraph "API Interface Layer (data‑api)"
        OpenAPISpec["OpenAPI Spec"]:::code
        GeneratedStub["Generated Stub (build.gradle)"]:::code
    end

    %% Core Application
    subgraph "Core Application (data‑service)"
        MainApp["DataApplication (Spring Boot)"]:::code
        ConfigYml["application.yml variants"]:::code

        subgraph "Layered Architecture"
            Controllers["Controllers"]:::code
            Services["Services"]:::code
            Mappers["Mappers"]:::code
            Repositories["Repositories"]:::code
            Entities["Entities"]:::code
        end
    end

    %% Database
    DB["Oracle / H2 Database"]:::db

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        CI["GitHub Actions"]:::infra
        DockerfileNode["Dockerfile"]:::infra
        K8s["Kubernetes Manifests"]:::infra
    end

    %% Data Flow
    ExternalClients -->|"1: invoke REST"| OpenAPISpec
    OpenAPISpec -->|"2: generated API stub"| GeneratedStub
    GeneratedStub -->|"3: HTTP request mapping"| Controllers
    Controllers -->|"4: business logic"| Services
    Services -->|"5: data access"| Repositories
    Repositories -->|"6: persist/query"| DB
    Services -->|"7: transform models"| Mappers
    MainApp -->|boots| Controllers

    %% Deployment Flow
    CI -->|"build/test/scan"| DockerfileNode
    DockerfileNode -->|"build image"| K8s
    K8s -->|"deploy service"| MainApp

    %% Click Events
    click OpenAPISpec "https://github.com/ministryofjustice/laa-ccms-data-api/blob/main/data-api/open-api-specification.yml"
    click GeneratedStub "https://github.com/ministryofjustice/laa-ccms-data-api/blob/main/data-api/build.gradle"
    click Controllers "https://github.com/ministryofjustice/laa-ccms-data-api/tree/main/data-service/src/main/java/uk/gov/laa/ccms/data/controller"
    click Services "https://github.com/ministryofjustice/laa-ccms-data-api/tree/main/data-service/src/main/java/uk/gov/laa/ccms/data/service"
    click Mappers "https://github.com/ministryofjustice/laa-ccms-data-api/tree/main/data-service/src/main/java/uk/gov/laa/ccms/data/mapper"
    click Repositories "https://github.com/ministryofjustice/laa-ccms-data-api/tree/main/data-service/src/main/java/uk/gov/laa/ccms/data/repository"
    click Entities "https://github.com/ministryofjustice/laa-ccms-data-api/tree/main/data-service/src/main/java/uk/gov/laa/ccms/data/entity"
    click MainApp "https://github.com/ministryofjustice/laa-ccms-data-api/blob/main/data-service/src/main/java/uk/gov/laa/ccms/data/DataApplication.java"
    click ConfigYml "https://github.com/ministryofjustice/laa-ccms-data-api/blob/main/data-service/src/main/resources/application.yml"
    click CI "https://github.com/ministryofjustice/laa-ccms-data-api/blob/main/.github/workflows/build-main.yml"
    click DockerfileNode "https://github.com/ministryofjustice/laa-ccms-data-api/tree/main/Dockerfile"
    click K8s "https://github.com/ministryofjustice/laa-ccms-data-api/blob/main/kubectl_deploy/ingress.yaml"

    %% Styles
    classDef code fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef db fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef cloud fill:#e0e0e0,stroke:#333,stroke-width:1px
```
