# nhsdigital/eligibility-signposting-api architecture

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

- Interactive diagram: https://gitdiagram.com/nhsdigital/eligibility-signposting-api
- Repository: https://github.com/nhsdigital/eligibility-signposting-api

## Overview

##### Project Type and Purpose
- This is a Python‐based microservice (“Eligibility Signposting API”) whose sole responsibility is to assess and signpost an individual’s vaccination eligibility.
- It is a backend API service, typically deployed as an AWS Lambda (or container) behind API Gateway, persisting data in DynamoDB and loading configurable rules from S3.

##### File Structure Insights
- **src/eligibility_signposting_api**
- views/ – presentation layer (HTTP endpoints)
- services/ – business logic layer (eligibility calculations, rule evaluation)
- repos/ – data access layer (DynamoDB repository, S3 rules reader)
- app.py – wiring module (dependency injection via WireUp)
- **infrastructure/**
– Terraform modules & stacks provisioning AWS resources: API layer, DynamoDB tables, S3 buckets, IAM roles & policies, VPC/networking, bootstrap.
- **tests/**
– unit, integration (including Lambda‐in-process tests), uses localstack via pytest-docker.
- **.github/** & **scripts/**
– CI/CD pipelines (GitHub Actions), linting, security scans, Makefile wrappers.

##### README Architectural Notes
- Adheres to Martin Fowler’s Separated Presentation → Service Layer → Repository layering.
- Uses Pydantic for models, WireUp for dependency injection.

##### Architectural Patterns & Design Principles
- **Layered Architecture**: clear separation of concerns (Presentation, Business, Data).
- **Dependency Injection** via WireUp for loose coupling & testability.
- **Configuration-as-Code**: Terraform modules & stacks for infra, parameterised by environment.
- **Testability**: localstack + pytest fixtures for full-stack integration tests.

## Diagram (Mermaid)

```mermaid
graph TB
    %% System Context
    subgraph "System Context"
        direction TB
        Client["NHS App / Client"]:::external
        Consumer["Postman / Consumer"]:::external
        API["Eligibility Signposting API"]:::system
        AWS["AWS"]:::external
    end

    Client -->|"HTTP Request"| API
    Consumer -->|"HTTP Request"| API
    API -->|"Deployed on"| AWS

    %% Container Diagram
    subgraph "Container Diagram"
        direction TB
        subgraph "AWS Infrastructure"
            direction TB
            APIGW["API Gateway"]:::aws
            Lambda["Python Lambda (app.py)"]:::aws
            DynamoDB["DynamoDB Table"]:::aws
            S3Bucket["S3 Bucket (rules)"]:::aws
            IAM["IAM Roles & Policies"]:::aws
        end
        subgraph "CI/CD Pipeline"
            direction TB
            GH["GitHub Actions"]:::cicd
            TF["Terraform"]:::cicd
        end
    end

    Client -->|"HTTPS POST /eligibility"| APIGW
    APIGW -->|"Invoke"| Lambda
    Lambda -->|"GetItem/PutItem"| DynamoDB
    Lambda -->|"GetObject"| S3Bucket
    Lambda -->|"Uses"| IAM

    GH -->|"runs pipelines"| TF
    TF -->|"provisions"| APIGW
    TF -->|"provisions"| DynamoDB
    TF -->|"provisions"| S3Bucket
    TF -->|"provisions"| IAM

    %% Component Diagram
    subgraph "Eligibility Lambda Function - Components"
        direction TB
        App["app.py\n(WireUp DI)"]:::code
        Config["config.py\n(error_handler.py)"]:::code
        subgraph "Presentation Layer"
            direction TB
            View["views/eligibility.py"]:::code
            ResponseModel["views/response_model/eligibility.py"]:::code
        end
        subgraph "Business Logic Layer"
            direction TB
            Service["services/eligibility_services.py"]:::code
            Operators["services/rules/operators.py"]:::code
        end
        subgraph "Data Access Layer"
            direction TB
            RepoElig["repos/eligibility_repo.py"]:::code
            RepoRules["repos/rules_repo.py"]:::code
            Factory["repos/factory.py\nrepos/exceptions.py"]:::code
        end
        subgraph "Models"
            direction TB
            ModelElig["model/eligibility.py"]:::code
            ModelRules["model/rules.py"]:::code
        end
    end

    Lambda -->|"loads"| App
    App -->|injects| View
    View -->|calls| Service
    Service -->|calls| Operators
    Service -->|calls| RepoElig
    Service -->|calls| RepoRules
    RepoElig -->|uses| DynamoDB
    RepoRules -->|uses| S3Bucket
    View -->|uses| ResponseModel
    App -->|reads| Config
    Service -->|uses| ModelElig
    Operators -->|uses| ModelRules
    App -->|wires| Factory

    %% Click Events
    click View "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/views/eligibility.py"
    click ResponseModel "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/views/response_model/eligibility.py"
    click Service "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/services/eligibility_services.py"
    click Operators "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/services/rules/operators.py"
    click RepoElig "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/repos/eligibility_repo.py"
    click RepoRules "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/repos/rules_repo.py"
    click Factory "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/repos/factory.py"
    click Factory "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/repos/exceptions.py"
    click App "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/app.py"
    click Config "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/config.py"
    click Config "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/error_handler.py"
    click ModelElig "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/model/eligibility.py"
    click ModelRules "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/src/eligibility_signposting_api/model/rules.py"
    click DynamoDB "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/infrastructure/modules/dynamodb/dynamodb.tf"
    click S3Bucket "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/infrastructure/modules/s3/s3.tf"
    click GH "https://github.com/nhsdigital/eligibility-signposting-api/tree/main/infrastructure/modules/bootstrap/tfstate"
    click TF "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/infrastructure/stacks/api-layer/eligibility_dynamodb.tf"
    click TF "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/infrastructure/stacks/api-layer/s3_buckets.tf"
    click TF "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/infrastructure/stacks/api-layer/iam_roles.tf"
    click TF "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/infrastructure/stacks/api-layer/iam_policies.tf"
    click TF "https://github.com/nhsdigital/eligibility-signposting-api/blob/main/infrastructure/stacks/api-layer/data.tf"

    %% Styles
    classDef external fill:#F3F4F6,stroke:#333,stroke-width:1px
    classDef system fill:#D1E8FF,stroke:#0366D6,stroke-width:2px
    classDef aws fill:#FFE5B4,stroke:#C75C02,stroke-width:1px
    classDef cicd fill:#E2F3E4,stroke:#2C662D,stroke-width:1px
    classDef code fill:#E8F1FF,stroke:#1A4680,stroke-width:1px
```
