# inwerejosic/bank_codes_api architecture

> Architecture diagram of the GitHub repository inwerejosic/bank_codes_api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inwerejosic/bank_codes_api
- Repository: https://github.com/inwerejosic/bank_codes_api

## Overview

#### Purpose and Runtime
A Rust/Axum HTTP service exposing static Nigerian bank-code data as JSON. It runs as an async server locally or in a Docker container; no database or third-party runtime service is indicated. Core artifacts: `Cargo.toml`, `src/main.rs`, `data.json`.

#### Application Bootstrap and Routing
`src/main.rs` is the executable entry point. It initializes application state, constructs the Axum router, registers the health, full-data, and query endpoints, and binds the HTTP listener (documented on port 3000). Route-to-handler control flow is centered on `src/main.rs` and `src/handlers.rs`.

#### Static Data Boundary
`data.json` is the authoritative bank dataset, containing bank codes, names, and categories. The application loads and exposes this data rather than querying a remote system or persistent database. Data parsing/storage responsibilities are separated into `src/db.rs`, with `data.json` as the input boundary.

#### HTTP API Layer
Request handling belongs in `src/handlers.rs`. The public surface is:
- `GET /`: health response.
- `GET /api/data`: serialized complete dataset.
- `POST /api/query`: accepts a JSON path and returns the selected value.

Handlers translate Axum requests into service calls and JSON HTTP responses, keeping HTTP concerns separate from lookup behavior. Paths: `src/handlers.rs`, `src/main.rs`.

#### Query and Domain Services
`src/services.rs` contains application-level data access/query behavior, notably dot-notation traversal such as `banks.0.name`. The primary flow is request JSON → handler → service path resolution over loaded JSON → result/error response. This is the main semantic boundary between transport logic and dataset traversal. Paths: `src/services.rs`, `src/handlers.rs`, `data.json`.

#### Shared Utilities and Error/Value Handling
`src/utils.rs` supports reusable logic needed by the API, likely including JSON/path-oriented helper behavior. It should remain below handlers/services in the dependency direction: handlers orchestrate requests, services implement domain operations, utilities provide generic support. Paths: `src/utils.rs`, `src/services.rs`.

#### Deployment Boundary
The service is containerized for Alpine-oriented, non-root deployment. `Dockerfile` defines the image build/runtime contract, while `docker-compose.yml` provides local container orchestration and port exposure. The application remains self-contained: deployment supplies compute/networking, and the static dataset is packaged or made available to the process. Paths: `Dockerfile`, `docker-compose.yml`, `.dockerignore`.

Main entry points: [`src/handlers.rs`](https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs) (Request handlers), [`src/main.rs`](https://github.com/inwerejosic/bank_codes_api/blob/main/src/main.rs) (Axum router), [`Dockerfile`](https://github.com/inwerejosic/bank_codes_api/blob/main/Dockerfile) (Container image), [`src/db.rs`](https://github.com/inwerejosic/bank_codes_api/blob/main/src/db.rs) (Loaded dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service Runtime"]
  node_cargo["Cargo package<br/>Rust manifest<br/>[Cargo.toml]"]
  node_main["Server bootstrap<br/>Axum executable<br/>[main.rs]"]
end

subgraph group_api["HTTP API"]
  node_router["Axum router<br/>route registry<br/>[main.rs]"]
  node_health["GET /<br/>health endpoint<br/>[handlers.rs]"]
  node_full_data["GET /api/data<br/>data endpoint<br/>[handlers.rs]"]
  node_query["POST /api/query<br/>query endpoint<br/>[handlers.rs]"]
  node_handlers["Request handlers<br/>Axum handlers<br/>[handlers.rs]"]
end

subgraph group_application["Data Access"]
  node_services["Query service<br/>domain service<br/>[services.rs]"]
  node_data_store[("Loaded dataset<br/>JSON data store<br/>[db.rs]")]
  node_dataset["Bank-code dataset<br/>static JSON<br/>[data.json]"]
  node_utils["JSON utilities<br/>shared utilities<br/>[utils.rs]"]
end

subgraph group_deployment["Container Deployment"]
  node_dockerfile["Container image<br/>Docker build"]
  node_compose["Local containers<br/>Compose orchestration<br/>[docker-compose.yml]"]
  node_dockerignore["Build context filter<br/>Docker ignore rules<br/>[.dockerignore]"]
end

node_cargo -->|"builds"| node_main
node_main -->|"constructs"| node_router
node_main -->|"initializes state"| node_data_store
node_router -->|"GET /"| node_health
node_router -->|"GET /api/data"| node_full_data
node_router -->|"POST /api/query"| node_query
node_health -->|"dispatches"| node_handlers
node_full_data -->|"dispatches"| node_handlers
node_query -->|"dispatches"| node_handlers
node_handlers -->|"delegates lookup"| node_services
node_handlers -->|"returns full data"| node_data_store
node_services -->|"traverses"| node_data_store
node_services -->|"uses"| node_utils
node_data_store -->|"loads"| node_dataset
node_dockerfile -->|"runs"| node_main
node_dockerfile -->|"packages"| node_dataset
node_compose -->|"builds and runs"| node_dockerfile
node_dockerignore -.->|"filters context"| node_dockerfile

click node_cargo "https://github.com/inwerejosic/bank_codes_api/blob/main/Cargo.toml"
click node_main "https://github.com/inwerejosic/bank_codes_api/blob/main/src/main.rs"
click node_router "https://github.com/inwerejosic/bank_codes_api/blob/main/src/main.rs"
click node_health "https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs"
click node_full_data "https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs"
click node_query "https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs"
click node_handlers "https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs"
click node_services "https://github.com/inwerejosic/bank_codes_api/blob/main/src/services.rs"
click node_data_store "https://github.com/inwerejosic/bank_codes_api/blob/main/src/db.rs"
click node_dataset "https://github.com/inwerejosic/bank_codes_api/blob/main/data.json"
click node_utils "https://github.com/inwerejosic/bank_codes_api/blob/main/src/utils.rs"
click node_dockerfile "https://github.com/inwerejosic/bank_codes_api/blob/main/Dockerfile"
click node_compose "https://github.com/inwerejosic/bank_codes_api/blob/main/docker-compose.yml"
click node_dockerignore "https://github.com/inwerejosic/bank_codes_api/blob/main/.dockerignore"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cargo,node_main toneBlue
class node_router,node_health,node_full_data,node_query,node_handlers toneAmber
class node_services,node_data_store,node_dataset,node_utils toneMint
class node_dockerfile,node_compose,node_dockerignore toneRose
```

## Components

### Service Runtime

- [Cargo package](https://github.com/inwerejosic/bank_codes_api/blob/main/Cargo.toml): Rust manifest · `Cargo.toml`
- [Server bootstrap](https://github.com/inwerejosic/bank_codes_api/blob/main/src/main.rs): Axum executable · Builds state and router, then binds the HTTP listener. · `src/main.rs`

### HTTP API

- [Axum router](https://github.com/inwerejosic/bank_codes_api/blob/main/src/main.rs): route registry · Registers health, data, and query endpoints. · `src/main.rs`
- [GET /](https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs): health endpoint · `src/handlers.rs`
- [GET /api/data](https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs): data endpoint · `src/handlers.rs`
- [POST /api/query](https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs): query endpoint · Accepts a JSON path and returns its selected value. · `src/handlers.rs`
- [Request handlers](https://github.com/inwerejosic/bank_codes_api/blob/main/src/handlers.rs): Axum handlers · Translates requests into service calls and JSON responses. · `src/handlers.rs`

### Data Access

- [Query service](https://github.com/inwerejosic/bank_codes_api/blob/main/src/services.rs): domain service · Resolves dot-notation paths over loaded JSON. · `src/services.rs`
- [Loaded dataset](https://github.com/inwerejosic/bank_codes_api/blob/main/src/db.rs): JSON data store · Parses and retains the static bank dataset. · `src/db.rs`
- [Bank-code dataset](https://github.com/inwerejosic/bank_codes_api/blob/main/data.json): static JSON · Authoritative Nigerian bank codes, names, and categories. · `data.json`
- [JSON utilities](https://github.com/inwerejosic/bank_codes_api/blob/main/src/utils.rs): shared utilities · `src/utils.rs`

### Container Deployment

- [Container image](https://github.com/inwerejosic/bank_codes_api/blob/main/Dockerfile): Docker build · Defines Alpine-oriented non-root runtime image. · `Dockerfile`
- [Local containers](https://github.com/inwerejosic/bank_codes_api/blob/main/docker-compose.yml): Compose orchestration · Runs the service with port exposure. · `docker-compose.yml`
- [Build context filter](https://github.com/inwerejosic/bank_codes_api/blob/main/.dockerignore): Docker ignore rules · `.dockerignore`

## Connections

- Cargo package → Server bootstrap: builds
- Server bootstrap → Axum router: constructs
- Server bootstrap → Loaded dataset: initializes state
- Axum router → GET /: GET /
- Axum router → GET /api/data: GET /api/data
- Axum router → POST /api/query: POST /api/query
- GET / → Request handlers: dispatches
- GET /api/data → Request handlers: dispatches
- POST /api/query → Request handlers: dispatches
- Request handlers → Query service: delegates lookup
- Request handlers → Loaded dataset: returns full data
- Query service → Loaded dataset: traverses
- Query service → JSON utilities: uses
- Loaded dataset → Bank-code dataset: loads
- Container image → Server bootstrap: runs
- Container image → Bank-code dataset: packages
- Local containers → Container image: builds and runs
- Build context filter → Container image: filters context