# ministryofjustice/analytical-platform architecture

> Architecture diagram of the GitHub repository ministryofjustice/analytical-platform, 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/ministryofjustice/analytical-platform
- Repository: https://github.com/ministryofjustice/analytical-platform

## Overview

This repository isn’t a traditional full-stack application but rather a highly modular infrastructure repository for the Ministry of Justice Analytical Platform. Its purpose is twofold: to provide the technical documentation (and associated site building/publishing mechanisms) and to hold the infrastructure-as-code (IaC) artifacts—with heavy use of Terraform—to build and manage the analytical infrastructure used for storing, ingesting, and consuming data on AWS.

##### Main Components
- Documentation & Website Delivery:
– The source folder along with configuration files (e.g., config/tech-docs.yml) and Middleman preview scripts in the “scripts/docs” directory are responsible for rendering and publishing the technical documentation.
- CI/CD and Development Environment:
– The .github directory contains workflows, GitHub actions, dependency checks, and other automation tools for tasks like publishing documentation and enforcing code standards.
– The .devcontainer folder shows configuration for the development environment (e.g. VS Code remote containers).
- Infrastructure-as-Code Modules (Terraform):
– A significant part of the repository is taken up by the terraform directory. It contains multiple subdirectories representing different environments and components such as authentication (auth0), AWS infrastructure (EKS clusters, VPCs, security groups, EC2 instances, S3, Athena, CloudTrail, Route53), message brokers, build and artifact repositories, and more.
- Operational Scripts:
– The scripts folder encompasses various scripts that support operations like bucket archiving, user validation, data ingestion, Kubernetes operations, PagerDuty integrations, etc.
- Architectural Documentation & ADRs:

##### Relationships and Interactions
- CI/CD pipelines connect and coordinate the deployment of infrastructure (Terraform modules) and the documentation publishing process. Illustrate how GitHub Actions pull configurations from the repository and trigger deployment tasks.
- Operational scripts (for bucket archiving, ingress/egress tasks, and system monitoring) are run either as scheduled tasks or triggered by events in the CI/CD pipelines, and they interact with the AWS infrastructure.

##### Architectural Patterns and Design Principles
- Infrastructure as Code: The repository is organized around Terraform modules following the best practice of modular and environment-specific configuration.
- Separation of Concerns: Distinct directories are used to separate documentation, operational scripts, development environment configuration, and cloud infrastructure. This modular design eases maintenance and allows teams to work on different aspects independently.
- CI/CD Integration: GitHub Actions workflows are used to automate testing, deployment, validation, and publishing of both the documentation and infrastructure changes.
- Cloud-Native Design: The IAM, EKS, and various AWS-specific Terraform modules indicate a design that leverages AWS managed services and enforces security best practices (e.g., using Auth0 and AWS Secrets Manager for access).

##### Relevant Technologies, Frameworks, and Tools
- Terraform for Infrastructure Provisioning (with modules for AWS configuration, clusters, networking, IAM, etc.).
- GitHub Actions and related CI/CD tooling for automation of tests, validation, and deployments.
- GitHub’s infrastructure for repository management, dependabot, and pull request reviews.
- Docker and VS Code Dev Containers for local development environments.
- Middleman (or similar static site generator) for technical documentation rendering.
- AWS Services such as EKS, EC2, S3, IAM, CloudTrail, Athena, Route53, among others.

##### Essential Elements
- Clear Labels: Name each component clearly (e.g., “Documentation Server,” “CI/CD Pipeline,” “Terraform – AWS EKS Cluster,” “Operational Scripts for Ingestion,” etc.).
- Annotation of Technologies: Where relevant, annotate components with the key technologies (e.g., “Terraform,” “AWS EKS,” “GitHub Actions,” “Middleman”) to offer a quick technical reference.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Documentation & Website Delivery
    subgraph "Documentation & Website Delivery"
        DOC["Documentation Source"]:::docs
        CONFIG["Tech Docs Configuration"]:::docs
        MIDDLEMAN["Middleman Preview Scripts"]:::docs
        PUB["Public Documentation Site"]:::external
    end

    %% CI/CD and Development Environment
    subgraph "CI/CD & Dev Environment"
        GHA["GitHub Actions Workflows"]:::ci
        DEV["Development Environment (.devcontainer)"]:::ci
    end

    %% Infrastructure-as-Code (Terraform) Modules
    subgraph "Infrastructure-as-Code Modules"
        TERA["Terraform Modules (AWS Infrastructure)"]:::infra
    end

    %% Operational Scripts
    subgraph "Operational Scripts"
        OPS["Operations Scripts"]:::ops
    end

    %% Architectural Documentation & ADRs
    subgraph "Architectural Documentation & ADRs"
        ADR["ADRs & Diagrams"]:::adr
    end

    %% Relationships
    DOC -->|"render"| MIDDLEMAN
    CONFIG -->|"configures"| MIDDLEMAN
    MIDDLEMAN -->|"generates"| PUB
    GHA -->|"publish_docs"| PUB
    GHA -->|"deploy_infra"| TERA
    GHA -->|"trigger_scripts"| OPS
    DEV -->|"enables"| GHA
    OPS -->|"monitors"| TERA
    ADR -->|"informs_docs"| DOC
    ADR -->|"informs_infra"| TERA
    ADR -->|"informs_ops"| OPS

    %% Click Events
    click DOC "https://github.com/ministryofjustice/analytical-platform/tree/main/source"
    click CONFIG "https://github.com/ministryofjustice/analytical-platform/blob/main/config/tech-docs.yml"
    click MIDDLEMAN "https://github.com/ministryofjustice/analytical-platform/blob/main/scripts/docs/local.sh"
    click GHA "https://github.com/ministryofjustice/analytical-platform/blob/main/.github"
    click DEV "https://github.com/ministryofjustice/analytical-platform/blob/main/.devcontainer"
    click TERA "https://github.com/ministryofjustice/analytical-platform/tree/main/terraform"
    click OPS "https://github.com/ministryofjustice/analytical-platform/tree/main/scripts"
    click ADR "https://github.com/ministryofjustice/analytical-platform/tree/main/source/documentation"

    %% Styles
    classDef docs fill:#f9c74f,stroke:#f9844a,stroke-width:2px;
    classDef ci fill:#90be6d,stroke:#43aa8b,stroke-width:2px;
    classDef infra fill:#577590,stroke:#277da1,stroke-width:2px;
    classDef ops fill:#f94144,stroke:#f3722c,stroke-width:2px;
    classDef adr fill:#277da1,stroke:#577590,stroke-width:2px;
    classDef external fill:#f0a500,stroke:#d17b00,stroke-width:2px;
```
