# sensiblewood/open-banking-graphql architecture

> Architecture diagram of the GitHub repository sensiblewood/open-banking-graphql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sensiblewood/open-banking-graphql
- Repository: https://github.com/sensiblewood/open-banking-graphql

## Overview

##### Project type and purpose
- This is an open-source code-generation tool that converts OpenAPI/Swagger definitions (specifically the UK Open Banking Account Information & Payment Initiation specs) into a GraphQL schema.
- It reads JSON Swagger files, maps primitives and enums to GraphQL types, applies naming conventions, and outputs a ready-to-use `.graphql` schema file.

##### File structure
Top level:
- .eslintrc.yml, .gitignore, package.json / lock → standard JS project config
- README.md → documentation & high-level overview
- dist/ → generated GraphQL schemas (`account-info.graphql`)
- lib/ → core library (`swagger-to-graphql.js`)
- scripts/ → build orchestrator (`generate.js`)
- src/ → source assets:
– specs/ → bundled Swagger JSON specs
– templates/ → GraphQL template fragments
- test/ → unit tests and fixtures

Build & CI clues:
- npm scripts: `build:account-info` triggers scripts/generate.js → uses lib → produces dist
- GraphQL Schema Linter runs as part of build

##### README for additional insights
- Describes mapping rules (primitives→scalars, enums→enum, inline schemas→named types)
- Next steps mention resolvers & further codegen phases
- Emphasis on pragmatic simplicity and future refactor

a. Main components
1. CLI / npm-script layer
2. Orchestration script (`scripts/generate.js`)
3. Core conversion engine (`lib/swagger-to-graphql.js`)
4. Input assets:
- Swagger JSON specs (`src/specs/*.json`)
- GraphQL templates (`src/templates/*.graphql`)
5. Output artifacts (`dist/*.graphql`)
6. Quality tools: GraphQL Schema Linter
7. Test suite (`test/`)

b. Relationships & dataflow
- User runs `npm run build:account-info` (CLI)
↳ invokes `scripts/generate.js`
↳ loads Swagger JSON from `src/specs`
↳ passes JSON into the converter in `lib`
↳ converter applies schema-mapping logic and templates
↳ writes generated `.graphql` to `dist`
↳ lints output via GraphQL Schema Linter
- Tests independently load test fixtures, run `lib` logic, assert outputs

c. Architectural patterns & design principles
- Modular codegen pipeline (clear separation between orchestration, core logic, templates)
- Template-driven code generation (allows easy customization)
- Convention-over-configuration for naming & mapping
- Single-responsibility: generator → schema assembly; linting → quality gate

d. Key technologies & frameworks
- Node.js & npm scripts
- JSON Schema / Swagger (source spec)
- GraphQL (target schema)
- GraphQL Schema Linter (output validation)
- Mocha/Chai or similar (inferred for test suite)

##### Detailed capture of essential elements
- Don’t just show “Generator”: decompose into sub-components (parser, mapper, template engine)
- Package.json → scripts entry points
- Test harness reading fixtures and invoking core logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Scripts Layer
    subgraph "CLI & Scripts"
        pkg["package.json\n(scripts)"]:::cli
        gen["generate.js"]:::orchestration
    end

    pkg -->|"runs build:account-info"| gen

    %% Input Assets
    subgraph "Input Assets"
        spec1["account-info-swagger.json"]:::input
        spec2["payment-initiation-swagger.json"]:::input
        template["account-info.graphql"]:::input
    end

    gen -->|"load specs"| spec1
    gen -->|"load specs"| spec2
    gen -->|"load templates"| template

    %% Core Conversion Engine
    subgraph "Core Conversion Engine"
        parser["Parser"]:::core
        mapper["Mapper"]:::core
        engine["Template Engine"]:::core
        converter["swagger-to-graphql.js"]:::core
        parser --> mapper
        mapper --> engine
        engine --> converter
    end

    spec1 -->|"parse JSON"| parser
    spec2 -->|"parse JSON"| parser
    template -->|"apply templates"| engine
    gen -->|"invoke"| converter

    %% Output Artifacts
    subgraph "Output Artifacts"
        output["account-info.graphql"]:::output
    end

    converter -->|"write file"| output
    output -->|"lint"| linter["GraphQL Schema Linter"]:::linter

    %% Tests
    subgraph "Tests"
        ttest["test/swagger-to-graphql.js"]:::test
        t_spec["test/data/specs/account-info-swagger.json"]:::test
        t_temp["test/data/templates/account-info.graphql"]:::test
        ttest --> t_spec
        ttest --> t_temp
        ttest --> converter
    end

    %% Future Extension
    subgraph "Future Extensions"
        resolvers["Resolvers Stage"]:::ext
    end
    converter -.-> resolvers

    %% Click Events
    click pkg "https://github.com/sensiblewood/open-banking-graphql/blob/master/package.json"
    click gen "https://github.com/sensiblewood/open-banking-graphql/blob/master/scripts/generate.js"
    click converter "https://github.com/sensiblewood/open-banking-graphql/blob/master/lib/swagger-to-graphql.js"
    click spec1 "https://github.com/sensiblewood/open-banking-graphql/blob/master/src/specs/account-info-swagger.json"
    click spec2 "https://github.com/sensiblewood/open-banking-graphql/blob/master/src/specs/payment-initiation-swagger.json"
    click template "https://github.com/sensiblewood/open-banking-graphql/blob/master/src/templates/account-info.graphql"
    click output "https://github.com/sensiblewood/open-banking-graphql/blob/master/dist/account-info.graphql"
    click ttest "https://github.com/sensiblewood/open-banking-graphql/blob/master/test/swagger-to-graphql.js"
    click t_spec "https://github.com/sensiblewood/open-banking-graphql/blob/master/test/data/specs/account-info-swagger.json"
    click t_temp "https://github.com/sensiblewood/open-banking-graphql/blob/master/test/data/templates/account-info.graphql"

    %% Styles
    classDef cli fill:#ffa500,stroke:#333,stroke-width:1px
    classDef orchestration fill:#ffdead,stroke:#333,stroke-width:1px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef input fill:#98FB98,stroke:#333,stroke-width:1px
    classDef output fill:#98FB98,stroke:#333,stroke-width:1px
    classDef linter fill:#FF6347,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef test fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef ext fill:#bbbbbb,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
