How sensiblewood/open-banking-graphql works
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