# wealdtech/hawk architecture

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

- Interactive diagram: https://gitdiagram.com/wealdtech/hawk
- Repository: https://github.com/wealdtech/hawk

## Overview

##### Project Type and Purpose
- This is a multi‐module Java library implementing the Hawk authentication protocol (v1.0).
- It provides:
- A core module with generic Hawk client/server APIs and configuration
- A Jersey‐specific client implementation
- A Jersey‐specific server implementation
- It is not a full application by itself, but a reusable SDK for Java services and clients that wish to use Hawk.

##### File Structure Analysis
- Top‐level build files: `build.gradle`, `settings.gradle`, Gradle wrapper, `.travis.yml`
- Modules:
- hawk-core/
- hawk-client-jersey/
- hawk-server-jersey/
- Each module follows standard Maven/Gradle layout under `src/main/java/...` and `src/test/java/...`.
- Core module contains domain classes (Hawk, HawkClient, HawkServer, credentials, configuration) and a Guice module.
- Client and server modules only contain Jersey filters and providers that plug into web apps.

##### Key Components
a. Core Module
– Classes: Hawk, HawkClient, HawkServer
– Config: HawkClientConfiguration, HawkServerConfiguration
– Credentials: HawkCredentials
– Guice support: HawkServerConfigurationModule
b. hawk-client-jersey
– Jersey Filter: `HawkAuthorizationFilter`
– Depends on core’s HawkClient APIs and configuration
c. hawk-server-jersey
– Jersey Filters and Providers:
· HawkAuthenticationFilter
· HawkAuthenticator
· HawkCredentialsProvider
· HawkPrincipalProvider
· HawkUnauthorizedFilter
– Glues Jersey’s request pipeline to core’s HawkServer
d. External Pieces (for example apps/tests)
– HTTP clients calling endpoints protected with Hawk
– HTTP servers exposing endpoints secured with Hawk
– Configuration files (JSON) used to bootstrap clients/servers

##### Relationships and Data Flow
- Client App → HTTP Request → HawkAuthorizationFilter (client‐jersey) → HawkClient (core)
- HawkClient signs the request → sends to remote Service
- HTTP Service receives request → HawkAuthenticationFilter (server‐jersey) → HawkServer (core)
- HawkServer verifies the signature → extracts credentials/principal → passes control to resource
- Any unauthorized or malformed requests are blocked by filters in server module

##### Architectural Patterns & Principles
- Modular, layered design: core abstractions + pluggable implementations
- Separation of concerns:
- Core handles protocol logic
- Jersey modules handle web framework integration
- Dependency injection with Guice (core provides a module)
- Single responsibility: filters only manage authentication/authorization

##### Detailed Steps for the Engineer
1. A high‐level canvas labeled “Hawk Java SDK”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Applications and HTTP
    ClientApp["Client Application"]:::external
    ServiceApp["Service Application"]:::external
    HTTP["HTTP Network"]:::external

    %% Configuration Data
    ConfigClient(["Client JSON Config"]):::data
    ConfigServer(["Server JSON Config"]):::data

    %% Core Module
    subgraph "hawk-core"
        Hawk["Hawk"]:::core
        HawkClient["HawkClient"]:::core
        HawkServer["HawkServer"]:::core
        HawkClientConf["HawkClientConfiguration"]:::core
        HawkServerConf["HawkServerConfiguration"]:::core
        HawkCred["HawkCredentials"]:::core
        GuiceMod["HawkServerConfigurationModule"]:::core
    end

    %% Jersey Client Integration
    subgraph "hawk-client-jersey"
        FilterClient["HawkAuthorizationFilter"]:::client
    end

    %% Jersey Server Integration
    subgraph "hawk-server-jersey"
        AuthFilter["HawkAuthenticationFilter"]:::server
        Authenticator["HawkAuthenticator"]:::server
        CredProv["HawkCredentialsProvider"]:::server
        PrincipalProv["HawkPrincipalProvider"]:::server
        UnauthFilter["HawkUnauthorizedFilter"]:::server
    end

    %% Data Flow
    ClientApp -->|HTTP Request| FilterClient
    FilterClient -->|uses| HawkClient
    HawkClient -->|signs request over| HTTP
    HTTP --> ServiceApp
    ServiceApp -->|HTTP Request| AuthFilter
    AuthFilter -->|uses| HawkServer
    HawkServer -->|verifies signature| ServiceApp

    %% Configuration Flow
    ConfigClient -.-> FilterClient
    ConfigClient -.-> HawkClient
    ConfigServer -.-> AuthFilter
    ConfigServer -.-> HawkServer

    %% Click Events for Core Module
    click Hawk "https://github.com/wealdtech/hawk/blob/develop/hawk-core/src/main/java/com/wealdtech/hawk/Hawk.java"
    click HawkClient "https://github.com/wealdtech/hawk/blob/develop/hawk-core/src/main/java/com/wealdtech/hawk/HawkClient.java"
    click HawkServer "https://github.com/wealdtech/hawk/blob/develop/hawk-core/src/main/java/com/wealdtech/hawk/HawkServer.java"
    click HawkClientConf "https://github.com/wealdtech/hawk/blob/develop/hawk-core/src/main/java/com/wealdtech/hawk/HawkClientConfiguration.java"
    click HawkServerConf "https://github.com/wealdtech/hawk/blob/develop/hawk-core/src/main/java/com/wealdtech/hawk/HawkServerConfiguration.java"
    click HawkCred "https://github.com/wealdtech/hawk/blob/develop/hawk-core/src/main/java/com/wealdtech/hawk/HawkCredentials.java"
    click GuiceMod "https://github.com/wealdtech/hawk/blob/develop/hawk-core/src/main/java/com/wealdtech/hawk/guice/HawkServerConfigurationModule.java"

    %% Click Events for Client Jersey Module
    click FilterClient "https://github.com/wealdtech/hawk/blob/develop/hawk-client-jersey/src/main/java/com/wealdtech/hawk/jersey/HawkAuthorizationFilter.java"

    %% Click Events for Server Jersey Module
    click AuthFilter "https://github.com/wealdtech/hawk/blob/develop/hawk-server-jersey/src/main/java/com/wealdtech/hawk/jersey/HawkAuthenticationFilter.java"
    click Authenticator "https://github.com/wealdtech/hawk/blob/develop/hawk-server-jersey/src/main/java/com/wealdtech/hawk/jersey/HawkAuthenticator.java"
    click CredProv "https://github.com/wealdtech/hawk/blob/develop/hawk-server-jersey/src/main/java/com/wealdtech/hawk/jersey/HawkCredentialsProvider.java"
    click PrincipalProv "https://github.com/wealdtech/hawk/blob/develop/hawk-server-jersey/src/main/java/com/wealdtech/hawk/jersey/HawkPrincipalProvider.java"
    click UnauthFilter "https://github.com/wealdtech/hawk/blob/develop/hawk-server-jersey/src/main/java/com/wealdtech/hawk/jersey/HawkUnauthorizedFilter.java"

    %% Click Events for Config Files
    click ConfigClient "https://github.com/wealdtech/hawk/blob/develop/hawk-core/src/test/resources/clientconfig-test1.json"
    click ConfigServer "https://github.com/wealdtech/hawk/blob/develop/hawk-server-jersey/src/test/resources/config-test.json"

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,color:#006064
    classDef client fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20
    classDef server fill:#fff3e0,stroke:#e65100,color:#e65100
    classDef external fill:#eceff1,stroke:#90a4ae,color:#37474f
    classDef data fill:#f3e5f5,stroke:#4a148c,color:#4a148c
```
